Documentation Industry-specific FieldMotion

Industry integration

FieldMotion

FieldMotion integration overview
  • CategoryIndustry
  • AuthSigned requests

Overview

FieldMotion is a UK field-service management CRM used by gas, HVAC and plumbing trades. On /integrations the FieldMotion card is marked Disabled by default; opening it shows the 'Connect FieldMotion' modal with two fields, API ID and API Key. MessageMind finds the right FieldMotion server for your tenant automatically from those credentials, then imports your customers (with their custom fields), keeps them in sync and merges duplicates rather than creating them. The integration acts AS the FieldMotion user whose API Key you pasted, so pick a user that can see every customer you want MessageMind to work with.

What MessageMind can do with it

  • Import your FieldMotion customers into MessageMind as contacts, including their custom field values.
  • Keep contacts in step going forward and merge duplicates against existing MessageMind contacts rather than creating a second record.
  • Discover which FieldMotion server (shard) hosts your tenant automatically from the API ID and API Key, so you never type it.
  • Append MessageMind-side contact edits to the matching FieldMotion customer as a fresh note next to the notes already in FieldMotion, so the field team's own notes are never blanked.
  • Track a background import job per tenant that you can poll for status through the dashboard.

Requirements

  • A FieldMotion account with an active API Key issued for a user who can see every customer you want MessageMind to work with.
  • The numeric API ID shown beside that key in FieldMotion.

How to connect

  1. In FieldMotion, go to Users, Edit user, Api Keys, and click Create Key. FieldMotion shows the 32-character key and its numeric API ID.
  2. In the MessageMind dashboard, open /integrations and click the FieldMotion card. The 'Connect FieldMotion' modal opens.
  3. Paste the API ID (for example '15') into the API ID field and paste the 32-character key into the API Key field.
  4. Click Integrate. MessageMind finds your FieldMotion server from those credentials and stores the connection.
  5. Once connected, MessageMind imports your customers, keeps them in sync every few minutes, and merges duplicates instead of creating them. You can check the import's progress against the fieldmotion/import-status endpoint behind the dashboard.

Authentication and permissions

Mechanism
Per-tenant API ID and API Key issued inside FieldMotion. The integration acts as the FieldMotion user that owns the key, with that user's visibility over customers. The FieldMotion server (shard) is resolved automatically from the credentials; you do not pick it.
Credentials
Two fields on the connect modal: a numeric API ID (e.g. '15') and the 32-character API Key. Both are stored on the integration document.

Available data and actions

Reads

  • Your FieldMotion customers, including their custom field values, during the initial import and on the ongoing sync.
  • The identity of the FieldMotion user the API Key belongs to, used to decide which customers this connection can see.
  • Import job progress, exposed to the dashboard through GET /v1/contact/fieldmotion/import-status/:jobId.

Writes

  • A new note on the matching FieldMotion customer when a linked MessageMind contact is edited. The note is appended next to the FieldMotion team's existing notes; MessageMind never overwrites fields that only the FieldMotion operator maintains.
  • An idempotency guard that compares the previous note snapshot to the current one, so two near-simultaneous MessageMind saves do not post the same text to FieldMotion twice.

AI agent use cases

  • A trade (gas, HVAC or plumbing) running FieldMotion wants its customer book mirrored into MessageMind so the AI can greet a returning customer by name and update the right record.
  • An engineer's phone number already exists in FieldMotion; when that customer messages, MessageMind matches on the existing record and merges rather than creating a duplicate.
  • The AI captures a new detail during a conversation; the change is posted to FieldMotion as a new note on the customer, visible to the field team alongside their own notes.

Configuration

  • The modal exposes two fields only: API ID and API Key. There is no server or region selector; MessageMind resolves the FieldMotion server from the credentials.
  • The FieldMotion-side user whose key you paste decides visibility. If a customer is not visible to that user in FieldMotion, it is not visible to the integration.
  • The connector is available on the Starter, Professional and Enterprise plans.

Example workflows

First import

  1. You paste the API ID and API Key in 'Connect FieldMotion' and click Integrate.
  2. MessageMind resolves your FieldMotion server from the credentials and enqueues a FieldMotion import job for your tenant through confirmFieldMotionImport.
  3. The job walks your FieldMotion customers (and their custom fields) and lands them as MessageMind contacts, merging duplicates against existing contacts rather than creating a second record.
  4. The dashboard polls GET /v1/contact/fieldmotion/import-status/:jobId for progress; if an import is already running when you reconnect, that same job is returned instead of a second one being started.
  5. Ongoing sync continues from there in the background every few minutes.

MessageMind edit to a linked customer

  1. A linked MessageMind contact is edited (by a human or by the AI).
  2. updateFieldMotionContact is called with the contact and the pre-edit note snapshot (previousNote).
  3. The edit is posted to FieldMotion as a new entry next to the notes already on the customer; fields that only the FieldMotion operator maintains are left alone.
  4. If a second save races the first, the previousNote guard stops MessageMind sending the other save's text to FieldMotion a second time.

Limitations

  • The card is shipped Disabled; the connection is only live once you paste a valid API ID and API Key in 'Connect FieldMotion' and the server probe succeeds.
  • The integration acts AS the FieldMotion user that owns the API Key. Customers hidden from that user in FieldMotion are hidden from MessageMind too.
  • MessageMind-side edits reach FieldMotion as a new note on the customer, not as field-by-field writes. This is the chosen pattern so a MessageMind edit never blanks fields the FieldMotion operator maintains.
  • Only one FieldMotion import runs per tenant at a time. Re-triggering the import while one is already in progress returns the existing job rather than starting a second.

Troubleshooting

The connect form does not accept my credentials.

Re-open FieldMotion, go to Users, Edit user, Api Keys, Create Key, and copy both the 32-character key and the numeric API ID beside it. Paste both back into the 'Connect FieldMotion' modal. The key must still be active in FieldMotion.

The dashboard says no enabled FieldMotion integration was found for this user.

The confirmFieldMotionImport endpoint only runs for a tenant that has an enabled FieldMotion connection. Reconnect the FieldMotion card first; the import can then be enqueued.

I retried the import and it did not start a new one.

That is on purpose: if a FieldMotion import is already in progress for your tenant, confirmFieldMotionImport returns 'FieldMotion import already in progress' and the existing job id, so you can keep polling the same /fieldmotion/import-status/:jobId.

A customer I expected to see is missing from MessageMind.

The integration acts as the FieldMotion user that issued the API Key. If that user cannot see the customer in FieldMotion, MessageMind cannot either. Pick (or create) a FieldMotion user that can see every customer you want in MessageMind and reconnect with that user's key.

A note from MessageMind looks posted twice on a FieldMotion customer.

updateFieldMotionContact carries the pre-edit note (previousNote) specifically to stop two near-simultaneous MessageMind saves posting the same text to FieldMotion a second time. If you see a true duplicate, confirm both edits actually went through MessageMind and not partly through FieldMotion directly.

Disconnect and reconnect

  • In the MessageMind dashboard, open /integrations and choose Disconnect on the FieldMotion card. The API ID, API Key and the resolved FieldMotion server are removed from your tenant and ongoing sync stops.
  • FieldMotion itself keeps its customers, custom fields and notes untouched; disconnecting does not delete anything in FieldMotion.
  • To reconnect, paste the API ID and API Key again in 'Connect FieldMotion'. The server is re-resolved on the first authenticated call; if an import is already running, the existing job is returned instead of a second one being started.