Using the Allison Voice REST 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 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 → API Keys (in the Connect section of the sidebar)
• Full reference (interactive): docs.allisonvoice.com
• Base URL: https://api.allisonvoice.com/v1/...

Creating an API key

1. Go to API Keys in the dashboard sidebar (Connect section)
2. Click Generate New Key (the API Keys page is admin-only)
3. Name the key (e.g., "Zapier integration", "Production sync"). This is just for your reference
4. Leave Allow write access on for a read + write key, or switch it off for a read-only key
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 is 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 revocation are sensitive actions. The dashboard requires a fresh code from your authenticator app (or a recovery 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 was created, updated, or deleted, the IP address and user-agent of the request, and a timestamp. If you ever need to trace "what did this key do, when?", reach out and we'll pull the relevant rows.

Revoking a key

Click the trash icon next to the key on the API Keys page and confirm with Revoke Key. Revocation is permanent: the key stops authenticating immediately, its audit history is kept, and it can't be re-enabled. If you need the same integration running again, create a new key.

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 create a replacement.

What's available in v1

The v1 surface covers the resources subscribers commonly automate against:

• Calls: read call records, transcripts, summaries, and recordings. Call lifecycle is managed by the voice platform, so the only write is updating an order's status on a call.
• Bookings: read appointments booked by your agent
• Orders: read phone orders
• Contacts: read, create, update, and delete caller contact profiles (the lite CRM that auto-populates from calls), plus read, create, update, and delete team notes on a contact
• Knowledge: read, create, update, and delete facts and FAQs
• Locations: read, create, update, and delete locations
• Team members: read, create, update, and delete team members
• Escalation rules: read, create, update, and delete routing rules
• Intents: read and update call intent definitions
• Settings: read and update organization settings
• Integrations: read connected integrations
• Me: read the organization and key the request is authenticated as
• Webhook subscriptions: read, create, update, delete, rotate secrets, and view deliveries (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 reference is 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: There's no audit log view in the dashboard today. Ask us and we'll pull the rows you need.
• OAuth on the API itself: The 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, a 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.
• CORS: Endpoints don't allow browser-origin requests. The API is server-side only.

If your integration needs one of these, tell Allison and she will file a ticket so we know there is demand.