Create an opportunity-status label through the mapped API

When to use this endpoint

Use the mapped creator when an integration needs the allocated label ID. Check existing choices first if duplicate labels matter, then read back the returned ID.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. The handler requires login but does not check a settings-page permission, role or record owner. All rows in this family belong to the authenticated tenant’s opportunity_statuses table.

Parameters

Parameter	Type	Required	Description
`name`	String	Yes	Trimmed, nonblank label, at most 100 Unicode characters. The same validation is used by every name writer.
`id / cdate / lastEdited`	Any	Forbidden	Server-owned identity and timestamps. Supplying any of these keys is rejected, rather than silently ignoring or overwriting it.

Example request

$status = FM_api('OpportunityStatus_createData', ['name' => 'Negotiation']);

Example response

{"ok":1,"id":1042}

Errors and unusual responses

Response	Condition
`{"error":"not logged in"}`	No authenticated tenant context is available. Invalid signed credentials can be rejected by the dispatcher before the handler runs.
`{"error":"missing or invalid parameter: name"}`	Missing, non-string or blank label.
`{"error":"parameter too long: name. max length 100 characters"}`	Trimmed label exceeds 100 characters.
`{"error":"read-only field: id"}`	An identity/timestamp key is supplied; the error names that key.
`{"error":"configuration write failed"}`	Primary insert/update or transactional history fails; the tenant transaction rolls back.
`{"error":"configuration read failed"}`	Target/tenant-owner lookup fails.
`{"error":"configuration transaction failed"}`	Transaction start/commit fails.
`{"error":"configuration operation failed"}`	Unexpected database/runtime failure; transaction is rolled back.

Legacy application errors may be returned with HTTP 200. Check the decoded response for error, not only the HTTP status.

Behaviour and edge cases

The insert and field-creation history commit in one tenant transaction. Failed persistence does not return ok.
cdate and last_edited are current Unix seconds. The supplied name is trimmed; names are not deduplicated and no default status is assigned.
No extra settings-page/role permission or tenant feature flag is checked. CRM2’s similarly titled settings use CommonList instead.
Returns integer ok and integer allocated id; read details afterwards for the final stored row.

Side effects

Inserts the label, requests the opportunity_statuses cache marker and writes checked generic creation history in the same transaction.
No email, notification, webhook or related opportunity rewrite is performed.

See it in Fieldmotion

CRM1

Open CRM1 Settings → General → Opportunity Statuses. pageSettingsOpportunityStatuses.js loads the legacy table, creates labels and saves inline name edits. CRM1 opportunity/customer screens and exports obtain the choices through OpportunityStatuses_list.

CRM2

CRM2’s Opportunity Statuses settings screen (pageOpportunitySettingsStatuses.js) uses CommonList/CommonLists with type=opportunityStatus instead, not this table. No direct CRM2 settings caller to this endpoint was found. Reproduce this contract with the example request; do not assume that changing it changes CRM2’s CommonList choices.

Related endpoints

OpportunityStatuses_list supplies picker labels.
OpportunityStatus_getRequestedDetails reads mapped fields.