Create a legacy opportunity · Fieldmotion API

When to use this endpoint

Use Opportunity_new for the CRM1 Opportunities/customer quick-create dialogs. CRM2 layouts should use Opportunity_createData.

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
`userID`	Integer string	Yes	Assigned user ID after integer conversion. Presence is required; zero/nonexistent IDs are accepted.
`customerID`	Integer string	Yes	Customer ID after integer conversion. Presence is required; zero/nonexistent IDs are accepted.
`value`	Integer string	Yes	Opportunity value; decimals are truncated. Blank becomes zero.
`notes`	String	Yes	Stored notes text. A blank value is accepted.
`source`	Integer string	Yes	Lead-source ID after integer conversion.
`form_id`	Integer string	No	Opportunity-form ID; defaults to zero.
`status`	Integer string	No	Status ID; defaults to `1`. No status/transition validation occurs.
`createdDate`	Date/string accepted by strtotime	No	Creation calendar date. The handler appends the current server time using a legacy minute-format bug; omit it for the exact current epoch.

Example request

$created = FM_api('Opportunity_new', [
	'userID' => '18',
	'customerID' => '1042',
	'value' => '2500',
	'notes' => 'Replace reception lighting',
	'source' => '7',
	'status' => '1',
]);

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: userID"}`	`userID` is omitted.
`{"error":"missing or invalid parameter: customerID"}`	`customerID` is omitted.
`{"error":"missing or invalid parameter: value"}`	`value` is omitted.
`{"error":"missing or invalid parameter: notes"}`	`notes` is omitted.
`{"error":"missing or invalid parameter: source"}`	`source` is omitted.

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

Behaviour and edge cases

createdDate does not preserve the current minute. The appended format is H:m:s, where PHP m is the month number. A September request therefore uses minute 09, not the actual minute.

The handler validates only parameter presence. It does not check related rows, active/deleted state, the Opportunities feature, or add permission.
Creation sets cdate and last_edited, but leaves created_by at its database default and does not populate form/custom/meta values.

Side effects

Inserts one opportunity and invalidates the opportunities cache. It creates no generic audit entry, mention notice, or notification-service event.

See it in Fieldmotion

CRM1

The Opportunities page and the customer edit page’s quick-create control call this route.

CRM2

CRM2 uses Opportunity_createData for its layout-driven create dialog.

Related endpoints

Opportunity_createData supports the complete mapped CRM2 record and side effects.
Opportunity_get reads the legacy core fields.