Welcome to AlmaTalk API
AlmaTalk provides a powerful REST API for automating AI-powered voice calls. Whether you're building customer outreach, appointment reminders, lead qualification, or interactive voice applications, the API exposes the account operations listed in this reference.
Getting Started
Step 1: Generate an API Key
Navigate to your AlmaTalk dashboard → Settings → API and webhooks to create an API key.
A key is scoped, not all-powerful. You choose the scopes when you create it, and the key can do exactly those things and nothing else. A key holding only calls:read can list calls and cannot place one. Give each integration its own key with the smallest set of scopes it needs, and keep the secret out of client-side code: it is shown once, at creation, and is stored only as a hash afterwards.
Step 2: Make Your First Request
Test your connection with a simple health check:
curl -X GET "https://almatalk.ca/api/v1/health"
Step 3: Authenticate Requests
Include your API key in every request using one of these methods:
curl -H "Authorization: Bearer YOUR_API_KEY" ...
curl -H "X-API-Key: YOUR_API_KEY" ...
Core Concepts
Credits and Metering
Credits are metered per second of answered conversation, not per minute and not rounded up to one. On the standard model tier one second of talk time costs one credit, so a minute costs 60 and a 70-second call costs 70.
A higher AI model tier costs more per second: the effective rate is the base rate multiplied by that tier's multiplier, both read live from your account. Your dashboard's model picker shows the exact credits per minute for every tier you can select, and the pricing page shows what each plan includes. Do not hard-code a rate; read GET /credits/balance for the balance and take the rate from the dashboard or the pricing page.
For reference, the Starter plan includes 9,000 credits, which is about 150 minutes of answered conversation on the standard tier.
GET /credits/usage reports minutes as a copy of credits, not as measured call duration. Treat credits as the truth and derive time from it with the rate above. Measured duration lives in GET /analytics/calls (totalDurationMinutes, averageDurationSeconds), which sums the recorded call length.
Telephony Engines
AlmaTalk supports two telephony engines for different use cases:
Authentication
The v1 discovery root and /health are public. Other v1 operations require an API key; dashboard and embed operations use the separate authentication shown on their cards. For API-key operations:
Authorization Header: Authorization: Bearer YOUR_API_KEY
X-API-Key Header: X-API-Key: YOUR_API_KEY
Requests handled by API-key authentication receive an X-Request-ID header. Quote it when you report a problem.
Scopes
A key carries a list of scopes and is refused with 403 INSUFFICIENT_SCOPES on anything outside them. These are the scopes enforced by mounted v1 routes. The ALMA CRM section lists its additional connected scopes:
403 INSUFFICIENT_SCOPES names the scope that was missing and lists the scopes the key does hold, so you can fix it without guessing.
Rate Limiting
The limit is per key, not per plan. Each key carries its own request ceiling and window, and both are visible on the key in your dashboard. A new key is created with a ceiling of 100 requests per 60 seconds; the account owner can set the ceiling from 10 to 10,000 requests when creating or editing a key. The server controls the time window.
Over the ceiling the API answers 429 RATE_LIMIT_EXCEEDED with details.retryAfter in seconds. Responses that pass key and IP validation carry the current state (including a rate-limit rejection). Authentication failures need not include these headers:
X-RateLimit-Limit - this key's maximum requests per window
X-RateLimit-Remaining - requests left in the current window
X-RateLimit-Reset - Unix timestamp (seconds) when the window resets
A key may also carry an IP allowlist. When it is set, a request from any other address is refused with 403 IP_NOT_WHITELISTED. An empty allowlist means any address is accepted.
Contact Identity
AlmaTalk keeps two stores of people, and they are not the same identity. Nothing merges them automatically, and you should not merge them on a phone number alone.
Mapping between them, when you need one: the only shared field is the phone number, compared on the last 10 digits after every non-digit is stripped, which is how the dashboard's own manual-contact route matches. That is a heuristic, not a key: two people sharing a line, or an extension, will collide. Keep your own external id in customFields on the lead if you need a stable join, and do not assume a lead id and a caller-profile id ever refer to the same row.
Campaign contacts are a third thing. POST /campaigns/{id}/contacts writes rows in a campaign's own contact list, keyed to that campaign, not to leads.
Response Format
Success Response
{
"success": true,
"data": { ... },
"meta": {
"requestId": "uuid",
"timestamp": "2024-01-01T00:00:00.000Z"
}
}
Error Response
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human readable message",
"details": { ... }
},
"meta": { ... }
}
Common Error Codes
Which authentication applies?
The primary integration API is /api/v1. Use an API key owned by the account and holding the scope shown on each operation. All records are account-scoped. A scope enables a route; it does not bypass available credits, trial restrictions, agent ownership, number ownership, or connected-service configuration. New keys default to calls:read, calls:write, campaigns:read, and contacts:read if scopes are omitted.
The ALMA CRM section uses /api/plugins/crm-bridge, with its own documented response shapes. Some connected CRM scopes are provisioned by the ALMA CRM connection and are not selectable in the ordinary API-key form. The key-management section requires an account-owner dashboard session. Existing dashboard actions are explicitly marked as session-only and use /api; an API key cannot authenticate those actions. Team permissions and feature availability still apply. Session APIs are for the signed-in application, not unattended API-key integrations.
Knowledge scopes offered by the key form do not currently have a standalone /api/v1 resource. Agent read and flow import/export are supported; creating or updating an agent prompt through an API key is not a published operation. Internal administration endpoints are not customer APIs.
Pagination and safe retries
REST list endpoints use page and pageSize, with pagination in meta.pagination; check each operation for its actual defaults and limits. CRM exports use opaque cursors and has_more. Keep a cursor unchanged between requests and stop when there is no next page. Incremental CRM call exports overlap by 24 hours so updated call results can be included; deduplicate by call id. Do not treat call ids as a UUID-only format.
Read requests may be retried after a temporary error. Calls, messages, purchases, invitations and campaign starts can have side effects. Unless an operation explicitly describes idempotency, a retry after a timeout may duplicate the action. A successful submission does not prove a call was answered or a message delivered. Use the returned status, later reads and supported webhooks to reconcile outcomes. The reference examples do not execute requests; the interactive explorer does execute requests when you submit them.