Skip to main content

API Overview

The YourCalls API lets you trigger outbound voice calls from your own application, and keep the contacts those calls are placed against up to date.

Base URL​

https://api.yourcalls.ai

This host serves the public API only. Apart from the /health and /ready checks, every path outside /public/ returns 404.

Authentication​

Authenticate requests by including your API key in a request header:

Authorization: Bearer YOUR_API_KEY

x-api-key: YOUR_API_KEY also works. Passing the key in the URL is not supported. See Authentication.

Available endpoints​

  • Create a call: POST /public/v1/calls triggers an outbound call from one of your assistants. See Calls.
  • Create or update a contact: POST /public/v1/contacts records a person by phone number or email address, and updates the matching contact if there already is one. See Contacts.
  • Look a contact up: GET /public/v1/contacts finds one contact by phone number or email address.
  • Read a contact: GET /public/v1/contacts/:id returns one contact by its id.
  • Export a contact: GET /public/v1/contacts/:id/export returns everything held about one person, for a subject access request.

Calls are triggered here and reviewed in the dashboard. There is no endpoint for reading call results back.

Request and response fields are snake_case, wrapped in the standard response envelope:

{
  "success": true,
  "data": { "request_id": "...", "call_id": "...", "status": "in_progress", "from_number": "+447700900999" },
  "error": null,
  "requestId": "req-abc123",
  "apiVersion": 1
}

API reference pages​