Setup

The OutCallerAI API lets an existing CRM, operations system, or internal application manage the same core records your team uses in the dashboard. Use it to provision agents, synchronize leads, configure calling use cases, and read call outcomes without duplicating manual work.

Open the generated API Reference to browse every supported endpoint, request and response schema, code example, and the interactive playground.

API prefixes

API Key

Create and manage API keys from the OutCallerAI Integrations.

• Visit the OutCallerAI dashboard subdomain
• Select Integrations from the sidebar

• Click Generate New Token

• Enter a description for the key
• Click Generate Token

• The API key is shown only once — copy and store it securely
• Click Copy Token to copy it to your clipboard

• Manage keys from the Integrations page
• Delete a key at any time to revoke access

Treat an API key like a password. Keep it in a server-side secret manager, send it only over HTTPS, and never place it in browser code, screenshots, support messages, source control, or a Postman shared initial value. Create separate keys for separate environments or integrations so each one can be revoked independently.

Headers

Authorization: Bearer <api-key>

Base URL

Production:

https://outcallerai.com

Example:

curl https://outcallerai.com/api/v1/public/workspace \
  -H "Authorization: Bearer <api-key>"

Errors and request IDs

Every public API response includes an X-Request-ID header. Send your own safe request ID when you need to correlate a request across systems, or let OutCallerAI generate one. Include this value when contacting support.

Errors use one stable envelope:

{
	"error": {
		"code": "validation_error",
		"message": "Unprocessable Entity",
		"request_id": "a72d84c2-7e36-4a3e-a9cc-e6adad589e17",
		"retryable": false,
		"details": []
	}
}

The HTTP status remains authoritative. The retryable field identifies transient failures that may succeed when repeated without changing the request. For mutations, it is true only when the request included an Idempotency-Key backed by persisted replay semantics. SDKs must additionally confirm that the operation supports idempotency before retrying. The details field is optional and may contain structured validation context.

Pagination

Agent, usecase, lead, and call list endpoints support opt-in cursor pagination:

• send limit from 1 to 100;
• read X-Next-Cursor and X-Has-More from the response;
• send the returned cursor unchanged as the next request's cursor;
• stop when X-Has-More is false.

Existing integrations that omit both limit and cursor retain the original unpaginated v1 response. New integrations should always request bounded pages. A request containing cursor but no limit uses a page size of 50.

Rate limits and retries

Rate-limited responses use status 429 and include Retry-After plus X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers when available. Retry 429, transient 5xx, and network timeouts with bounded exponential backoff and jitter. Honor Retry-After when present.

Do not automatically retry create, update, or delete requests after an ambiguous timeout unless the operation documents Idempotency-Key support and the caller supplied a stable key. Agent creation and lead creation currently support persisted replay semantics; other mutations do not.

API reference

Authenticated REST API

Integration pattern

For a reliable CRM integration, keep the CRM as the owner of customer records and store OutCallerAI IDs alongside the corresponding CRM records.

1. Create or select an agent, then store its agent_id in your integration configuration.
2. Create leads under that agent and retain each returned lead ID.
3. Read calls for the agent to synchronize status, transcript, summary, duration, and outcome data.
4. Make retries idempotent in your own worker: record successful IDs before retrying a batch, and do not blindly recreate records after a timeout.
5. Treat 401 as an invalid or revoked key, 403 as a workspace entitlement or policy restriction, 404 as an ID outside the authenticated workspace, and 422 as invalid request data.

The interactive playground sends requests through the OutCallerAI docs server so the key is never embedded in client-side source. The key remains in memory only while the playground is open and is cleared when it closes, navigates, or unloads. For production integrations, make requests from your own backend rather than from a public browser session.