Fieldmotion API Getting started

Opportunities

Set opportunity form values

POST /a/Opportunity_setFormValues

Replace the complete main-form values JSON document for one opportunity.

When to use this endpoint

Use Opportunity_setFormValues for CRM1’s form-data editor. It does not update subform values.

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
idInteger stringYesPositive opportunity ID.
valuesJSON object/array stringYesComplete replacement document. It must decode to a PHP array; a native request array is not accepted by json_decode.

Example request

$result = FM_api('Opportunity_setFormValues', [
	'id' => '481',
	'values' => json_encode(['field-1' => 'Yes']),
]);

Example response

{
  "ok": 1
}

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: id"}The ID integer-converts below one.
{"error":"missing or invalid parameter: values"}The string is absent, malformed JSON, or decodes to a scalar/null.
{"error":"opportunity does not exist"}No opportunity—deleted or otherwise—has that ID.
Runtime type errorvalues is sent as a native array/object rather than a JSON string.
{"ok":1,"warning":"nothing to do"}The compact JSON encoding is byte-for-byte equal to the stored form_values string.

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

Behaviour and edge cases

  • Both JSON objects and arrays are accepted because both decode to PHP arrays. The submitted document replaces, rather than merges with, the stored document.
  • The lookup does not exclude soft-deleted opportunities. Equivalent JSON with different key order/formatting can still be rewritten.

Side effects

  • Updates only form_values. It does not update last_edited, invalidate the opportunities cache, write audit history, or send notifications.

See it in Fieldmotion

CRM1

Click the form-data icon in an Opportunities row, edit a main form field, and CRM1 sends the complete main-field object here.

CRM2

CRM2 saves form values through the mapped widgetFormField/formValues path instead.

Related endpoints