Entities API

What this does

The Entities API lets a bot or external client see which entities (organisations) the calling user owns and switch the user's active_entity_id. Subsequent calls scoped to "active entity" data — invoices, bills, dashboards — then operate on the newly-selected entity.

When to use it

Use this endpoint for any user with multiple businesses. A typical flow is: list entities, present the chooser to the user, switch on selection.

Authentication and scopes

Requests must include Authorization: Bearer rly_your_key_here. Each endpoint requires one of:

entities:read — list entities owned by the user
entities:switch — set the active entity

Endpoints

List entities

GET /api/v1/entities

Returns every entity owned by the calling user, with the default entity first.

{
  "data": [
    { "id": "ent_abc", "name": "Acme Ltd", "is_default": true, "currency": "GBP" },
    { "id": "ent_xyz", "name": "Acme Trading",  "is_default": false, "currency": "GBP" }
  ]
}

Switch active entity

POST /api/v1/entities/switch

{ "entityId": "ent_xyz" }

Sets users.active_entity_id to entityId. Subsequent API calls (and the user's web session) operate against the chosen entity.

200 OK — returns { activeEntityId, entity }
404 not_found — the entity doesn't exist or isn't owned by this user
400 validation_error — entityId was missing or not a string

Test mode

Test-mode keys return { activeEntityId } with "test": true in the envelope without writing to the DB.