Fieldmotion API Getting started

Contracts

Create a contract through the field map

POST /a/Contract_createData

Create a contract through CRM2’s mapped layout engine and publish its create notifications.

When to use this endpoint

Use Contract_createData from the CRM2 configurable Contracts list or Kanban workflow, where request keys follow the contract field map.

Use Contract_new when you need the older create contract, initial job links, or explicit name validation.

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
nameStringNoContract name, limited to 64 characters when supplied. Unlike Contract_new, this wrapper does not require it.
notesStringNoStored notes; defaults to an empty string. Mention syntax can create notices after insertion.
expiryDateDate stringNoMapped YYYY-MM-DD expiry. Blank, numeric NaN-like input, and exact NaN-NaN-NaN become null; other invalid dates are rejected by the shared mapper.
cDateDate-time stringNoCreation date-time; defaults to the current server time.
activeInteger stringNoStored status value. Omission leaves the table default, normally 1.
customersStringNoRaw cached customer/asset representation. This endpoint does not derive or validate it.
customValuesJSON object or arrayNoComplete mapped custom JSON value stored in custom; defaults to {}.
budgetNumberNoMapped floating-point contract budget.
number / address / managerStringsNoReference number, address, and manager fields.
typeID / createdByInteger stringsNoContract-type and creator IDs. createdBy is always replaced with the authenticated user ID.
dateStarted / dateCompletedDate / date-timeNoMapped lifecycle dates.
meta / metaHoursBudget / metaNotInvoiceable / metaStageJSON or mapped scalarNoThe supplied top-level meta is replaced with defaults: spend and hours-spent status ok and not_invoiceable="0". Nested mapped values may then modify those properties.

Example request

$created = FM_api('Contract_createData', [
	'name' => 'North Region Service Contract',
	'typeID' => '8',
	'budget' => '25000',
	'expiryDate' => '2027-09-30',
]);

Example response

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

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":"name has a maximum length of 64"}The shared mapped conversion rejects an overlong name. Exact wording can vary with mapper validation.
{"error":"invalid date parameter: expiryDate"}A nonblank mapped expiry is not a valid YYYY-MM-DD value.
{"error":"missing or invalid parameters."}No mapped value remains to insert; wrapper 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. The contract field map controls coercion, date validation, JSON storage, and the 64-character name limit.
  • The endpoint does not link jobs, derive customers/assets, require a name, or provide pagination.
  • The fixed metadata defaults differ from Contract_new, which begins with customersDirty=1.

Side effects

  • Inserts the tenant contract, writes generic field-level activity logs, and sets last_edited.
  • Sends mention notices found in mapped notes and publishes create/time notifications to the notifications service. These effects are not transactional with the insert.

See it in Fieldmotion

CRM1

No production CRM1 caller was found. CRM1 creates contracts through Contract_new.

CRM2

Open Contracts in CRM2, use the configurable create action or create a Kanban card, and filter Network requests for Contract_createData.

Related endpoints