Reading records

Open in the interactive reference

A resource has up to three endpoints for reading, each for a different job:

• GET the collection to list records. Its records are often lighter than the full record. It is the only one that takes filters, sorting, field selection and paging in the query string; see Pagination and querying.
• GET a record by id for one full record.
• POST to search for many full records, with the filters in the request body. A search usually returns the same fields as GET by id; its endpoint shows exactly what it returns.

Not every resource has all three, and their filters differ: some text filters, such as a customer's name, exist only on search, and some structured filters only on the collection. Check the resource's endpoints for the filter you need.

A collection returns its records as the data array, with pagination beside it. A search returns them in data.items.

Only a collection refuses query parameters it does not declare. GET by id and search ignore them, so fields= on GET by id still returns the whole record.

You cannot ask an endpoint to include related records. A field such as customerId holds an id, and reading that customer is a second request, unless the record already embeds the details you need.

A collection query that matches nothing returns 200 with an empty data array, not 404.

Statuses and drafts

Each resource has its own status values, listed on its endpoints. When a description mentions records without naming a status, it means records in every status. When only some statuses count, the description names them.

Some records can be saved as a draft in the application. A record saved as a draft is not the same as a record whose status is 'draft', which is an ordinary record returned like any other. Get, list and search endpoints never return records saved as drafts, so reading one by its id answers NOT_FOUND. Some update, delete and status-change endpoints can still act on one by its id.

Examples

Three ways to read

GET  /accounting/customers
GET  /accounting/customers/{id}
POST /accounting/customers/search