Delete customers · Fieldmotion API

When to use this endpoint

Use Customer_delete only when customer records must be removed from normal Fieldmotion use. The operation preserves rows for historical integrity by setting the soft-delete fields, but it removes the customers from standard lookup endpoints and can affect integrations and recurring work.

Use Customer_disable when the record should remain available as an inactive customer that can later be reactivated.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session. Every linked API user must be active.

CRM1-style sessions, including signed API users that do not identify as CRM2, require permission bit 1. CRM2 sessions require delete permission for pageCustomers. The operation is limited to non-deleted customers in the authenticated tenant.

Parameters

Parameter	Type	Required	Description
`id`	Comma-separated integer string	Yes	One customer ID or a comma-separated batch such as `1042,1088`. Every comma-delimited item must convert to a positive ID for an existing non-deleted customer. Duplicate IDs are accepted and processed once.

Example request

$result = FM_api('Customer_delete', [
	'id' => '1042,1088',
]);

Example response

{
  "ok": 1
}

The response does not return a count or the IDs processed.

Errors and unusual responses

Response	Condition
`{"error":"no ID supplied"}`	`id` was omitted.
`{"error":"You do not have the correct permissions to delete a customer."}`	The authenticated CRM1/API or CRM2 user lacks the applicable delete permission. CRM1-style responses also include the numeric `permissions` value.
`{"error":"customer 0 does not exist"}`	The supplied string is empty or contains a blank/non-numeric/zero item.
`{"error":"customer 1042 does not exist"}`	A named ID does not exist or is already soft-deleted. The actual ID is included in the message.

All IDs are checked before deletion begins. A missing item prevents writes for the complete batch.

Behaviour and edge cases

The endpoint sets deleted=1, records Unix seconds in ddate, and updates last_edited. It does not physically remove the customer row.
Active and inactive customers can both be deleted. Already deleted customers fail validation.
Whitespace and non-numeric text around a valid integer follow PHP integer conversion. Avoid relying on that coercion; send canonical comma-separated decimal IDs.
Related jobs, invoices, assets, and other business records are not deleted by this handler. Existing references remain, although normal customer lookups stop returning the deleted customer.
The whole batch is validated first, but the subsequent side effects are not wrapped in one database transaction.

Side effects

Writes one tenant deletes entry per unique customer, including the customer name as deletion metadata.
Soft-deletes the customer rows and invalidates the customer cache.
Removes matching customer objects from the global accounting upload queue and tenant api_syncs mappings.
Removes upload-queue entries for invoices belonging to the deleted customers. It does not delete the invoices themselves.
Removes generated daily-archive customer-name caches so they can be rebuilt.

See it in Fieldmotion

CRM1

Open Customers, choose Delete, and filter the Network panel for Customer_delete. CRM1 first calls Customer_listJobs to warn about linked jobs, then requires the typed confirmation phrase before deleting.

CRM2

Open Customers and choose the dangerous Delete row action. CRM2 checks the customer's active state, archives active customers first, lists linked jobs for the warning, then calls Customer_delete after confirmation. Bulk deletion follows the same archive-before-delete workflow.

Related endpoints

Customer_disable is the reversible choice when a customer should be archived rather than deleted.
Customer_get returns “requested customer does not exist” after the soft delete.
Customers_listByLastEdited excludes deleted rows, so it cannot act as the deletion feed for this operation.