# Change, deactivate or reactivate a member

`PATCH https://app.booksbyinstant.com/api/integrator/v1/customers/{id}/members/{memberId}`

A change of role or entity access takes effect on the member's next request; a chat turn already running ends. `active: false` deactivates the member and revokes their tokens for good; `active: true` reactivates them with their role and access, and new tokens must be issued.

operationId `updateMember`; tag Members.

## Example request

cURL:

```bash
curl -X PATCH 'https://app.booksbyinstant.com/api/integrator/v1/customers/01900000-0000-7000-8000-000000000000/members/01900000-0000-7000-8000-000000000000' \
  -H "Authorization: Bearer $INTEGRATOR_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "language": "en",
  "timezone": "Europe/Copenhagen",
  "role": "admin",
  "entityAccess": {
    "mode": "all"
  },
  "active": true
}'
```

JavaScript:

```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/members/01900000-0000-7000-8000-000000000000", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.INTEGRATOR_CREDENTIAL}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "string",
    "language": "en",
    "timezone": "Europe/Copenhagen",
    "role": "admin",
    "entityAccess": {
      "mode": "all"
    },
    "active": true
  }),
});
const data = await res.json();
```

Python:

```python
import os
import requests

res = requests.patch(
    "https://app.booksbyinstant.com/api/integrator/v1/customers/01900000-0000-7000-8000-000000000000/members/01900000-0000-7000-8000-000000000000",
    headers={
        "Authorization": f"Bearer {os.environ['INTEGRATOR_CREDENTIAL']}",
    },
    json={
        "name": "string",
        "language": "en",
        "timezone": "Europe/Copenhagen",
        "role": "admin",
        "entityAccess": {
            "mode": "all",
        },
        "active": True,
    },
)
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.
- `memberId` (string · uuid; required): The member's id.

## Request body

At most 32768 bytes.

`application/json`, required: object; send at least 1 field; no other fields

Send active alone (false deactivates the member, true reactivates them), or at least one of the other fields; the same values again change nothing. An admin has access to all entities, so role admin with a selection is refused, and a selection names entities of this customer only. A deactivated member's role and entity access change only after active: true; their name, language and time zone can still change. The owner stays an admin and is never deactivated, and the company keeps at least one admin.

- `name` (string; at least 1 character): The member's name: 1 to 120 characters after leading and trailing whitespace is removed. With two or more words, the last is the last name.
- `language` (string; one of `en`, `de`, `sv`, `nb`, `da`, `fr`, `es`, `pl`, `pt-BR`, `it`, `hr`, `tr`, `he`, `ar`, `ro`): One of Instant's languages.
- `timezone` (string; 1 to 100 characters): An IANA time zone.
- `role` (string; one of `admin`, `user`, `auditor`)
- `entityAccess` (one of 2 shapes): all: every entity of the customer, and it clears a selection. selected: the entities entityIds names.
  - either object
    - `mode` (string; required; always `all`)
  - or object
    - `mode` (string; required; always `selected`)
    - `entityIds` (array of string · uuid; required; at most 500 items; no repeated items): Up to 500 of the customer's entity ids, each at most once: the same id in upper and lower case counts as twice. An empty selection reaches no entity until one is added, so a restricted member can be created before the customer has an entity.
- `active` (boolean)

Example, built from the schema:

```json
{
  "name": "string",
  "language": "en",
  "timezone": "Europe/Copenhagen",
  "role": "admin",
  "entityAccess": {
    "mode": "all"
  },
  "active": true
}
```

## Responses

### 200

The member.

`application/json`: object

- `member` (object; required): A person in a customer, with a role and entity access.
  - `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; one of `admin`, `user`, `auditor`): admin manages the company and sees every entity, user works within their entities, auditor reads.
  - `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.
    - either object
      - `mode` (string; required; always `all`)
    - 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; at least `0`): How many of the member's tokens are active and unexpired, at most 20.

Example, built from the schema:

```json
{
  "member": {
    "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 `active` comes with another field, nothing is to change, `role` is admin with a selected entity access, or an entity id is not the customer's.

`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; at least `1`): Seconds to wait before retrying, also sent as the `Retry-After` header. Present only when there is a wait, as on a 429.
- `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:

```json
{
  "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"

`application/json`: the `Error` object, as in 400.

### 404

`id` or `memberId` name nothing this caller can see.

`application/json`: the `Error` object, as in 400.

### 409

The member is deactivated and must be reactivated first; the owner would stop being an admin or be deactivated; the company would have no admin left; or it changed meanwhile.

`application/json`: the `Error` object, as in 400.

### 413

The body is over 32768 bytes.

`application/json`: the `Error` object, as in 400.

### 415

The body is not sent as `application/json`.

`application/json`: the `Error` object, as in 400.

### 5XX

Instant is temporarily unavailable. Retry later, with backoff.

`application/json`: the `Error` object, as in 400.

---

Page: https://booksbyinstant.com/docs/update-member/ · Overview: https://booksbyinstant.com/docs/index.md