Retrieve invoice status tuples for jobs

When to use this endpoint

Load compact invoice status/email/reference/due-date tuples for job-list invoice icons.

Authentication and permissions

Authenticate with signed API-key fields or a logged-in CRM session. These calls use the authenticated account’s data; the handler has no additional job-page, department, assignee or client-admin permission check unless stated below.

The same finance restriction as Invoice_get applies: crm_access bit 64 denies access before any invoice/link query. The endpoint does not additionally restrict jobs by assignee or department.

Parameters

Parameter	Type	Required	Description
`ids`	JSON-encoded array or native array	Yes	A list of positive integer IDs or integer strings. Malformed JSON, objects, scalar values and invalid members are rejected. IDs are converted to integers and deduplicated; an empty list returns [].

Example request

$statuses = FM_api('Jobs_getInvoiceStatuses', ['ids' => json_encode(['1042', '1088'])]);

Example response

{"1042":["0",null,"INV-0042","1792396800"],"1088":["1","2026-10-10 09:00:00","INV-0043",null]}

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":"no permission to access api"}`	The authenticated user has the finance restriction bit set.
`{"error":"missing or invalid parameter: ids"}`	ids is absent, not a list or contains an invalid member.
`{"error":"could not read job invoice links"}`	The direct-link read fails.
`{"error":"could not read job invoice statuses"}`	The invoice read fails.

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

Behaviour and edge cases

Returns an object keyed only by requested job IDs, omitting jobs with no active invoice. An empty result is []. No active-job existence check or paging applies; nondeleted invoices and direct type-3 links are used.
Every tuple is [status,email_sent,num,due_date], including legacy matches. Values are copied from the saved invoice: due_date is Unix seconds/null and email_sent is a datetime/null.
Active explicit links take precedence over legacy pointers. When more than one active invoice is linked, the lowest invoice ID is selected consistently. Legacy fallback is always considered, including when links are duplicated or point only to deleted invoices; among legacy matches the lowest active invoice ID wins.
Duplicate request IDs and duplicate links do not change selection. A linked invoice’s legacy owner is returned only if that owner was also requested and has no higher-precedence explicit match.
Read failures return errors rather than partial status maps. This is a read-only lookup: it does not call Job_invoiceGet, hydrate customer snapshots, convert links, create invoices, send mail or change payments.

Side effects

Releases the PHP session write lock after authentication and nonempty-list validation. No database writes occur.

See it in Fieldmotion

CRM1

Open the Jobs list. pageJobs.js sends JSON.stringify(appids) after drawing rows and uses returned tuples to paint invoice icons and overdue indicators.

CRM2

No direct CRM2 network call was found. Jobs_getDataTable calls this helper internally when building invoiceList, so inspect the parent mapped-table request.

Related endpoints

Job_invoiceGet returns a full invoice/editor model rather than compact tuples.
Invoice_get documents the full saved-invoice payload.