Fieldmotion API Getting started

Invoices

Retrieve invoices by ID

POST /a/Invoices_getById

Retrieve an allowed field subset for selected non-deleted invoices.

When to use this endpoint

Use this for small batch lookups where full invoice objects are unnecessary.

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
idsArray or JSON arrayYesInvoice IDs. Values are integer-coerced and deduplicated; zero is not removed.
fieldsArray or JSON arrayYesAny of id, notes, num, order_no, paid, total, cdate, and due_date. Unknown and duplicate fields are ignored.

Example request

$rows = FM_api('Invoices_getById', [
	'ids' => ['981', '982'],
	'fields' => ['id', 'num', 'total'],
]);

Example response

[
  {"id": "981", "num": "INV-981", "total": "120.00"}
]

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 parameter is absent.
{"error":"missing required parameter: fields"}Fields is absent.
{"error":"no fields selected"}No supplied field is allowed.

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

Behaviour and edge cases

  • An empty ID array returns an empty array.
  • Soft-deleted invoices and unknown IDs are omitted. Result order is database-dependent and not guaranteed to match input order.
  • Malformed JSON that does not become an iterable array is a legacy unsafe input and must not be sent.

See it in Fieldmotion

CRM1

Export and document widgets use this kind of selected-ID lookup.

CRM2

Export widgets call it to resolve selected invoices.

Related endpoints