Phase 2 — API integration

This phase keeps your system and Voicebot in step. A customer appears on your side, an account appears here, and the two stay matched for as long as both exist. Your engineers write that loop once.

Optional in scale, not in substance

Every integration needs the resources below. Automating them is what this phase adds. With nothing to synchronise, one administrator creates the same resources once — in the Account Panel or with a handful of calls — and this page becomes a checklist rather than a build.

Step 1 — Authenticate

The key from phase 1 is a bearer credential. Send it on every request:

Authorization: Bearer <your key>

There is no exchange step and no token to refresh: the key is what authenticates.

Treat it as you would any other production secret. It belongs in your secret store, never in source control, and it reaches your service the way the rest of your credentials do.

Key	Opens
Tenant key	every account in your tenant
Account key	the one account it was issued for

We issue a key with an expiry — a year, for a service integration — and revoke it on request before then. Revoke and reissue if one is ever exposed.

Done when GET/v1/internal/account answers under that key.

Step 2 — Mirror your resources

Four resources cross the boundary. All four work the same way: something happens in your system, you call the matching operation here, and the two records stay joined by an identifier you choose.

You keep your own identifiers

Set external_id to your own primary key when you create a resource. It is unique on our side, so a repeated create is rejected rather than quietly forking into two records, and you can read, update and delete by it without storing our sid anywhere.

Accounts

One per organisational unit on your side: a department, a brand, a region, or a customer of yours.

POST/v1/internal/account
PATCH/v1/internal/account/{sid}
DELETE/v1/internal/account/{sid}
GET/v1/internal/account

Users

The people who sign in to that account. An account needs at least one.

POST/v1/user
PATCH/v1/user/{sid}
DELETE/v1/user/{sid}
GET/v1/user

Numbers

An identifier the account places and answers calls on. It is an alphanumeric value carried in a SIP URI, not necessarily a dialable telephone number.

POST/v1/number
PATCH/v1/number/{id}
DELETE/v1/number/{id}
GET/v1/number

Number pools

Only if you group numbers. A pool widens the inbound side: an agent bound to one answers on every active number in it.

Membership lives on the number rather than on the pool — you attach and detach by patching the number’s pool_sid, not by calling the pool.

POST/v1/number-pool
PATCH/v1/number-pool/{id}
DELETE/v1/number-pool/{id}
GET/v1/number-pool

Done when every resource on your side has a counterpart here, a change on your side reaches it, and a deletion on your side removes it.

Step 3 — Sign your users in

Neither shape below gives your people a second password to remember. Pick one and apply it uniformly.

Magic link

You issue a one-time link for a user and hand it to them: your system redirects them straight into the panel, or delivers the link however it already reaches that person.

POST/v1/user/{sid}/magic-link/request
POST/v1/auth/magic-link/consume

The link is a credential while it is in transit. How it travels matters as much as the fact that it expires.

Provisioned credentials

You create the user and drive a password reset; the person then signs in with an email address and a password.

POST/v1/user/{sid}/password-reset/request
POST/v1/auth/regular

Use this where a redirect is not possible.

Either a tenant key or that account’s own key can issue the link. Identity and access covers the rest.

Done when one of your people has signed in for real and last_login_at comes back set from GET/v1/user.

Step 4 — Validate

Work through both against a real account rather than a scratch one.

Resources synced

Everything your system created here, and the changes it makes afterwards.

#	Check	How
1	every account on your side has a counterpart here	GET/v1/internal/account
2	numbers registered	GET/v1/number
3	numbers grouped into pools	GET/v1/number-pool
4	a change on your side reaches here	PATCH/v1/number/{id}
5	a deletion on your side removes the counterpart here	DELETE/v1/number/{id}

A user signs in

The pass that matters: a user you created signs in and reads their own profile.

#	Check	How
1	that user can be issued a one-time link	POST/v1/user/{sid}/magic-link/request
2	consuming it returns a session	POST/v1/auth/magic-link/consume
3	the session reads its own profile	GET/v1/profile

The profile answers with that user, the account they belong to, and the features enabled for it, so a successful call confirms the whole chain in one request.

Passing both is what opens phase 3, however the resources were created.