Create an opportunity-status label using the legacy CRM1 form

When to use this endpoint

Use the CRM1 settings Create form, then reload the table or lookup. The legacy response omits the allocated ID; choose createData when the ID is needed.

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

$result = FM_api('OpportunityStatus_new', ['name' => 'Negotiation']);

Example response

{"ok":"1"}

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 string ok and no ID; duplicate labels make name-only follow-up lookup ambiguous.

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. Choose Create, enter a name and save; the form sends this endpoint, then reloads the 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.