Place your first outbound AI phone call

This tutorial uses a placeholder destination. Do not paste a real phone number into an example until your organization has approved the workflow, the intended recipient has the required consent relationship, and billing is ready.

1. Check prerequisites

Confirm the following before sending a call request:

• the bearer key includes callonline.calls or *;
• the destination and callback number use E.164 format, such as +15551234567;
• the purpose matches the actual call;
• capturedAt is an ISO 8601 timestamp with an offset and is not in the future;
• evidenceRef points to your auditable consent record;
• the called-party time zone is an IANA name such as America/New_York;
• the account has enough available credits.

2. Send one request

The internal-test example below is suitable for a controlled test number you own. Replace every placeholder deliberately.

curl https://callonline.app/v1/calls \
  --request POST \
  --header "Authorization: Bearer $CALLONLINE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+15551234567",
    "objective": "Confirm that the CallOnline test workflow is working",
    "voiceTier": "standard",
    "metadata": { "testCase": "first-call-fixture" },
    "compliance": {
      "purpose": "internal_test",
      "consent": {
        "basis": "manual_internal_test",
        "capturedAt": "2026-07-14T14:30:00Z",
        "evidenceRef": "test-owner-approval-001"
      },
      "calledParty": {
        "timeZone": "America/New_York",
        "state": "FL",
        "type": "wireless"
      },
      "caller": {
        "legalName": "Example Company LLC",
        "onBehalfOf": "Example Company",
        "callbackNumber": "+15557654321",
        "aiDisclosureAcknowledged": true,
        "dncPolicyAcknowledged": true
      },
      "recording": {
        "enabled": false
      }
    }
  }'

3. Save the accepted result

An approved request that starts dialing returns HTTP 201. The representative shape is:

{
  "id": "call_opaque_identifier",
  "status": "dialed",
  "telnyxCallControlId": "redacted",
  "telnyxCallSessionId": "redacted",
  "compliance": {
    "approved": true,
    "aiDisclosureScript": "Hi, this is Jaxia, an AI assistant calling for Example Company..."
  }
}

Store id as your durable CallOnline identifier. Carrier identifiers are operational details; do not use them as your primary application key.

4. Inspect the call

curl "https://callonline.app/v1/calls/call_opaque_identifier" \
  --header "Authorization: Bearer $CALLONLINE_API_KEY"

The response includes call and an ordered events array. Continue only until a terminal status appears. Prefer a webhook for production notification and use polling as reconciliation.

If the request is blocked

An HTTP 403 with error: "compliance_blocked" includes a callId, a list of blocks, and the proposed disclosure script. Do not retry unchanged. Fix the underlying evidence or context, complete any internal approval your organization’s policy requires, and create a new request only when it is appropriate.

An HTTP 502 or 503 can be ambiguous. Call creation has no idempotency contract in v1. Before sending another POST, check whether your application already stored a call ID or received a webhook. Blind retries can place duplicate calls.