SIGNALS Docs
Exit Reader View
100%
Theme

Reader View

Integration identities

External references, idempotent upserts, provider mappings and reverse lookups.

External references and upserts

Accounts, rentals, invoices, assets and catalogue items accept external_ref on create and update, return it on reads, and allow filter[external_ref][eq] lookups. This nullable string is at most 191 characters and unique within each resource type in the tenant. Omission leaves an existing value unchanged; explicit null clears it. Soft-deleted rows still reserve their reference.

Resource Upsert endpoint Token ability
Accounts PUT /api/v1/accounts/by-external-ref/{ref} accounts:write
Rentals PUT /api/v1/rentals/by-external-ref/{ref} rentals:write
Invoices PUT /api/v1/invoices/by-external-ref/{ref} invoices:write
Assets PUT /api/v1/assets/by-external-ref/{ref} assets:write
Catalogue items PUT /api/v1/catalogue_items/by-external-ref/{ref} catalogue-items:write

URL-encode the reference in the path. The path value takes precedence over a body external_ref. An unmatched reference uses the normal create contract and returns 201; an existing visible record uses the update contract and returns 200. Both return the normal {data, meta} resource envelope (meta is optional). The same permissions, required fields, version checks and lifecycle restrictions apply as on ordinary create/update. The OpenAPI export declares request-body fields for each upsert and describes which apply when creating or updating. Runtime validation uses the corresponding create or update contract. Invoices must be editable drafts. Asset upserts ignore catalogue_item_id and warehouse_id on the update branch; they cannot move an existing asset between them.

For example, create or update a company:

PUT /api/v1/accounts/by-external-ref/sync-company-42
Content-Type: application/json

{"name":"Festival Productions","account_type":"company"}

The resource is abbreviated here:

{"data":{"id":42,"name":"Festival Productions","external_ref":"sync-company-42"}}

Look it up without writing:

GET /api/v1/accounts?filter[external_ref][eq]=sync-company-42
{
  "data": [{"id":42,"name":"Festival Productions","external_ref":"sync-company-42"}],
  "meta": {"total":1,"per_page":20,"page":1,"last_page":1}
}

An upsert does not restore a deleted record. A reserved or duplicate reference returns 422; reconcile the existing identity before retrying. Upsert matching prevents creating a second live identity for the same reference; it does not bypass idempotency and concurrency rules.

Provider mappings

Use mappings when one Signals record has identities in several integration providers or external tenants. The supported parents are accounts, invoices, credit_notes and payments.

Operation Endpoint Result
List GET /api/v1/{parent}/{id}/integration-mappings 200, data array
Create POST /api/v1/{parent}/{id}/integration-mappings 201, data object
Remove DELETE /api/v1/{parent}/{id}/integration-mappings/{mapping} Empty 204
Reverse lookup GET /api/v1/integration-mappings 200, visible mappings in data

Reads require the parent's view permission, policy and read token ability; writes require its edit permission, policy and write ability. Payment writes use payments.record. Invoice mappings use the invoice view policy with invoices.edit and invoices:write, allowing issued invoices to be mapped without editing their financial contents.

POST /api/v1/invoices/81/integration-mappings
Content-Type: application/json

{"provider":"xero","external_id":"invoice-123","external_tenant_id":"org-7","meta":{"synced_at":"2026-11-04T09:30:00Z"}}
{
  "data": {
    "id":7,"ref":"integration_mapping:7","mappable_type":"invoice","mappable_id":81,
    "provider":"xero","external_id":"invoice-123","external_tenant_id":"org-7",
    "meta":{"synced_at":"2026-11-04T09:30:00Z"},
    "created_at":"2026-11-04T09:30:00+00:00","updated_at":"2026-11-04T09:30:00+00:00"
  }
}

Each mapping includes a stable ref in the form integration_mapping:{id}. The mapping's provider metadata is data.meta; it is part of the resource, distinct from root response metadata. provider is lowercased, at most 64 characters, starts with a letter or digit, and permits letters, digits, _, . and -. External and external-tenant IDs are at most 191 characters. Omit external_tenant_id when the provider has none; the response returns null. An external ID can identify at most one Signals record of a type within a provider and external tenant; a conflicting claim returns 422.

Reverse lookup

Provider and external-ID equality filters are required. Additional supported filters remain in effect after those identity fields are normalized. Optional tenant and type equality filters disambiguate the result:

GET /api/v1/integration-mappings?filter[provider][eq]=xero&filter[external_id][eq]=invoice-123&filter[external_tenant_id][eq]=org-7&filter[mappable_type][eq]=invoice

The response is a data array of the mapping objects shown above. mappable_type is account, invoice, credit_note or invoice_payment; mappable_id is the Signals primary key. Only records the caller may view are returned. Lookup examines at most 100 newest matching mappings before permission filtering. It is a bounded lookup, not a cursor-paged export. Nested mapping lists return the complete matching collection without pagination metadata.

Use incremental sync and webhooks to maintain the records behind these identities.