API docs

Reference / Customers

Pause, resume or hand over a customer

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

status pauses or resumes the customer; the answer is the customer. While it is paused, Instant answers every message with a fixed sentence that the customer is paused, and runs no scheduled, background or event work; reads, decisions, uploads, connections and member changes work, and nothing is deleted. customer.paused or customer.resumed is posted to the webhook. ownerMemberId hands the ownership to that member and answers the customer with its members.

updateCustomer · This page as markdown

Example request

cURL

curl -X PATCH 'https://app.booksbyinstant.com/api/integrator/v1/customers/01900000-0000-7000-8000-000000000000' \
  -H "Authorization: Bearer $INTEGRATOR_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "active"
}'

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: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.INTEGRATOR_CREDENTIAL}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "status": "active"
  }),
});
const data = await res.json();

Python

import os
import requests

res = requests.patch(
    "https://app.booksbyinstant.com/api/integrator/v1/customers/01900000-0000-7000-8000-000000000000",
    headers={
        "Authorization": f"Bearer {os.environ['INTEGRATOR_CREDENTIAL']}",
    },
    json={
        "status": "active",
    },
)
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.

Request body

At most 4096 bytes.

Body application/json, required

object

Exactly one of status or ownerMemberId; both, or neither, is refused. status pauses or resumes the customer, and the same status again changes nothing. ownerMemberId hands the ownership to one of the customer's members, who must be an active admin.

send exactly 1 field · no other fields

  • status string

    One of active paused

  • ownerMemberId string · uuid

    The id of one of the customer's members, an active admin, who becomes its owner.

Example, built from the schema

{
  "status": "active"
}

Responses

200

The customer; with its members after a handover.

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

    Only after an ownerMemberId handover.

    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
      }
    }
  ]
}

400

The body is not one JSON object, or a field is invalid; error says which. Also when the body has both status and ownerMemberId, or neither.

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"
}

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

The Error object, as in 400.

404

id names nothing this caller can see. Also when ownerMemberId names no member of the customer.

Body application/json

The Error object, as in 400.

409

The new owner is not an active admin, or the company changed meanwhile: read it again.

Body application/json

The Error object, as in 400.

413

The body is over 4096 bytes.

Body application/json

The Error object, as in 400.

415

The body is not sent as application/json.

Body application/json

The Error object, as in 400.

5XX

Instant is temporarily unavailable. Retry later, with backoff.

Body application/json

The Error object, as in 400.