Fieldmotion API Getting started

Contracts

List contracts by name

POST /a/Contracts_listByNames

Resolve exact submitted contract names to active stored IDs for CSV import mapping.

When to use this endpoint

Use Contracts_listByNames during an import that contains contract names but needs IDs before saving another object.

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
namesJSON array stringYesArray of strings. Every item must already be a string; values are not trimmed, normalized, or deduplicated.

Example request

$matches = FM_api('Contracts_listByNames', [
	'names' => json_encode(['North Region Service Contract', 'National Support']),
]);

Example response

[
  {"id": "720", "name": "North Region Service Contract"},
  {"id": "731", "name": "National Support"}
]

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 parameter: names"}The key is omitted.
{"error":"invalid parameter: names"}The value is malformed JSON or does not decode to an array.
{"error":"invalid name string","name":...}Any decoded item is not a string; the first invalid value is echoed.

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 non-deleted contracts are returned. Active/completed and expired/non-expired rows are all eligible.
  • The SQL uses exact IN values under the tenant collation; it defines no response order and does not preserve input placeholders for missing names.
  • An empty array is valid and normally returns []. There is no pagination or explicit batch limit.

See it in Fieldmotion

CRM1

Import another object with a Contract-name mapping. CRM1’s import widget calls Contracts_listByNames while translating distinct names.

CRM2

CRM2’s shared import widget uses the same endpoint for contract-name translation.

Related endpoints