OnCallClerk Logo
Try Free
DevelopersAPI Reference

Reference  ·  REST

API reference.

Complete REST API documentation for the OnCallClerk platform. Base URL https://api.oncallclerk.com.

.md

Authentication

Authenticate every request by including your API key in the Authorization header as a Bearer token.

GET /agents HTTP/1.1
Host: api.oncallclerk.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

API keys can be generated in your dashboard settings. Each key is scoped to your account and has full access to all endpoints.

Agents

Create, manage, and configure AI voice agents.

GET/agents

Returns a list of all voice agents associated with your account.

Response

{
  "success": true,
  "data": [
    {
      "id": "agt_abc123",
      "business_name": "Acme Corp",
      "agent_name": "Reception",
      "phone_number": "+14155551234",
      "voice_id": "f5HLTX707KIM4SzJYzSz",
      "greeting": "Hello, thanks for calling Acme Corp!",
      "system_prompt": "You are a helpful receptionist...",
      "status": "active",
      "escalation_policy": "complex",
      "forwarding_number": "+14155559876",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-20T14:00:00Z"
    }
  ]
}
GET/agents/{agentId}

Retrieve a single voice agent by its ID.

Path Parameters

agentIdrequired
string

The unique identifier of the agent.

Response

{
  "success": true,
  "data": {
    "id": "agt_abc123",
    "business_name": "Acme Corp",
    "agent_name": "Reception",
    "phone_number": "+14155551234",
    "phone_number_sid": "PN...",
    "voice_id": "f5HLTX707KIM4SzJYzSz",
    "greeting": "Hello, thanks for calling Acme Corp!",
    "system_prompt": "You are a helpful receptionist...",
    "voice_settings": {
      "personality": "friendly",
      "name": "Kevin"
    },
    "functions_enabled": true,
    "forwarding_number": "+14155559876",
    "escalation_number": "+14155550000",
    "escalation_policy": "complex",
    "business_hours": {
      "enabled": true,
      "timezone": "America/New_York",
      "schedule": {
        "monday": { "open": "09:00", "close": "17:00", "enabled": true },
        "tuesday": { "open": "09:00", "close": "17:00", "enabled": true }
      }
    },
    "faq": [
      { "question": "What are your hours?", "answer": "We are open 9–5 Mon–Fri." }
    ],
    "status": "active",
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-20T14:00:00Z"
  }
}
POST/agents

Create and deploy a new AI voice agent.

Request Body

business_namerequired
string

The business name the agent represents.

agent_namerequired
string

A friendly name for the agent (e.g. 'Reception', 'Support').

voice_idrequired
string

The ID of the voice to use. See the Voices endpoint for available options.

greetingrequired
string

The greeting spoken when a call is answered.

system_promptrequired
string

Instructions that define the agent's behavior and personality.

forwarding_number
string

Phone number to forward calls to when escalation is triggered.

escalation_number
string

Dedicated escalation phone number (overrides forwarding_number for escalations).

escalation_policy
'never' | 'complex' | 'requested' | 'always'

When to transfer to a human. Defaults to 'never'.

business_hours
BusinessHours

Business hours configuration. If omitted or disabled, agent runs 24/7.

faq
FAQ[]

Array of FAQ entries the agent can reference during calls.

voice_settings
VoiceSettings

Additional voice customization: personality and display name.

functions_enabled
boolean

Enable built-in tool functions (calendar, email, etc.). Defaults to false.

Example Request

{
  "business_name": "Acme Corp",
  "agent_name": "Reception",
  "voice_id": "f5HLTX707KIM4SzJYzSz",
  "greeting": "Hello, thanks for calling Acme Corp! How can I help?",
  "system_prompt": "You are a professional receptionist for Acme Corp. Be friendly, answer questions about the business, and take messages when needed.",
  "escalation_policy": "complex",
  "forwarding_number": "+14155559876",
  "faq": [
    {
      "question": "What are your business hours?",
      "answer": "We are open Monday through Friday, 9am to 5pm Eastern."
    }
  ]
}

Response

{
  "success": true,
  "agent": {
    "id": "agt_abc123",
    "business_name": "Acme Corp",
    "agent_name": "Reception",
    "voice_id": "f5HLTX707KIM4SzJYzSz",
    "status": "active",
    "phone_number": null,
    "created_at": "2025-01-15T10:30:00Z"
  }
}
PUT/agents/{agentId}

Update a voice agent's configuration. Only include the fields you want to change.

Path Parameters

agentIdrequired
string

The unique identifier of the agent.

Request Body

Any fields from the Create Agent body. Only provided fields are updated.

Example Request

