API: account and operations

Everything on this page is bound to the key's account. General contract in How the API works.

An account cannot be created with a key

POST /accounts exists, but requires a global or client-level actor: a key is account-level, so it gets 403 accounts.actor_scope_not_allowed. Same for DELETE /accounts/:id and for activating/deactivating its own account (shared.self_scope_mutation).

Reading the account

GET /accounts
GET /accounts/:id

GET /accounts returns a single account: the key's. Accepted query: businessLine (eas/vending), isActive, search, page, pageSize (max 1000); clientId and accountId are ignored.

200 response:

{
  "items": [
    {
      "id": "665f0f1c2e8a4b0012a3b4c6",
      "clientId": "665f0f1c2e8a4b0012a3b4c5",
      "taxId": "900123456",
      "companyName": "ACME Bogotá",
      "location": { "country": "Colombia" },
      "contact": { "name": "Juan Pérez", "phone": "6015551234", "mobile": "3001234567", "email": "juan@acme.co" },
      "businessLines": ["vending", "eas"],
      "currency": "COP",
      "consumerTagKeys": ["departamento", "cargo"],
      "isActive": true,
      "createdAt": "2026-01-15T14:02:11.000Z",
      "updatedAt": "2026-08-01T09:31:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

Editing the account

PATCH /accounts/:id

Field	Type	Required	Notes
companyName	string	no	min. 2 characters
location.country	string	no	country name (Colombia), not ISO
contact.name / .phone / .mobile	string	no	—
contact.email	string	no	valid email

taxId, currency and businessLines cannot be changed. 200 with the full account; 400 if the body carries undeclared fields.

User tags

Up to 4 per account. They define which keys a user's tags may use.

POST   /accounts/:accountId/consumer-tag-keys      { "key": "Departamento" }
PATCH  /accounts/:accountId/consumer-tag-keys/:key { "newKey": "Sucursal" }
DELETE /accounts/:accountId/consumer-tag-keys/:key

POST returns 201 with the account. Renaming propagates the new name to every user that already had the tag; deleting removes it from all of them. Errors: 409 consumers.duplicate_tag_key, 400 consumers.too_many_tags, 404 consumers.unknown_tag_key.

Operations

POST   /operations
GET    /operations
GET    /operations/:id
PATCH  /operations/:id
PATCH  /operations/:id/deactivate
PATCH  /operations/:id/activate
DELETE /operations/:id

Create (201):

Field	Type	Required	Notes
clientId	string	yes	must be the key's
accountId	string	yes	must be the key's
name	string	yes	min. 2
location	object	yes	country, city, address, sublocation?, coordinates?
contact	object	yes	name, phone, mobile, email
businessLines	string[]	yes	non-empty subset of the account's

{
  "clientId": "665f0f1c2e8a4b0012a3b4c5",
  "accountId": "665f0f1c2e8a4b0012a3b4c6",
  "name": "Sede Norte",
  "location": { "country": "Colombia", "city": "Bogotá", "address": "Cra 15 # 3-17" },
  "contact": { "name": "Ana Ruiz", "phone": "6015551234", "mobile": "3009876543", "email": "ana@acme.co" },
  "businessLines": ["vending"]
}

PATCH /operations/:id accepts name, location and contact (same fields, all optional). Activate and deactivate answer 204 with no body. DELETE answers 204 and cascades: devices, profiles, codes of that operation and operators scoped to it; the ledger is kept.

List query: businessLine, isActive, search (name, city or contact), page, pageSize.

Own errors: 404 operations.not_found, 403 operations.actor_scope_not_allowed, 400 operations.business_line_not_in_account.