Documentation

Quickstart

Place your first outbound AI call in three steps. You will need a By Your Side account with at least one phone number.

Step by step

1. Get an agent API keyIn your account, open Account - Developers and press Create agent key. Copy the key; it starts with bys_ak_. You will not be able to see it again.
   Make sure you have at least one phone number on your account. By Your Side uses your number as the outbound caller ID. You can set a default in the Developers section or pass callerId per call.
2. Place a callSend a POST to /v1/agent/calls with your objective and (optionally) the fields you want extracted from the conversation.
   Place a call (curl)Copy

   curl -X POST https://api.byourside.ai/v1/agent/calls \
     -H "Authorization: Bearer bys_ak_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "to": "+14155550123",
       "objective": "Confirm the appointment for tomorrow at 2 PM and ask if they need to reschedule.",
       "fields": [
         { "name": "confirmed", "type": "boolean" },
         { "name": "new_time",  "type": "string"  }
       ]
     }'

   The API responds immediately with a callId, status queued, and the resolved language, languageSource, and voice the call will use. The call runs asynchronously in the background.
   ResponseCopy

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

3. Poll until completeSend a GET to /v1/agent/calls/{callId} every few seconds until the status is one of the five terminal states: completed, no_answer, voicemail, declined, or failed.
   Poll for result (curl)Copy

   curl https://api.byourside.ai/v1/agent/calls/f47ac10b-58cc-4372-a567-0e02b2c3d479 \
     -H "Authorization: Bearer bys_ak_YOUR_KEY"

   A completed call includes a plain-English summary, the extracted fields, a full transcript, and a recording URL.
   Completed call responseCopy

   {
     "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
     "status": "completed",
     "to": "+14155550123",
     "objective": "Confirm the appointment for tomorrow at 2 PM and ask if they need to reschedule.",
     "summary": "The contact confirmed the appointment at 2 PM and said they did not need to reschedule.",
     "extracted": {
       "confirmed": true,
       "new_time": null
     },
     "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
   }

Next steps

• API reference - every parameter, response field, status, and error token.
• SDKs - Python and Node clients with a built-in wait_for_call helper that handles polling automatically.
• MCP server - let Claude Desktop or Cursor place calls as tool calls.
• Webhooks - receive real-time events during and after the call.
• Playground - place a live test call from the dashboard with no code (good for verifying your setup before writing any integration).
• Lead caller - run the same AI call toward a list of leads and collect structured results for each one.