Create a mapped supplier · Fieldmotion API

When to use this endpoint

Use Supplier_createData when supplying the camel-cased fields from the supplier map. CRM2 reaches it indirectly through Layout_setValue when a Supplier Create layout is saved.

Use Supplier_new only for the smaller legacy CRM1 create dialog.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. The handler calls the normal login guard but performs no additional Suppliers-page, stock, purchasing, role, create, edit, or delete permission check.

All records are selected from the authenticated tenant. CRM1 and CRM2 hide some controls through client-side permissions, but these endpoints do not repeat those UI checks.

Parameters

Parameter	Type	Required	Description
`id`	Integer-compatible or array	No	Ignored for creation; the database assigns the ID.
`name`	String	Yes	Supplier name. It must be nonempty when creating through the mapped route.
`contactName, streetAddress1, streetAddress2, town, county, country`	String	No	Contact and address values. `country` maps directly to the tenant table’s three-character country column.
`postcode`	String	No	Maximum 20 characters.
`email`	Email string	No	Maximum 64 characters. A nonblank value must pass PHP email validation.
`phone`	String	No	Maximum 40 characters.
`notes`	String or notes JSON	No	Supplier notes. When the value is a notes array, newly added `@username` tokens can create Fieldmotion notices.
`website, terms, accountNumber, type`	String	No	Mapped supplier text fields. The mapped website field has no application-level 64-character limit.
`taxId`	String	No	Maximum 20 characters.
`refNumber`	String	No	Maximum 16 characters.
`isActive, onHold`	Integer-compatible	No	Converted with `intval()`. Conventionally use `0` or `1`.
`meta`	String	No	Complete raw metadata value. Prefer the named accounting fields when changing their keys.
`accountsContact, accountsEmail, additionalEmail`	String	No	Stored inside `meta` as `contact_accounting`, `email_accounting`, and `email_extra`. `accountsEmail` validates a nonblank email address.
`customValues`	JSON-compatible value	No	Stored in `custom_values`. Creation defaults it to an empty JSON object.
`createDate, lastEdited`	SQL datetime string	No	Default to the server’s current date and time on creation. Normal updates advance `lastEdited` automatically.
`editedUuid`	String	No	Mapped synchronization marker.

Example request

$supplier = FM_api('Supplier_createData', [
	'name' => 'Northshore Components',
	'contactName' => 'Aisling Byrne',
	'email' => 'orders@example.test',
	'accountsEmail' => 'accounts@example.test',
	'country' => 'IRL',
]);

Example response

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

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: name"}`	The required `name` field is absent or blank.
`{"error":"Invalid email address."}`	A mapped email field is nonblank but invalid.
`{"error":"email is too long."}`	A mapped value exceeds the maximum defined in the supplier map; the field name changes with the failing input.

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

Behaviour and edge cases

Only mapped camel-case fields are stored; unknown request fields are ignored.
No duplicate-name check is performed, unlike Supplier_new.
createDate, lastEdited, and customValues receive mapped defaults when omitted.

Side effects

Creates the tenant supplier row, clears the supplier cache, and writes field-level history entries.
Can create notices for newly mentioned users in structured notes.
Fires the configurable Supplier_new event after creation.

See it in Fieldmotion

CRM1

CRM1 does not call this mapped route; its Create dialog calls Supplier_new.

CRM2

Open Stock → Suppliers in CRM2 and filter browser developer tools for the exact function name. Choose Create and save the configured Supplier Create layout. The browser sends Layout_setValue, which dispatches internally to Supplier_createData.

Related endpoints

Supplier_getRequestedDetails reads the same mapped fields.
Supplier_updateData updates an existing mapped supplier.
Supplier_new is the narrower legacy creator.