Docs
API Reference

Customer records

Read the named sheets of information kept on a customer

A customer record is a named sheet of information on a customer: Wi-Fi networks, Microsoft 365 users, printers, alarm codes, licences. It has columns and rows. With layout: "fields" it is one row shown top to bottom; with layout: "table" it has many rows.

The API reads records. They are created and edited in the Servicebay app.

Endpoints

  • GET/organisations/{orgId}/customers/{customerId}/records — List a customer's records
  • GET/organisations/{orgId}/customers/{customerId}/records/{recordId} — Get one record

A scope you have to choose

These endpoints need customer-records:read. No bundle includes it: a key or an OAuth grant with read, write or full cannot read customer records, and neither can a legacy key without scopes. Tick Customer records when you create or edit the key (or request the scope by name in an OAuth authorization) to grant it. Existing keys and connected apps did not gain it when it was added.

Secret values are never returned

Any column can be marked secret (passwords, alarm codes, licence keys). The API never returns a secret value:

  • a row's values holds the non-secret columns only;
  • a row's secretSet lists the secret columns that have a value in that row, so you can tell a filled secret from an empty one.

To read a secret, reveal it in the Servicebay app, where the reveal is logged.

{
  "id": "REC_ID",
  "name": "Wi-Fi",
  "layout": "table",
  "columns": [
    { "id": "ssid", "name": "Network", "type": "text", "secret": false },
    { "id": "password", "name": "Password", "type": "text", "secret": true }
  ],
  "rows": [
    { "id": "r1", "values": { "ssid": "Office" }, "secretSet": ["password"] }
  ]
}

Values are strings. A date column is YYYY-MM-DD; a yesNo column is yes or no. Column type is one of text, longText, url, email, phone, ipAddress, number, date, yesNo, pickList (with options).

deviceId is set when the record is also shown on one of the customer's devices. Deleting a customer deletes their records.

Machine-readable version: OpenAPI spec.