Fieldmotion API Getting started

Invoices

Export invoices

POST /a/Invoices_getExportData

Select invoice IDs and return requested invoice-level export columns.

When to use this endpoint

This is a two-phase export API. Send _ids=1 to obtain the complete filtered ID list, then send JSON-encoded ID and field arrays in one or more data requests. Neither phase paginates internally.

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.

The handler performs no additional invoice page, record-owner, or department permission check unless stated below.

Parameters

ParameterTypeRequiredDescription
_idsStringYesLiteral 1 starts selection; otherwise a JSON array of selected invoice IDs.
fieldsJSON arrayData phaseExport column keys. Supported invoice columns include account/customer/type, dates, creator, form, number/order, totals/tax/owing/paid, status, notes, rows, nominal/tax codes, parent, invoice range, latest paying user, job ID via the legacy appointment_id wire key, and FORM_ID:FIELD_NAME custom-form keys.
from / toDate stringsNoSelection-phase inclusive invoice-date bounds.
inv_no / inv_id / customer / search / orderNo / notesString or integerNoSelection-phase number, ID, customer/asset, broad search, order-number, and notes filters.
status / statusFilter / overdue / recurringMixedNoExact or multi-status, overdue, and recurrence filters.
form_id / formIDs / createdBy / quoteIDMixedNoExact or array filters for form, creator, and quote.
customerID / customerType / customersListMixedNoExact customer/asset target or an array of {id,type} targets. Exact target takes precedence.
referenceDateField / dateFromFilter / dateToFilter / isDateUnixMixedNoGeneric range filter over cdate, due_date, id, last_edited, or published.

Example request

$selection = FM_api('Invoices_getExportData', ['_ids' => '1', 'status' => '1']);
$rows = FM_api('Invoices_getExportData', [
	'_ids' => json_encode($selection['ids']),
	'fields' => json_encode(['num', 'customer_id|customer_type', 'total', 'owing']),
]);

Example response

[
  {"invoice_id": "981", "invoice_customer_type": "0", "f0": "INV-981", "f1_0": "55", "f1_1": "0", "f2": "120.00", "f3": "120.00"}
]

Selection returns {"ids":[...]}. In data rows, requested fields are named by zero-based position: f0, f1, and so on; combined customer/type fields become fN_0 and fN_1.

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 or invalid parameter: _ids"}The phase selector is absent.
{"error":"_ids should be a JSON array of numbers"}A data-phase ID list is empty or invalid.
{"error":"fields should be an array of requested field names"}Fields is not a nonempty JSON array.
{"error":"unknown field name: …"}A non-custom key is unsupported.
{"error":"invalid customersList"}The target list is malformed or contains no usable entry.

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

Behaviour and edge cases

  • Selection excludes soft-deleted invoices and legacy orphan drafts, orders IDs by numeric invoice number, and does not paginate.
  • Order-number and notes filters are case-insensitive literal substring searches; quotes and other SQL-significant characters are escaped rather than interpreted.
  • Customer-name expansion honors invoice-customer-filter-include-sites and invoice-customer-filter-includes-owned-and-located-assets. Credit allocations reduce exported owing when accounting_credit_notes=1.
  • Asset invoice customer IDs are normalized to the asset owner when that field is requested. Rows are normalized through the invoice row loader; custom form fields are returned only for the invoice’s form.
  • The job ID export deliberately reads the first direct link rather than the old invoice column.

See it in Fieldmotion

CRM1

The invoice export dialog names this function as its invoice-level export provider.

CRM2

The invoice module uses the same two-phase export contract.

Related endpoints