Documentation

API reference

Base URL: https://api.byourside.ai. All endpoints require Authorization: Bearer bys_ak_... (your agent key). Request and response bodies are JSON.

Authentication

Every request must include an Authorization header with your agent API key. Keys are created in your account under Account - Developers.

Place a call

POST /v1/agent/calls

Validates the request, runs guardrails, creates a call record with status queued, and immediately returns a callId. The call runs asynchronously. Guardrail failures return a 4xx before any call is placed.

Request body

POST /v1/agent/calls
Authorization: Bearer bys_ak_YOUR_KEY
Content-Type: application/json

{
  "to":        "+14155550123",
  "objective": "Book a table for 4 at 7 PM Friday. Confirm the time and ask for their name.",
  "context":   "We have dined here before. Our preference is a window seat.",
  "fields": [
    { "name": "booked",         "type": "boolean", "description": "Did they confirm the booking?" },
    { "name": "confirmed_time", "type": "string",  "description": "The time they confirmed"       },
    { "name": "contact_name",   "type": "string",  "description": "Name given for the reservation"}
  ],
  "webhookUrl": "https://your-server.example.com/webhooks/bys",
  "callerId":   "+12134932550"
}

Response

Returns immediately with callId (use this to poll or match webhook events), status: "queued", and the resolved language, languageSource, and voice the call will use. Check languageSource to confirm whether the language was taken from your request, inferred from your objective, or set to auto.

{
  "callId":         "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status":         "queued",
  "language":       "en-US",
  "languageSource": "inferred",
  "voice":          "Aoede"
}

Structured field extraction

Pass a fields array when placing the call. After the call ends, By Your Side extracts each field from the transcript and populates the extracted object in the call record and webhook payload. Fields not found in the conversation are returned as null.

"fields": [
  { "name": "confirmed",  "type": "boolean" },
  { "name": "amount",     "type": "number",  "description": "Price quoted in USD" },
  { "name": "next_steps", "type": "string",  "description": "What the contact said they will do next" }
]

"extracted": {
  "confirmed":  true,
  "amount":     249,
  "next_steps": "They will email a signed contract by end of day Thursday."
}

Get a call

GET /v1/agent/calls/{id}

Returns the current state of a call. Calls are tenant-scoped: you can only fetch calls placed by your own key.

Response fields

{
  "id":          "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status":      "completed",
  "to":          "+14155550123",
  "objective":   "Book a table for 4 at 7 PM Friday.",
  "voice":          "Aoede",
  "language":       "en-US",
  "languageSource": "inferred",
  "summary":     "The restaurant confirmed a table for 4 at 7 PM Friday in the name of Smith, window section.",
  "extracted": {
    "booked":         true,
    "confirmed_time": "7 PM Friday",
    "contact_name":   "Smith"
  },
  "transcript":   "...",
  "recordingUrl": "https://api.byourside.ai/v1/agent/calls/f47ac10b-58cc-4372-a567-0e02b2c3d479/recording",
  "startedAt":    "2026-06-17T14:03:12.000Z",
  "endedAt":      "2026-06-17T14:05:48.000Z",
  "durationSec":  156
}

List calls

GET /v1/agent/calls?limit=20

Returns recent calls for your account, most recent first. Each item is a summary: it includes id, to, objective, status, summary, startedAt, endedAt, and durationSec. Full details (transcript, extracted, recordingUrl) are on GET /v1/agent/calls/{id}.

{
  "calls": [
    {
      "id":          "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "to":          "+14155550123",
      "objective":   "Book a table for 4 at 7 PM Friday.",
      "status":      "completed",
      "summary":     "Confirmed table for 4 at 7 PM Friday.",
      "startedAt":   "2026-06-17T14:03:12.000Z",
      "endedAt":     "2026-06-17T14:05:48.000Z",
      "durationSec": 156
    }
  ]
}

Status lifecycle

Statuses queued, dialing, and in_progress are non-terminal. Poll or use a webhook until you see one of the five terminal statuses.

Guardrails

The following rules apply to every call. Violations are rejected at placement time with a 400 error; no call is placed or billed.

• Allowed destinations: US, CA, GB, AU, NZ, and IL. Calls to other countries are rejected with destination_blocked.
• Blocked number types: Premium-rate, satellite, and IRSF-listed numbers are always blocked, regardless of country.
• Rate limit: A maximum number of calls per minute applies per API key. Excess requests return 429 rate_limited.
• Usage cap: Outbound minutes are drawn from your plan allowance. Once the cap is reached, additional calls return 429 over_minute_cap.
• Caller ID ownership: The callerId (or your account default) must be a number on your account. An unrecognized number returns 400 caller_id_not_owned.

Error reference

Error responses have the shape { "error": "token" }.