Getting started · Fieldmotion API

Create an API key

To use the Fieldmotion API, create an API key for the user the integration should act as.

In the Fieldmotion CRM, open Users, edit the user that needs API access, and select Create Key in the API Keys section. Keep the key secret. Requests run in that user's tenant and authentication context, and an inactive user cannot authenticate.

Sign each request

Fieldmotion API calls are HTTP POST requests containing form fields. To sign a request:

Build the endpoint's POST parameters.
Add _api_now containing the current Unix timestamp as a string.
JSON-encode that parameter object.
Append | and the API key to the JSON string.
Calculate the MD5 hash of the combined string.
Add that hash to the POST parameters as _api_md5.
Add _api_id containing the API key ID shown on the User page.
Form-encode and send the request to https://cpXX.fieldmotion.com/a/<FunctionName>.

Your assigned cpXX host is the host shown when you log in to the CRM; examples include https://cp12.fieldmotion.com/a/ and https://cp13.fieldmotion.com/a/. Responses are JSON.

Sign the exact string values you send. POST parameters are interpreted as strings. Convert integers and decimal values to strings before JSON encoding and calculating _api_md5, or the server's JSON representation may produce a different hash.

PHP example

This helper signs and sends a request, then lists users as a first call. Replace the placeholders with your assigned host and credentials.

<?php
$FMAPI = [
	'api_id' => '123',
	'api_key' => 'replace-with-your-api-key',
	'base_url' => 'https://cp13.fieldmotion.com/a/',
];

function FM_api($functionName, $post = []) {
	global $FMAPI;
	$post['_api_now'] = ''.time();
	$post['_api_md5'] = md5(json_encode($post).'|'.$FMAPI['api_key']);
	$post['_api_id'] = $FMAPI['api_id'];

	$ch = curl_init();
	curl_setopt_array($ch, [
		CURLOPT_URL => $FMAPI['base_url'].$functionName,
		CURLOPT_RETURNTRANSFER => true,
		CURLOPT_POST => true,
		CURLOPT_POSTFIELDS => http_build_query($post),
	]);
	$result = curl_exec($ch);
	curl_close($ch);

	return $result;
}

var_dump(FM_api('Users_list'));

The demonstration key is intentionally invalid. Do not commit a real API ID or key to source control.

Common authentication errors

Response	Meaning
`{"error":"API Key with that ID does not exist"}`	The `_api_id` is unknown or the key has been deleted.
`{"error":"Sent MD5 does not match calculated MD5", ...}`	The signed parameter JSON does not match the values the server received. Check scalar types, JSON encoding, and when authentication fields were added.
`{"error":"user account is not active"}`	The key exists, but its linked user is inactive.
`{"error":"not logged in"}`	The endpoint requires an authenticated user and the request did not establish one.

Legacy API errors are commonly returned as JSON response bodies rather than non-2xx HTTP statuses. Inspect the decoded payload before treating a request as successful.

Next steps

Use Short polling to keep another system up to date.
Call Customers_list to retrieve filtered customer records.
Fetch a selected batch with Customers_getById.

C# clients must use a network connection that supports TLS 1.2 or newer.