Fieldmotion API Getting started

Opportunities

Update one mapped opportunity field

POST /a/Opportunity_updateField

Set one mapped opportunity field to one value across one or more non-deleted rows.

When to use this endpoint

Use Opportunity_updateField for generic CRM2 autosave/bulk field controls. Use Opportunity_updateData when audit details, notices, notifications, composite values, or quote conversion matter.

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

ParameterTypeRequiredDescription
fieldMapped field keyYesOne of the opportunity map keys listed on Opportunity_getRequestedDetails. Hidden/read-only keys—including id, createdBy, and deleted—are not blocked.
valMapped scalar/JSON valueYesOne replacement value for every matched row. Use scalar aliases such as userID, customerID, and quote; composite picker keys do not unpack an object in this route.
idInteger string or native arrayOne of id or idsOne ID, or a native ID array. Takes precedence over ids.
idsInteger string or native arrayOne of id or idsAlternative target list. Values are integer-converted; supply at least one.

Example request

$updated = FM_api('Opportunity_updateField', [
	'ids' => [481, 482],
	'field' => 'isStarred',
	'val' => 1,
]);

Example response

{
  "ok": 1,
  "oldData": [
    {"id":"481","is_starred":"0"},
    {"id":"482","is_starred":"0"}
  ]
}

Errors and unusual responses

ResponseCondition
{"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: field"}field is absent.
{"error":"missing or invalid parameter: val"}val is absent.
{"error":"missing or invalid field"}The field key is not present in the opportunity map.
{"error":"missing or invalid parameter: id/ids"}Neither target parameter is present.
{"ok":"1","warning":"no change required"}No non-deleted target row exists or every stored value already compares equal.

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

Behaviour and edge cases

  • Soft-deleted target rows are excluded from the initial read. Numeric values are converted; blank JSON/datetime values become SQL NULL; nested metadata keys are merged one row at a time.
  • The response’s oldData contains raw id plus the underlying stored column (for metadata, the complete meta JSON), not mapped response aliases.
  • Setting status here does not create a quote and setting deleted here does not set ddate or create a deletion record.

Side effects

  • Updates changed rows, refreshes last_edited, invalidates the opportunities cache, and writes one generic audit entry naming the mapped field and comma-separated changed IDs.
  • Does not send mention notices or notification-service events.

See it in Fieldmotion

CRM1

No direct production CRM1 caller was found.

CRM2

The shared generic autosave helper can derive this route for opportunity fields, although the main opportunity module predominantly uses Opportunity_updateData.

Related endpoints