{
  "greeting": "Hi there! You've reached Acme Corp.",
  "escalation_policy": "always",
  "business_hours": {
    "enabled": true,
    "timezone": "America/Chicago",
    "schedule": {
      "monday": { "open": "08:00", "close": "18:00", "enabled": true },
      "tuesday": { "open": "08:00", "close": "18:00", "enabled": true },
      "wednesday": { "open": "08:00", "close": "18:00", "enabled": true },
      "thursday": { "open": "08:00", "close": "18:00", "enabled": true },
      "friday": { "open": "08:00", "close": "18:00", "enabled": true },
      "saturday": { "open": "10:00", "close": "14:00", "enabled": true },
      "sunday": { "open": "00:00", "close": "00:00", "enabled": false }
    }
  }
}

Response

{
  "success": true,
  "updatedAgent": {
    "id": "agt_abc123",
    "greeting": "Hi there! You've reached Acme Corp.",
    "escalation_policy": "always",
    "updated_at": "2025-01-21T09:15:00Z"
  }
}
DELETE/agents/{agentId}

Permanently delete a voice agent and release its phone number.

Path Parameters

agentIdrequired
string

The unique identifier of the agent to delete.

Response

{
  "success": true
}

This action is irreversible. All transcripts for this agent will also be deleted.

POST/agents/{agentId}/phone

Assign or change the phone number for an agent. The number must first be acquired via the Phone Numbers endpoint.

Path Parameters

agentIdrequired
string

The unique identifier of the agent.

Request Body

requestedNumberrequired
string

The phone number to assign (E.164 format, e.g. '+14155551234').

Example

{
  "requestedNumber": "+14155551234"
}

Phone Numbers

Search and acquire phone numbers to assign to your voice agents.

GET/phone-numbers/available

Search for available phone numbers that can be acquired and assigned to agents.

Query Parameters

country
string

ISO country code. Defaults to 'US'.

areaCode
string

Filter by area code (e.g. '415').

contains
string

Search for numbers containing this string.

pageSize
number

Number of results per page. Defaults to 10, max 50.

page
number

Page number for pagination. Starts at 0.

Response

{
  "success": true,
  "data": {
    "numbers": [
      {
        "phoneNumber": "+14155551234",
        "friendlyName": "(415) 555-1234",
        "region": "CA",
        "isoCountry": "US",
        "type": "local",
        "capabilities": {
          "voice": true,
          "SMS": true,
          "MMS": true
        }
      }
    ],
    "page": 0,
    "pageSize": 10,
    "country": "US"
  }
}
GET/phone-numbers/regulatory-bundles/{isoCountry}

Get existing regulatory bundles for a specific country. Required for acquiring numbers in regulated countries (e.g. GB, DE, AU).

Path Parameters

isoCountryrequired
string

Two-letter ISO country code (e.g. 'GB', 'DE').

Response

{
  "success": true,
  "data": {
    "bundles": [
      {
        "sid": "BU...",
        "status": "twilio-approved",
        "isoCountry": "GB",
        "name": "Acme Corp - GB Bundle"
      }
    ]
  }
}
POST/phone-numbers/regulatory-bundle

Create a new regulatory bundle for a country. Submit business or individual compliance data along with identity documents.

Request Body

isoCountryCoderequired
string

Two-letter ISO country code.

complianceType
'business' | 'individual'

Type of compliance submitter. Defaults to 'business'.

complianceData
ComplianceData

Business or individual compliance details (name, address, registration number, etc.).

proofOfIdentity
File

Identity document upload (multipart/form-data).

proofOfAddress
File

Address verification document upload (multipart/form-data).

ComplianceData Object

For business type:

businessNameregistrationAuthorityregistrationNumberwebsitebusinessStreetbusinessCitybusinessRegionbusinessPostalCodebusinessCountryrepFirstNamerepLastNamerepPhoneNumberrepEmail

For individual type:

firstNamelastNameemailphoneNumberbirthDateindividualStreetindividualCityindividualRegionindividualPostalCodeindividualCountry

Response

{
  "success": true,
  "bundleSid": "BU..."
}

Transcripts

Access call transcripts, summaries, and conversation logs for your agents.

GET/agents/{agentId}/transcripts

Get all call transcripts for a specific agent, ordered by most recent first.

Path Parameters

agentIdrequired
string

The unique identifier of the agent.

Query Parameters

limit
number

Maximum number of transcripts to return. Defaults to 50.

offset
number

Number of transcripts to skip for pagination.

type
string

Filter by call type: 'Sales Inquiry', 'Support Request', 'General Info', 'Complaint', 'Feedback', 'Booking', 'Cancellation'.

outcome
string

