Read a customer

GEThttps://app.booksbyinstant.com/api/integrator/v1/customers/{id}

readCustomer · This page as markdown

Example request

cURL

curl -X GET 'https://app.booksbyinstant.com/api/integrator/v1/customers/01900000-0000-7000-8000-000000000000' \
  -H "Authorization: Bearer $INTEGRATOR_CREDENTIAL"

JavaScript

// Node 18 or later, in an ES module (.mjs), which allows the top-level await.
const res = await fetch("https://app.booksbyinstant.com/api/integrator/v1/customers/01900000-0000-7000-8000-000000000000", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.INTEGRATOR_CREDENTIAL}`,
  },
});
const data = await res.json();

Python

import os
import requests

res = requests.get(
    "https://app.booksbyinstant.com/api/integrator/v1/customers/01900000-0000-7000-8000-000000000000",
    headers={
        "Authorization": f"Bearer {os.environ['INTEGRATOR_CREDENTIAL']}",
    },
)
data = res.json()

Authorization

Bearer token live_<100 hex>

Authorization: Bearer <secret>. A 401 answers WWW-Authenticate: Bearer realm="instant-integrator-api".

Path parameters

id string · uuid required

The customer's id.

Responses

200

The customer and its members, oldest first.

Body application/json

object

customer object required

A customer: a company in Instant that the integrator created.
- id string · uuid required
  
  The customer's id.
- reference string required
  
  The integrator's own reference for the customer.
- status string required
  
  paused while the integrator has paused the customer.
  
  One of active paused
- country string or null required
  
  The customer's ISO 3166-1 alpha-2 country code, in capitals, or null when none is recorded.
- createdAt string · date-time required
  
  When the customer was created. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- pausedAt string · date-time or null required
  
  When the customer was paused, or null while it is active. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
members array of object required

Each item
- id string · uuid required
  
  The member's id.
- reference string required
  
  The integrator's own reference for the member, unique across all its customers.
- name string required
  
  The member's name.
- role string required
  
  admin manages the company and sees every entity, user works within their entities, auditor reads.
  
  One of admin user auditor
- owner boolean required
  
  True for the one member who owns the customer.
- language string or null required
  
  The member's language: one of the language values the requests take, or null when none is set.
- timezone string or null required
  
  The member's IANA time zone, or null when none is set.
- active boolean required
  
  False while the member is deactivated.
- joinedAt string · date-time required
  
  When the member joined the customer. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- deactivatedAt string · date-time or null required
  
  When the member was deactivated, or null while active. ISO 8601 in UTC with milliseconds, such as 2026-11-06T10:00:00.000Z.
- entityAccess one of 2 shapes required
  
  Which of the customer's entities the member works in: all of them, or a selection. An admin always has all. A deactivated member shows the selection that reactivating them restores.
  1. Either object
    - mode string required
      
      always all
  2. Or object
    - mode string required
      
      always selected
    - entityIds array of string · uuid required
      
      The entity ids of the selection, sorted.
- tokens object required
  - active integer required
    
    How many of the member's tokens are active and unexpired, at most 20.
    
    at least 0

Example, built from the schema

{
  "customer": {
    "id": "01900000-0000-7000-8000-000000000000",
    "reference": "string",
    "status": "active",
    "country": "string",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "pausedAt": "2026-01-15T09:30:00.000Z"
  },
  "members": [
    {
      "id": "01900000-0000-7000-8000-000000000000",
      "reference": "string",
      "name": "string",
      "role": "admin",
      "owner": true,
      "language": "string",
      "timezone": "string",
      "active": true,
      "joinedAt": "2026-01-15T09:30:00.000Z",
      "deactivatedAt": "2026-01-15T09:30:00.000Z",
      "entityAccess": {
        "mode": "all"
      },
      "tokens": {
        "active": 0
      }
    }
  ]
}

401

The credential is missing, malformed, unknown, revoked or rotated, or its integrator is disabled. All of these answer the same way.

Headers

WWW-Authenticate string

Bearer realm="instant-integrator-api"

Body application/json

object Error

Every answer that is not a success.

error string required

Instant's sentence for people. A 4xx keeps the refusal's own sentence; a 5xx always says "Instant is temporarily unavailable. Please try again shortly."
code string required

Stable, and what a caller branches on: VALIDATION_ERROR (400), UNAUTHENTICATED (401), FORBIDDEN (403), NOT_FOUND (404), CONFLICT (409), LIMIT_EXCEEDED (413), UNSUPPORTED_MEDIA_TYPE (415), UNREADABLE_FILE (422), RATE_LIMITED (429) and UNAVAILABLE (5xx). More codes may be added; treat one you do not know by its status.
retryAfter integer

Seconds to wait before retrying, also sent as the Retry-After header. Present only when there is a wait, as on a 429.

at least 1
existingId string · uuid

On a 409 that names the object already there, such as a customer with that reference: its id.

Example, built from the schema

{
  "error": "string",
  "code": "VALIDATION_ERROR",
  "retryAfter": 1,
  "existingId": "01900000-0000-7000-8000-000000000000"
}

404

id names nothing this caller can see.

Body application/json

The Error object, as in 401.

5XX

Instant is temporarily unavailable. Retry later, with backoff.

Body application/json

The Error object, as in 401.