Skip to main content

API Conventions

Every resource in the API Reference follows the same conventions for listing, filtering, pagination, and lifecycle actions. This page describes the shared behavior once so each resource page can focus on what is specific to it.

Base URL and Authentication​

Use the base URL for your assigned region (see Environments & Regions), and send a Bearer token on every request (see Authentication):

Authorization: Bearer {access_token}
Content-Type: application/json

All resource paths are under the /v1 prefix, for example GET /v1/clients.

Listing and Pagination​

List endpoints (GET /v1/{resource}) return a JSON array of records and accept the same pagination and shaping parameters:

ParameterDefaultDescription
limit10Records per page. Values above 100 are capped at 100.
skip0Records to skip, for paging.
sortcreated_atField to sort by. A value that is not a field of the resource falls back to created_at.
sortDirectiondescasc or desc. Any other value falls back to desc.
fieldsall fieldsComma-separated list of fields to return (a sparse fieldset), for example fields=uuid,created_at. Unknown field names are ignored.

Page through a list by increasing skip in multiples of limit: ?limit=50&skip=0, then ?limit=50&skip=50, and so on. See Pagination for a worked example.

Counting​

Most resources expose a count endpoint that applies the same filters as the list endpoint but returns only a number, which is efficient for pagination math and dashboards:

GET /v1/{resource}/total

Response (200): a bare number, for example 42.

Filtering​

Each resource page lists its own filter parameters. Filters follow consistent rules:

  • Exact match: most filters match a field exactly, for example ?status=outstanding.
  • Partial match: text search filters match substrings, for example a client ?name= search.
  • Date ranges: paired _from and _to parameters bound a date field, for example ?due_from=2024-03-01&due_to=2024-03-31 on payments. The bounds are inclusive.
  • Boolean filters: a boolean filter activates only when set to a truthy value: 1, true, yes, or y. Setting it to 0 does not filter; use the parameter's opposite where one is provided (for example optout=1 rather than optin=0 on contacts).

Full-text search behavior is resource-specific: the parameter searches whichever field is most useful for that resource (for example, a payment's payment_reference or a contact's value). See each resource page for what its search matches.

Lifecycle: Archive, Delete, and Restore​

Records are not hard-deleted through the API. They move between three states:

ActionEffectReversible
Delete (DELETE /v1/{resource}/{uuid})Soft delete: sets deleted_at. Excluded from default lists.Yes, with restore
Archive (PUT /v1/{resource}/{uuid}/archive)Sets archived_at. Excluded from default lists. Suits records that are resolved or inactive.Yes, with restore
Restore (PUT /v1/{resource}/{uuid}/restore)Clears archived_at and deleted_at, returning the record to active lists.N/A

To include the hidden records in a list, use these filters, which are common across resources:

  • archived=1 returns only archived records.
  • trashed=1 returns only deleted records.

By default (without these filters), both archived and deleted records are excluded. Deleting or archiving a record generally also cancels any scheduled, unsent messages tied to it; the resource pages note where this applies.

Sync and Process​

Some resources expose a sync or process action that queues background work rather than changing the record directly, most often to rebuild the scheduled reminder messages for a record:

POST /v1/{resource}/{uuid}/sync
POST /v1/{resource}/{uuid}/process

Response (202): the work is accepted and runs asynchronously, so the effect (for example, rescheduled messages) appears shortly after the response, not within it.

References and UUIDs​

Records are identified by a uuid, but many endpoints also accept your own reference in place of the UUID:

  • Creating a linked record accepts either the related record's UUID or its reference, for example client (a UUID) or client_reference (your identifier) when creating a payment.
  • Some GET and PATCH endpoints accept a reference or a natural value in the path, for example a client by client_reference, or a contact by phone number or email address. The resource page notes where this is supported.

Setting your own reference on create (for example client_reference or payment_reference) makes later lookups and syncing with an external system straightforward.

Timestamps and Dates​

  • Timestamps such as created_at and updated_at are UTC, formatted YYYY-MM-DD HH:MM:SS.
  • Calendar dates such as a payment's due_at or an event's date are YYYY-MM-DD and are interpreted in the agency's timezone.

Provenance Fields​

Most records carry two provenance fields:

  • created_by: the email or UUID of the user or API client that created the record.
  • upload: the UUID of the file import associated with the record, when it is linked to one. Filter by it (?upload={uuid}) to review a batch imported over SFTP.

Caching​

Single-record GET responses are cached briefly. After you change a record through the API, the cache for that record is refreshed automatically, so a subsequent read reflects your change. Changes made outside the API can take a short time to appear.