Using the Allison Voice Public API

If you want to read or write your Allison Voice data from your own scripts, server-side code, automation tools, or another system, the Allison Voice public REST API is the answer. Anything you can do on your dashboard (read calls, manage knowledge, create contacts, etc.), an external program can do via the API with the right key and scope.

For the conceptual "how do I connect Allison to HubSpot / Slack / Salesforce" walkthroughs, see Connecting via API and Zapier. This article covers the API itself — how to get a key, what the scopes mean, the limits, and where the reference docs live.

Where to find it

• API key management: Dashboard → Settings → API Keys
• Full reference (interactive): docs.allisonvoice.com
• Base URL: https://api.allisonvoice.com/v1/...

Creating an API key

1. Go to Settings → API Keys in the dashboard
2. Click Create API key
3. Name the key (e.g., "Zapier integration", "Production sync") — this is just for your reference
4. Pick the scope: Read or Read + Write
5. Confirm
6. Copy the plaintext key immediately. You'll only see it once. After you close the dialog, only the prefix (e.g., av_live_abc123...) is shown.

If you lose a key, revoke it and create a new one — there's no way to recover the plaintext after the create dialog closes. This is intentional security behavior.

Sensitive operations require fresh authentication

API key creation and deletion are sensitive actions. The dashboard requires you to re-enter your password or 2FA code before completing them, even if you signed in recently. This protects against stolen-session attacks where someone with temporary access to your account could quietly mint a long-lived API key.

Scopes

Two scopes:

• Read — can call any GET endpoint (list calls, view contacts, read knowledge, etc.)
• Write — can call any GET, POST, PUT, PATCH, or DELETE endpoint (create contacts, manage knowledge, modify settings, etc.)

A Write key implicitly has Read access. A Read-only key cannot perform any writes (returns 403 insufficient_scope).

Best practice: create separate keys per integration with the minimum scope each needs. A read-only Zap that pulls call data into Google Sheets should use a Read key; a write key for a Salesforce sync that creates contacts should be Write. Reduces blast radius if a key leaks.

Authentication

Pass your API key as a Bearer token in the Authorization header:

Authorization: Bearer av_live_abc123...

That's it. No additional headers, no signature scheme on the request side. (Outbound webhooks from Allison to your endpoint ARE signed — see the webhooks article — but those are a different direction.)

Rate Limits

Per API key, per minute:

If you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating how long to wait. Standard pattern: retry after the indicated seconds, with exponential backoff if multiple retries are needed.

The limit is per key, not per IP. If you have multiple servers using the same key, they share the budget. Most automation tools (Zapier, Make, n8n) handle 429s automatically.

Audit log

Every write the API performs is logged. The audit row captures:

• Which API key was used
• What entity was created, updated, or deleted
• The IP address and user-agent of the request
• A timestamp

Reads are NOT audit-logged (it would dwarf the table). The audit log is admin-visible today and will be subscriber-visible in a future release. If you ever need to trace "what did this key do, when?", reach out and we'll pull the relevant rows.

Revoking a key

Two ways:

1. Toggle the key inactive in Settings → API Keys — preserves the audit history but stops the key from authenticating.
2. Delete the key entirely — same effect as inactive, but the row is removed from the table. Audit history remains tied to the key ID even after deletion.

A revoked key returns 401 unauthorized on the next request. There's no grace period. If you suspect a key was leaked, revoke immediately and rotate.

What's available in v1

The v1 surface covers the resources subscribers commonly automate against:

• Calls — read call records, transcripts, summaries (read-only — call lifecycle is managed by the voice platform)
• Contacts — read, create, update caller contact profiles (the lite CRM that auto-populates from calls)
• Knowledge — read and write facts, FAQs, policies
• Locations — read, create, update locations
• Team members — read, create, update team contacts
• Escalation rules — read, create, update routing rules
• Intents — read, create, update call intent definitions
• Webhook subscriptions — read, create, update, delete (subscribe to events from your code without using the dashboard)

Full reference with request/response shapes for every endpoint is at docs.allisonvoice.com. The page embeds Scalar — interactive try-it-out works against your real API key.

Errors

Standard error envelope:

{
  "error": "short_machine_code",
  "details": { "field": "specific issue" }
}

Common status codes:

• 400 — Validation failed (the details object will say which field)
• 401 — Missing or invalid API key
• 403 — Wrong scope (you tried to write with a read-only key)
• 404 — Resource not found (or the API key's organization doesn't have access to it)
• 409 — Conflict (e.g., trying to create a duplicate)
• 429 — Rate limited (with Retry-After header)
• 500 — Something broke on our end (retry with backoff)

See docs.allisonvoice.com/errors for the full list.

Versioning

v1 is a stable contract — we add fields freely but never rename or remove them without a new major version. If a major version becomes necessary, both versions will run side-by-side with a clear deprecation timeline.

What's not yet supported

• Subscriber-visible audit log — Today the audit log is admin-side. Subscriber-facing audit log views are on the roadmap.
• OAuth on the API itself — V1 API uses key-based auth only. There's no OAuth provider flow for third-party apps to ask for API access on behalf of a subscriber. (Outbound integrations from Allison TO Google Calendar do use OAuth — separate concern.)
• Per-resource scopes — Today the model is read vs write across all resources. There's no way to grant "read calls but not contacts" with a single key. Coming in a future release; for now use multiple keys with finer-grained scopes when each is added.
• CORS — V1 endpoints currently don't allow browser-origin requests. The API is server-side only. Browser-origin support is being evaluated.
• GraphQL or webhooks-only access — V1 is REST-only. Webhooks are documented separately (see the webhooks article); they're a complement, not an alternative API path.

If any of these matter for your use case, ask Allison to file a support ticket so the team can prioritize.