Intervoce Seat Management API

A small REST API that lets your own bot manage the user list (seats) of your Intervoce customer account: list, add and remove email addresses. A machine-readable OpenAPI 3.1 specification is available at /api/public/v1/openapi.json.

1. Get an API key

The account's customer administrator signs in at intervoce.com.
Opens Profile → API for bots.
Creates a named key and copies it — it is shown only once.

Keys look like ivk_ followed by 48 hex characters. A key can be blocked at any time from the same page, which takes effect immediately.

2. Authenticate

Authorization: Bearer ivk_your_key_here

3. Endpoints

`GET https://intervoce.com/api/public/v1/seats` — list seats

curl -H "Authorization: Bearer $KEY" https://intervoce.com/api/public/v1/seats

→ 200 { "seats": [ { "email": "anna@company.com", "name": "Anna",
                     "joined": false, "is_admin": false } ] }

`POST https://intervoce.com/api/public/v1/seats` — add seats

curl -X POST -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{ "seats": [ { "email": "anna@company.com", "name": "Anna" } ],
        "dryRun": true }' https://intervoce.com/api/public/v1/seats

→ 200 { "ok": true, "added": ["anna@company.com"] }

`DELETE https://intervoce.com/api/public/v1/seats` — remove seats

curl -X DELETE -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{ "emails": ["anna@company.com"], "dryRun": true }' https://intervoce.com/api/public/v1/seats

→ 200 { "ok": true, "removed": ["anna@company.com"], "skippedAdmins": [] }

4. Rules and limits

The key only ever touches the seat list of the account that created it — never calls, transcripts, advice, documents, voice profiles, balance or billing.
Added addresses must belong to the account's own domains. Domains are set by Intervoce and cannot be changed via the API.
Customer administrators cannot be removed via the API; they appear in skippedAdmins.
At most 500 rows per call and 50 removals per 24 hours.
Every call accepts "dryRun": true to preview the result without changing anything.
Everything the bot does is written to the account's change log (visible under Profile → API for bots), with time and key name.

5. Errors

Status	Meaning
`401`	Missing, malformed, invalid or revoked key
`400`	Malformed body, or more than 500 rows
`422`	Rule violated — e.g. email outside the account's domains, or the daily removal limit reached. The response body names the rejected addresses.

6. Responsibility

Changes made with your keys are considered to be made by your customer administrator. Store keys securely and block them immediately if they may have been compromised.