Update mapped opportunity fields

When to use this endpoint

Use Opportunity_updateData for CRM2 layout saves and inline edits. It accepts the same mapped keys as Opportunity_createData and changes only supplied fields.

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
`id`	Integer string	Yes	Target opportunity ID. The shared helper supports a native ID array for ordinary updates, but this wrapper’s quote/notice/notification logic assumes one ID; use one ID per call.
`user / customer / quoteID`	Native objects/arrays	No	Picker values with nested `id`, expanded to `userID`, `customerID`, or `quote`. The scalar aliases can be supplied directly.
`value / notes / status / source / type`	Mapped integer/text values	No	Core editable values. Status integer `3` triggers quote creation before the mapped update.
`formID / formValues / subformValues`	Integer / JSON-compatible values	No	Opportunity form and complete main/subform documents.
`widgetFormField`	JSON-compatible value	No	Copied to `formValues` and takes precedence over a separately supplied value.
`createDate / lastEdited`	Unix seconds or parseable datetime	No	Mapped epoch fields. Any actual change also refreshes `last_edited` to the current epoch, overriding a supplied historical value in the generated SQL.
`isStarred / reason / formID / createdBy / deleted`	Integer-compatible	No	Other mapped scalar fields. Read-only/hidden layout flags are not enforced server-side.
`customValues`	JSON-compatible value	No	Complete mapped custom-values document.
`metaCallback / metaCallbackNotes / metaJob`	Datetime / text / text	No	Values merged into the stored `meta` JSON object.
`noRecord / noRecordCustom`	Native arrays	No	Field/custom keys whose audit metadata should be hidden.
`_poll`	Any	No	Ignored before the mapped update.

Example request

$updated = FM_api('Opportunity_updateData', [
	'id' => '481',
	'value' => 2750,
	'notes' => [['text' => 'Repriced after survey']],
]);

Example response

{
  "ok": 1,
  "oldData": {
    "value": "2500",
    "notes": "Initial estimate"
  }
}

When status 3 creates a quote, the response also contains numeric quoteId. oldData includes only stored columns selected for supplied mapped fields and uses their first mapped aliases.

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: id"}`	`id` is absent. This is also returned before conversion when status is 3.
`{"warning":"no updated fields."}`	No supplied key maps to a writable stored field.
`{"warning":"No data.","oldData":[]}`	The ID has no non-deleted row for the selected mapped fields.
`{"warning":"No Change."}`	Mapped values compare equal after type/JSON normalization.
`Quote-creation error`	Status 3 was supplied and the quote helper rejected the opportunity’s user/customer or could not insert a quote.

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

Behaviour and edge cases

Every status-3 request attempts conversion first. The wrapper does not first check the current status/quote link. Re-sending status=3 can create another quote and replace the linked quote ID, even when the final status itself is unchanged.

Soft-deleted rows are excluded by the mapped helper. Unknown keys are ignored; numbers are converted to mapped numeric types; JSON documents are compared structurally.
Layout required/read-only flags are not general authorization. A supplied blank required quoted value is rejected, but related IDs, feature state, and CRM2 edit permission are not server-validated.
In a CRM2 session, the internal conversion returns the quote ID without first setting legacy status 2; the outer update stores status 3 and quote_id. Other session types may briefly write 2 before the outer write stores 3.
Warning/no-data responses still pass through the wrapper’s mention/notification calls using the submitted data, even though no mapped row changed.

Side effects

On change, updates mapped columns/last_edited, invalidates the opportunities cache, and writes per-field audit entries.
Scans notes-compatible submitted fields for newly mentioned users, then queues opportunity update/time notifications using normalized old/new notes.
Status 3 creates and audit-logs a draft quote before the mapped update.

See it in Fieldmotion

CRM1

CRM1 uses individual legacy setters rather than this mapped route.

CRM2

Layout create/edit, inline user/notes/status edits, callback saves, job-link creation, and Kanban moves all derive this route from table opportunity.

Related endpoints

Opportunity_updateField sets one mapped field across one/many rows with fewer side effects.
Opportunity_convertToQuote performs the quote creation used for status 3.