Get started
Authentication and keys
One header on every request. Partner keys are bound to a campaign; agency keys come from Settings.
You post a data lead. An AI voice agent calls it, follows up on a sequence we already configured, and warm-transfers qualified buyers to your licensed agents. You get dispositions, transcripts and recordings back. You do not provision campaigns, caller IDs or scripts: Entrovox runs those. You integrate two things, posting leads and receiving outcomes.
Base URL and format
| Base URL | https://api.entrovox.com/v1. Every path in these guides is relative to it. |
| Auth | Authorization: ApiKey sk_entrovox_…. We mint and bind a partner key; agencies create their own in Settings. |
| Format | JSON. Success is { "data": … }, and lists add meta. Errors are { "error": { "code", "message", … } }, so branch on code, not on the sentence. |
| Phone numbers | E.164, like +14255551234. |
Send the key on every request and keep it server-side:
curl "https://api.entrovox.com/v1/leads?external_id=hw-1" \
-H "Authorization: ApiKey $ENTROVOX_KEY"import os, requests
r = requests.get(
"https://api.entrovox.com/v1/leads",
params={"external_id": "hw-1"},
headers={"Authorization": f"ApiKey {os.environ['ENTROVOX_KEY']}"},
timeout=15,
)
print(r.status_code, r.json())const res = await fetch("https://api.entrovox.com/v1/leads?external_id=hw-1", {
headers: { Authorization: `ApiKey ${process.env.ENTROVOX_KEY}` },
});
console.log(res.status, await res.json());A missing or malformed header is 401 AUTHENTICATION_REQUIRED. A key that is not found or has the wrong format is 401 TOKEN_INVALID. A key past its expiry is 401 API_KEY_EXPIRED.
Partner keys
Partner keys we mint are bound to one campaign. You do not create campaigns or caller IDs, and the key already knows which campaign it posts to.
- You may omit
lead_source_idon writes. Naming a different campaign is403 LEAD_SOURCE_NOT_ALLOWED. - Call reads (
GET /v1/calls) are scoped to your campaign. POST /v1/callsis for agencies. A bound key gets403 CALLS_NOT_ALLOWED_ON_BOUND_KEY, and the AI voice agent, phone number and call stats routes are closed to it.- Your lead ids are unique per campaign. The same
external_idposted to another campaign is a separate lead.
Scopes
readscopeOptionalGET leads, calls and artifacts, plus ping.
writescopeOptionalEverything read can do, plus post, batch, pause and resume. write implies read.
A read key that tries to write is 403 INSUFFICIENT_SCOPE.
Agency keys
An agency creates its own keys to place calls and read their outcomes. In the console, go to Settings → API Keys → Create key, choose a permission tier and copy the key. It is shown only once.
| Tier | Can do | Mirrors |
|---|---|---|
| Read & write | Initiate calls, post, pause and resume leads, and read call and lead data | An admin |
| Read only | Read call and lead data only | A member |
Keys can carry an optional expiry and can be revoked at any time. A revoked or expired key stops working within about a minute. Once you have a key, place your first call.
An API key reaches only the public API surface. Any other path answers 403 API_KEY_ENDPOINT_NOT_ALLOWED, and so do the /webhooks routes today while webhook delivery is a preview.
What this API does not cover
Campaign setup, DID inventory, prompt edits, SIP and priced ping bids are out of scope. Entrovox operates those. POST /v1/calls is the agency one-shot dialer, and a campaign-bound partner key cannot use it.
Questions while you integrate: reply to the thread that included your key, or email the Entrovox contact who provisioned you.
Next steps
Post a live lead with your own ids, or read Compliance: what we enforce for what you certify before we activate your campaign.