Filter by outcome: 'Resolved', 'Escalated', 'Follow-up Required', 'Lead Captured', etc.

Response

{
  "success": true,
  "data": {
    "transcripts": [
      {
        "id": "tr_xyz789",
        "date": "2025-01-20",
        "time": "14:32:00",
        "duration": 185,
        "duration_minutes": 3.08,
        "caller": "+14155559999",
        "type": "Sales Inquiry",
        "outcome": "Lead Captured",
        "rating": 5,
        "summary": "Caller asked about pricing for the enterprise plan. Expressed interest in a demo. Contact info captured.",
        "conversation": [
          { "speaker": "agent", "text": "Hello, thanks for calling Acme Corp!" },
          { "speaker": "caller", "text": "Hi, I wanted to ask about your pricing." },
          { "speaker": "agent", "text": "Of course! We have three plans..." }
        ],
        "agentId": "agt_abc123",
        "created_at": "2025-01-20T14:32:00Z"
      }
    ]
  }
}
GET/agents/{agentId}/transcripts/{transcriptId}

Retrieve a single transcript by ID with full conversation log.

Path Parameters

agentIdrequired
string

The unique identifier of the agent.

transcriptIdrequired
string

The unique identifier of the transcript.

Voices

Browse available AI voices for your agents.

GET/voices

Returns a list of all available voices you can assign to agents.

Response

{
  "success": true,
  "data": [
    {
      "id": "f5HLTX707KIM4SzJYzSz",
      "name": "Kevin",
      "accent": "American",
      "description": "Professional, warm, and articulate",
      "gender": "Male"
    },
    {
      "id": "KR1TkIhkSykEjI4B0DtH",
      "name": "Sarah",
      "accent": "American",
      "description": "Confident, friendly, and approachable",
      "gender": "Female"
    },
    {
      "id": "4BWwbsA70lmV7RMG0Acs",
      "name": "Lucy",
      "accent": "British",
      "description": "Energetic, clear, and engaging",
      "gender": "Female"
    },
    {
      "id": "YLbQE9U7P1K6rBNJWNSv",
      "name": "Jake",
      "accent": "Australian",
      "description": "Young, reliable, and professional",
      "gender": "Male"
    }
  ]
}

Available Voices

NameAccentGender
KevinAmericanMale
SarahAmericanFemale
LucyBritishFemale
JakeAustralianMale
DominicAmericanMale
AvaAmericanFemale
EliseAmericanFemale
RyanAmericanMale
JonAmericanMale

User

Manage your account profile and settings.

GET/user

Retrieve the authenticated user's profile.

Response

{
  "success": true,
  "data": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@acmecorp.com",
    "company": "Acme Corp",
    "timezone": "America/New_York",
    "personalPhoneNumber": "+14155559876",
    "emailNotifications": true,
    "callNotifications": true,
    "weeklyReports": false
  }
}
PUT/user

Update the authenticated user's profile. Only include fields to change.

Request Body

firstName
string

First name.

lastName
string

Last name.

company
string

Company or business name.

timezone
string

IANA timezone string (e.g. 'America/New_York').

personalPhoneNumber
string

Personal contact phone number.

emailNotifications
boolean

Enable email notifications.

callNotifications
boolean

Enable call event notifications.

weeklyReports
boolean

Enable weekly performance reports via email.

DELETE/user

Permanently delete the authenticated user's account, all agents, and all data.

Response

{
  "success": true
}

This action is irreversible. All agents, phone numbers, transcripts, and settings will be permanently deleted.

Subscription

Query your current subscription status and usage.

GET/subscription

Get the current subscription plan and usage limits for your account.

Response

{
  "success": true,
  "data": {
    "subscription": {
      "plan": "professional",
      "status": "active",
      "current_period_start": "2025-01-01T00:00:00Z",
      "current_period_end": "2025-02-01T00:00:00Z",
      "cancel_at_period_end": false
    },
    "usage": {
      "used": 142,
      "limit": 500
    }
  }
}

Errors

The API uses standard HTTP status codes and returns consistent error objects.

{
  "success": false,
  "error": "Agent not found",
  "status": 404
}
StatusDescription
200Success. The request was completed as expected.
201Created. A new resource was successfully created.
400Bad Request. The request body is missing required fields or has invalid values.
401Unauthorized. API key is missing, invalid, or expired.
403Forbidden. You don't have permission to access this resource.
404Not Found. The requested resource does not exist.
409Conflict. The resource already exists or there is a state conflict.
429Too Many Requests. Rate limit exceeded. Retry after the specified interval.
500Internal Server Error. Something went wrong on our end.

Further reading

Engineering guides for teams building voice agents on this API.