Leadcaller's API is a REST API over HTTPS that responds with JSON. With it you can create customers and add team members programmatically. The same secure functions are available as MCP tools for AI agents. The complete machine-readable contract is available at /v1/openapi.json.

Authentication

Create an OAuth client under Settings → API & MCP. The client secret is shown once and is used only to fetch a short-lived access token:

curl -u "$LEADCALLER_CLIENT_ID:$LEADCALLER_CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "resource=https://api.leadcaller.com" \
  https://api.leadcaller.com/oauth/token

The response's access_token is sent as Authorization: Bearer …. The token is valid for 15 minutes and is bound to the requested resource.

Permissions

The profile is determined by the user who creates the client. Admins can manage customers and teams. Resellers can only manage their own customers. Regular users can only read and add regular members to their own team, and the API accepts no role field that could grant higher permissions.

REST endpoints

GET /v1/customers and GET /v1/customers/{id}
POST /v1/customers
GET /v1/team-members
POST /v1/team-members
GET /v1/operations/{id} for the status of asynchronous onboarding

Lists use ?cursor= and ?limit=. All POST requests require a unique Idempotency-Key, so that the same safe retry does not create duplicates.

curl https://api.leadcaller.com/v1/customers \
  -H "Authorization: Bearer $LEADCALLER_ACCESS_TOKEN"

MCP

MCP uses Streamable HTTP on POST /mcp. Request a token with resource=https://api.leadcaller.com/mcp. The server only advertises the tools that the client's scopes allow, and REST and MCP use exactly the same validation, tenant boundaries, idempotency and audit log. The operations.get tool follows the status of welcome emails and other asynchronous onboarding steps without leaving the MCP token's audience. The status failed is terminal and means that support needs to review the securely stored operation.

MCP version 2026-07-28 is stateless. Every request sends MCP-Protocol-Version, Mcp-Method and, for tool calls, also Mcp-Name. The same protocol version and the client's capabilities must be present in params._meta, and header and body must match.

curl https://api.leadcaller.com/mcp \
  -H "Authorization: Bearer $LEADCALLER_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

Error handling

The REST and OAuth API uses standard HTTP status codes: 2xx for a successful request, 4xx for errors in your request and 5xx for errors on our side. Error responses follow application/problem+json and contain a machine-readable code, a request ID and a readable detail:

{
  "type": "https://api.leadcaller.com/problems/unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "En giltig Bearer-token krävs.",
  "request_id": "…"
}

MCP instead follows JSON-RPC 2.0 and uses standardised MCP error codes, for example -32020 when the routing headers and body do not match.

Rate limits

Requests are rate limited per OAuth client to protect the service. If you reach the limit, the API responds with 429 Too Many Requests. Wait for as long as Retry-After indicates before you try again.

API reference