Create a mapped opportunity · Fieldmotion API

When to use this endpoint

Use Opportunity_createData for CRM2 layout-driven creation. CRM1’s compact dialog uses the narrower Opportunity_new route.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler performs no additional page or role-permission check.

The lookup and any write use the authenticated tenant; an ID from another tenant cannot be addressed through this call.

Parameters

Parameter	Type	Required	Description
`user`	Native object/array	Yes	Assigned user picker value, normally `["id"=>18]`. The nested `id` becomes `user_id`; malformed shapes can pass required validation yet store the database default/null.
`customer`	Native object/array	Yes	Customer picker value, normally `["id"=>1042]`. Only the nested ID is stored.
`source`	Integer-compatible	Yes	Lead-source ID. Presence is required, but zero and nonexistent IDs are not rejected.
`value / notes / status / type`	Integer / text / integers	No	Core values. Status defaults to `1`; omitted value/notes use their database defaults.
`formID / formValues / subformValues`	Integer / JSON-compatible values	No	Opportunity form and saved field data. Arrays/objects are JSON-encoded; JSON strings are normalized by the shared helper.
`widgetFormField`	JSON-compatible value	No	CRM2 alias copied to `formValues`, taking precedence over a separately supplied `formValues`.
`quoteID`	Native object/array	No	Quote picker value such as `["id"=>9021]`. The nested ID becomes `quote_id`.
`isStarred / reason`	Integer-compatible	No	Stored flags/reason values after integer conversion.
`createDate / lastEdited`	Unix seconds or parseable datetime	No	Mapped epoch fields. Both default to the current epoch; supplied nonnumeric values are parsed with `strtotime`.
`createdBy`	Integer-compatible	No	Defaults to the signed-in user. Although layouts mark it read-only, the helper accepts an explicit override.
`customValues`	JSON-compatible value	No	Layout custom values; defaults to an empty JSON object.
`metaCallback / metaCallbackNotes / metaJob`	Datetime / text / text	No	Keys merged into the opportunity `meta` JSON object.
`deleted`	Integer-compatible	No	Mapped soft-delete flag. The generic helper accepts it even though normal creation should omit it.
`noRecord / noRecordCustom`	Native arrays	No	Audit-hiding controls. `noRecordCustom` checks custom keys as intended; `noRecord` is affected by a legacy stale-variable bug and does not reliably check each mapped field key.

Example request

$created = FM_api('Opportunity_createData', [
	'user' => ['id' => 18],
	'customer' => ['id' => 1042],
	'value' => 2500,
	'notes' => 'Replace reception lighting',
	'source' => 7,
]);

Example response

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

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: user"}`	`user` is absent.
`{"error":"missing or invalid parameter: customer"}`	`customer` is absent.
`{"error":"missing or invalid parameter: source"}`	`source` is absent.
`{"error":"missing or invalid parameters."}`	No mapped/default field can be prepared for insertion. Defaults normally prevent this response.

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

Behaviour and edge cases

Unknown request keys are ignored. Numeric mapped fields are integer-converted; text is stored as supplied; blank JSON/date values become SQL NULL.
The mapped type field depends on the tenant having the corresponding opportunity schema upgrade.
The public embedded-form workflow also calls this function internally after it validates its configured actor, customer mode, status, source, and optional form.

Side effects

Inserts one opportunity, invalidates its cache, and writes per-field creation audit entries—including defaults.
Sends mention notices found in notes-compatible fields and queues opportunity create/time notifications.

See it in Fieldmotion

CRM1

CRM1 does not call this route from its Opportunities page.

CRM2

The layout-driven Create Opportunity dialog calls this route. Public embedded forms can call the same function internally under their configured audit user.

Related endpoints

Opportunity_new is the narrower CRM1 create route.
Opportunity_updateData updates mapped fields with similar conversions.