Query the CRM2 invoice table · Fieldmotion API

When to use this endpoint

Use this for CRM2 invoice tables and generic mapped-data consumers. Requested columns use the invoice field map.

Authentication and permissions

The request must authenticate with signed API-key fields or a logged-in CRM session and is scoped to the authenticated tenant.

By default the handler also requires view access to pageInvoices. Passing roleCheck=0 skips that page-permission check; tenant authentication still applies.

Parameters

Parameter	Type	Required	Description
`fields`	Array	Yes	Mapped invoice columns to return.
`start / length / draw`	Integers	As required by the shared data processor	Pagination offset, page size, and optional draw token.
`order / search / advanceSearch`	Structured arrays	No	Shared mapped-table ordering and filtering. Legacy nominal IDs in `nominalCode` searches are translated to codes.
`roleCheck`	Integer-compatible	No	Defaults to 1. Set to 0 to bypass only the `pageInvoices` permission check.
`searchField / searchValue`	Strings	No	Special status-name search supporting prefixes of Draft, Quoted, Invoiced, Paid, or Cancelled.
`paid`	Numeric-compatible	No	Exact owing-before-credit filter (`total-paid`). The value is converted to a floating-point number.
`customer`	Customer/asset picker value	No	Mapped customer filter; picker IDs and types are integer-normalized and may be expanded by the following parameters.
`childJobAndAsset`	Array of 0, 1, or 2	No	For selected customers, include child customers (0), owned/located assets (1), or replace selection with those assets (2).
`assetOwner`	Picker object	No	Additional owner customer appended to the customer filter.

Example request

$table = FM_api('Invoices_getDataTable', [
	'fields' => ['id', 'num', 'status', 'total', 'paid'],
	'start' => 0, 'length' => 25,
]);

Example response

{
  "draw": 0,
  "recordsTotal": 148,
  "recordsFiltered": 25,
  "data": [{"id": 981, "num": "INV-981", "status": 1, "total": 120, "paid": 0, "qbRemoteID": "", "xeroRemoteID": ""}]
}

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":"permission denied"}`	Role checking is enabled and the caller lacks invoice-page view permission.
`{"error":"missing or invalid parameter: fields"}`	The shared processor rejects the requested fields.

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

Behaviour and edge cases

Non-admin users can be restricted to customers allowed by department-based and/or account-manager-based page filters; owned assets are included with those customers.
Status text search is converted to its numeric status; an unknown term produces no rows.
When credit notes are enabled, each row gains creditAllocated, credit_allocated, and credit-adjusted owing. Nominal codes are normalized.
QuickBooks and Xero remote IDs are tenant-instance-specific. Status-4 credit-note rows use credit synchronization links; other statuses use invoice links.

See it in Fieldmotion

CRM1

CRM1 uses the positional Invoices_getDT route.

CRM2

The invoice module configures its main and selection tables with this endpoint.

Related endpoints

Invoices_getSyncProvidersByIds resolves provider badges in bulk.