Claritel.ai Logo
    Developer Hub
    V1.0.4 STABLE

    Telephony Reimagined.

    Build next-generation communication flows with Claritel's high-performance Telephony API. Connect agents and customers instantly with enterprise-grade reliability.

    Integration Lifecycle

    Follow the standard sequence to ensure a smooth and successful telephony integration.

    1. Auth & Keys

    Use your Tenant API key from the Admin Dashboard to authorize all requests.

    2. Initiate Bridge

    Use Click-to-Call or Single Leg to connect agent and customer instantly.

    3. Manage CRM

    Create and update leads in real-time during or after every call.

    4. Post-Call Webhooks

    Receive automated POST notifications to your server on every call event.

    Privacy & Protection

    Claritel employs advanced masking and encryption to protect caller privacy. Our temporal session model ensures that Virtual DIDs are only active during authorized windows.

    Temporal Masking

    Virtual numbers are assigned dynamically and expire automatically after a set duration, preventing unauthorized post-session contact.

    Secure Auth

    All requests must include a valid x-api-key header. Never expose this key in client-side applications.

    Role-Based Scoping

    All data responses are automatically scoped to the authenticated principal's role — agents see only their own data, supervisors see their team's.

    IST Timestamps

    All call timestamps are returned in Asia/Kolkata (IST). Store and compare times in UTC on your side to avoid timezone issues.

    Outbound

    2 Leg Calling

    POST
    /api/v1/telephony/click-to-call

    Initiate a seamless outbound bridge between an agent and a customer. The system rings the agent first, and upon connection, bridges the call to the customer instantly.

    i

    Agent and customer numbers require a minimum of 10 digits. If the DID is omitted, the system will use the default account DID.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/telephony/click-to-call' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw '{
    "agent": "9876543210",
    "customer": "8765432109",
    "did": "optional_did_number"
}'
    Response Body
    {
    "success": true,
    "data": {
        "status": "success",
        "call_id": "c1b2f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0a"
    }
}

    Payload Dictionary

    PropertyTypeDescription
    agentreq
    string
    The 10-digit registered agent number to bridge from.
    customerreq
    string
    The customer's destination phone number.
    did
    string
    Optional specific Virtual DID to dial out from. Defaults to account primary.
    Single Leg

    Single Leg Calling

    POST
    /api/v1/telephony/single-leg

    After the API request is initiated, the agent calls the specified DID number. Upon connection, the system automatically bridges the call from the same DID to the customer.

    i

    This API creates a "pending bridge" state. The call to the customer is only initiated once the system detects an incoming call from the agent_number to the specified DID.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/telephony/single-leg' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw '{
    "agent_number": "9876543210",
    "customer_number": "8765432109",
    "did": "0112345678"
}'
    Response Body
    {
    "success": true,
    "data": {
        "id": "req-12345-abcde",
        "expires_at": "2026-06-01T14:30:00Z",
        "agent_number": "9876543210"
    }
}

    Payload Dictionary

    PropertyTypeDescription
    agent_numberreq
    string
    The registered phone number of the agent who will initiate the call to the DID.
    customer_numberreq
    string
    The destination customer number to which the agent will be bridged.
    didreq
    string
    The Virtual DID number the agent must dial to trigger the connection.
    Users

    Create User

    POST
    /api/v1/client/users

    Create a new agent or supervisor within your tenant account. An invitation email with a link to set the password is automatically sent to the provided email address.

    i

    The 'role' field must be either 'agent' or 'supervisor'. The group_id is optional. User status starts as 'pending_invite' until they accept the invitation.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/users' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "9876543210",
    "role": "agent",
    "group_id": 1
}'
    Response Body
    {
    "success": true,
    "data": {
        "id": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
        "client_id": 1,
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone_number": "9876543210",
        "role": "agent",
        "status": "pending_invite",
        "is_taking_calls": false,
        "status_reason": "",
        "created_at": "2026-04-25T16:46:46Z",
        "updated_at": "2026-04-25T16:46:46Z"
    }
}

    Payload Dictionary

    PropertyTypeDescription
    first_namereq
    string
    User's first name.
    last_namereq
    string
    User's last name.
    emailreq
    string
    User's valid email address. Used for login.
    phone_numberreq
    string
    10-digit registered phone number.
    rolereq
    string
    Must be either "agent" or "supervisor".
    group_id
    integer
    Optional group ID to assign the user to.
    Users

    List Users

    GET
    /api/v1/client/users

    Retrieve all agents and supervisors in your tenant account. The response is scoped by role — admins see all users, supervisors see their team, and agents see only themselves.

    i

    User status can be 'active', 'pending_invite', or 'inactive'. The enable_agent_availability flag indicates whether live availability tracking is enabled for your account.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/users' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "data": {
        "enable_agent_availability": false,
        "users": [
            {
                "id": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
                "client_id": 1,
                "first_name": "Aakash",
                "last_name": "Sarkar",
                "email": "aakash@example.com",
                "phone_number": "9876543210",
                "role": "agent",
                "status": "active",
                "is_taking_calls": false,
                "status_reason": "",
                "created_at": "2026-02-09T12:31:39Z",
                "updated_at": "2026-02-18T07:18:24Z"
            }
        ]
    }
}
    Users

    Get User

    GET
    /api/v1/client/users/{id}

    Retrieve a single user's details by their unique ID (UUID or legacy integer ID).

    i

    Replace {id} with the user's UUID or legacy integer ID.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/users/00d9312c-d94b-4e7d-b1ca-beadab0d6ca4' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "data": {
        "id": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
        "client_id": 1,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone_number": "9876500000",
        "role": "supervisor",
        "status": "active",
        "is_taking_calls": false,
        "status_reason": "",
        "created_at": "2026-04-25T16:46:46Z",
        "updated_at": "2026-04-26T09:00:00Z"
    }
}

    Payload Dictionary

    PropertyTypeDescription
    id (path)req
    string
    The unique UUID or legacy integer ID of the user to retrieve.
    Users

    Update User

    PUT
    /api/v1/client/users/{id}

    Update an existing user's details. All fields are optional — only include the fields you wish to change. The user ID (UUID or legacy integer ID) is passed as a URL path parameter.

    i

    Replace {id} with the user's UUID or legacy integer ID. Duplicate email or phone numbers will return a 400 error. Role changes take effect immediately.

    Request · cURL
    curl --location --request PUT 'https://cloudtelephony.claritel.ai/api/v1/client/users/00d9312c-d94b-4e7d-b1ca-beadab0d6ca4' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw '{
    "first_name": "Jane",
    "last_name": "Doe",
    "phone_number": "9876500000",
    "role": "supervisor"
}'
    Response Body
    {
    "success": true,
    "data": {
        "id": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
        "client_id": 1,
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone_number": "9876500000",
        "role": "supervisor",
        "status": "active",
        "is_taking_calls": false,
        "status_reason": "",
        "created_at": "2026-04-25T16:46:46Z",
        "updated_at": "2026-04-26T09:00:00Z"
    }
}

    Payload Dictionary

    PropertyTypeDescription
    id (path)req
    string
    The unique UUID or legacy integer ID of the user to update.
    first_name
    string
    User's first name.
    last_name
    string
    User's last name.
    email
    string
    User's valid email address.
    phone_number
    string
    10-digit registered phone number.
    role
    string
    Must be either "agent" or "supervisor".
    group_id
    integer
    Group ID to assign the user to.
    Users

    Delete User

    DELETE
    /api/v1/client/users/{id}

    Permanently remove a user from your tenant account. This action is irreversible. The user will immediately lose access to the platform.

    i

    Replace {id} with the user's UUID or legacy integer ID. Deleting a user does not delete their historical call records.

    Request · cURL
    curl --location --request DELETE 'https://cloudtelephony.claritel.ai/api/v1/client/users/00d9312c-d94b-4e7d-b1ca-beadab0d6ca4' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "message": "User deleted successfully"
}

    Payload Dictionary

    PropertyTypeDescription
    id (path)req
    string
    The unique UUID or legacy integer ID of the user to delete.
    Availability

    Update Agent Availability

    POST
    /api/v1/client/users/availability

    Toggle an agent's call availability status (Available / Unavailable) and optionally provide a status reason (e.g., Break, Lunch, Meeting).

    i

    Updating availability might fail if the client has active IVR schedule restrictions and tries to set availability outside working hours.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/users/availability' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw '{
    "agent_id": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
    "is_taking_calls": true,
    "status_reason": ""
}'
    Response Body
    {
    "success": true,
    "message": "Availability status updated successfully"
}

    Payload Dictionary

    PropertyTypeDescription
    agent_id
    string
    Optional agent UUID. Required when calling via API Key. If omitted, targets the currently authenticated user.
    is_taking_callsreq
    boolean
    Set to true to make agent available for calls, or false to make them unavailable.
    status_reason
    string
    Optional reason for unavailability (e.g. Break, Lunch, Meeting).
    CRM

    Create / Update Lead

    POST
    /api/v1/client/crm/lead

    Create a new CRM lead or update an existing one. This endpoint uses an upsert pattern — if a lead with the same phone number already exists, it will be updated. Setting a follow_up_date automatically schedules a follow-up reminder.

    i

    Phone numbers are normalized automatically — country codes and leading zeros are stripped to the last 10 digits. Setting follow_up_date creates a scheduled reminder in the Follow-ups module.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/crm/lead' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw '{
    "phone_number": "9876543210",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "dob": "1990-01-01",
    "address1": "123 Main St",
    "address2": "Suite 400",
    "city": "San Francisco",
    "state": "CA",
    "county": "San Francisco",
    "company": "Acme Corp",
    "status": "Hot",
    "disposition": "interested",
    "sub_disposition": "feature_request",
    "field1": "Custom Value 1",
    "field2": "Custom Value 2",
    "sugar_data": {"campaign": "spring_sale"},
    "note": "Interested in the enterprise plan",
    "follow_up_date": "2026-06-01T10:00:00Z",
    "follow_up_note": "Call back after product demo"
}'
    Response Body
    {
    "success": true,
    "message": "Lead saved successfully",
    "data": {
        "id": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
        "client_id": 1,
        "phone_number": "9876543210",
        "name": "Jane Smith",
        "dob": "1990-01-01",
        "email": "jane@example.com",
        "address1": "123 Main St",
        "address2": "Suite 400",
        "city": "San Francisco",
        "state": "CA",
        "county": "San Francisco",
        "note": "Interested in the enterprise plan",
        "company": "Acme Corp",
        "status": "Hot",
        "field1": "Custom Value 1",
        "field2": "Custom Value 2",
        "disposition": "interested",
        "sub_disposition": "feature_request",
        "follow_up_date": "2026-06-01T10:00:00Z",
        "follow_up_note": "Call back after product demo",
        "sugar_data": {"campaign": "spring_sale"},
        "created_at": "2026-04-26T06:00:00Z",
        "updated_at": "2026-04-26T06:00:00Z"
    }
}

    Payload Dictionary

    PropertyTypeDescription
    phone_numberreq
    string
    10-digit phone number of the lead (acts as unique identifier).
    namereq
    string
    Full name of the lead.
    email
    string
    Email address of the lead.
    dob
    string
    Date of birth (YYYY-MM-DD).
    address1
    string
    Primary address line.
    address2
    string
    Secondary address line (suite, apt, etc).
    city
    string
    City name.
    state
    string
    State or province code.
    county
    string
    County name.
    company
    string
    Company name.
    status
    string
    Lead status (e.g., Hot, Warm, Cold).
    disposition
    string
    Call disposition assigned to this lead.
    sub_disposition
    string
    Sub-disposition for more granular reporting.
    field1
    string
    Custom text field 1.
    field2
    string
    Custom text field 2.
    sugar_data
    object
    JSON object for storing arbitrary custom data.
    note
    string
    General notes about the lead.
    follow_up_date
    string
    ISO 8601 timestamp to schedule a follow-up.
    follow_up_note
    string
    Note specific to the scheduled follow-up.
    CRM

    Get Lead by Phone

    GET
    /api/v1/client/crm/lead

    Retrieve a single lead record by phone number. This is useful for real-time CRM lookups during an active call — identify the caller the moment they connect.

    i

    Returns null data (not a 404) if the lead does not exist. The phone query parameter is normalized — you can pass 10-digit, 11-digit, or +91 format.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/crm/lead?phone=9876543210' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "data": {
        "id": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
        "client_id": 1,
        "phone_number": "9876543210",
        "name": "Jane Smith",
        "email": "jane@example.com",
        "company": "Acme Corp",
        "status": "Hot",
        "disposition": "interested",
        "sub_disposition": "feature_request",
        "note": "Interested in the enterprise plan",
        "follow_up_date": "2026-06-01T10:00:00Z",
        "follow_up_note": "Call back after product demo",
        "created_at": "2026-04-26T06:00:00Z",
        "updated_at": "2026-04-26T06:00:00Z"
    }
}

    Payload Dictionary

    PropertyTypeDescription
    phone (query)req
    string
    The phone number to search for.
    CRM

    List Leads

    GET
    /api/v1/client/crm/leads

    Retrieve a paginated list of all CRM leads for your tenant. Results are ordered by last update time (most recent first).

    i

    Pagination is handled via page and limit query parameters. Default is page=1, limit=10.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/crm/leads?page=1&limit=10' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "data": {
        "leads": [
            {
                "id": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
                "client_id": 1,
                "phone_number": "9876543210",
                "name": "Jane Smith",
                "email": "jane@example.com",
                "company": "Acme Corp",
                "status": "Hot",
                "disposition": "interested",
                "follow_up_date": "2026-06-01T10:00:00Z",
                "created_at": "2026-04-26T06:00:00Z",
                "updated_at": "2026-04-26T06:00:00Z"
            }
        ],
        "total_count": 42,
        "page": 1,
        "limit": 10,
        "total_pages": 5
    }
}

    Payload Dictionary

    PropertyTypeDescription
    phone (query)
    string
    Optional 10-digit phone number to filter leads.
    page (query)
    integer
    Page number for pagination. Defaults to 1.
    limit (query)
    integer
    Number of items per page. Defaults to 10.
    CRM

    Update Lead

    PUT
    /api/v1/client/crm/lead/{id}

    Update all fields of a specific lead by its UUID. The lead ID is passed as a URL path parameter. All fields from the create endpoint are accepted.

    i

    Replace {id} with the lead's UUID string. Changing the phone_number will update the primary key — ensure the new number is not already assigned to another lead.

    Request · cURL
    curl --location --request PUT 'https://cloudtelephony.claritel.ai/api/v1/client/crm/lead/00d9312c-d94b-4e7d-b1ca-beadab0d6ca4' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw '{
    "phone_number": "9876543210",
    "name": "Jane Smith",
    "dob": "1990-01-01",
    "address1": "123 Main St",
    "address2": "Suite 400",
    "city": "San Francisco",
    "state": "CA",
    "county": "San Francisco",
    "status": "Warm",
    "disposition": "callback_requested",
    "field1": "Custom Value 1",
    "field2": "Custom Value 2",
    "sugar_data": {"campaign": "spring_sale"},
    "note": "Follow-up scheduled for next week"
}'
    Response Body
    {
    "success": true,
    "message": "Lead updated successfully",
    "data": {
        "id": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
        "client_id": 1,
        "phone_number": "9876543210",
        "name": "Jane Smith",
        "dob": "1990-01-01",
        "address1": "123 Main St",
        "address2": "Suite 400",
        "city": "San Francisco",
        "state": "CA",
        "county": "San Francisco",
        "status": "Warm",
        "disposition": "callback_requested",
        "field1": "Custom Value 1",
        "field2": "Custom Value 2",
        "sugar_data": {"campaign": "spring_sale"},
        "note": "Follow-up scheduled for next week",
        "updated_at": "2026-04-26T09:30:00Z"
    }
}

    Payload Dictionary

    PropertyTypeDescription
    id (path)req
    string
    The UUID of the lead to update.
    phone_number
    string
    Update the phone number.
    name
    string
    Update the name.
    dob
    string
    Update the date of birth.
    address1
    string
    Update the primary address.
    address2
    string
    Update the secondary address.
    city
    string
    Update the city.
    state
    string
    Update the state.
    county
    string
    Update the county.
    status
    string
    Update the status.
    disposition
    string
    Update the disposition.
    field1
    string
    Update custom field 1.
    field2
    string
    Update custom field 2.
    sugar_data
    object
    Update the custom JSON object data.
    note
    string
    Update the note.
    CRM

    Delete Lead

    DELETE
    /api/v1/client/crm/lead/{id}

    Permanently delete a CRM lead by its UUID. This also cascades to remove any associated pending follow-up records for the deleted lead.

    i

    Replace {id} with the lead's UUID. This operation is permanent and cannot be undone.

    Request · cURL
    curl --location --request DELETE 'https://cloudtelephony.claritel.ai/api/v1/client/crm/lead/00d9312c-d94b-4e7d-b1ca-beadab0d6ca4' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "message": "Lead deleted successfully"
}

    Payload Dictionary

    PropertyTypeDescription
    id (path)req
    string
    The UUID of the lead to delete.
    CRM

    List Follow-ups

    GET
    /api/v1/client/crm/follow-ups

    Retrieve a paginated list of scheduled follow-ups with advanced filtering by date range, status, and agent. Follow-ups are automatically created when a lead is saved with a follow_up_date.

    i

    Query parameters: start_date (YYYY-MM-DD), end_date (YYYY-MM-DD), status ('Pending' or 'Done'), agent_id (integer), limit, page.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/crm/follow-ups?status=Pending&limit=10&page=1' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "data": {
        "data": [
            {
                "id": 45,
                "lead_id": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
                "customer_name": "Jane Smith",
                "customer_phone": "9876543210",
                "follow_up_time": "2026-06-01T10:00:00Z",
                "due_in": "in 5 days",
                "status": "Pending",
                "note": "Call back after product demo",
                "created_by": "Vivek Sarkar",
                "created_at": "2026-04-26T06:00:00Z",
                "last_modified_by": "Vivek Sarkar",
                "last_modified_at": "2026-04-26T06:00:00Z"
            }
        ],
        "total": 12,
        "page": 1,
        "limit": 10
    }
}

    Payload Dictionary

    PropertyTypeDescription
    start_date (query)
    string
    Start date in YYYY-MM-DD format.
    end_date (query)
    string
    End date in YYYY-MM-DD format.
    status (query)
    string
    Filter by "Pending" or "Done".
    agent_id (query)
    integer
    Filter follow-ups assigned to a specific agent.
    page (query)
    integer
    Page number for pagination.
    limit (query)
    integer
    Number of items per page.
    CRM

    Update Follow-up Status

    PUT
    /api/v1/client/crm/follow-ups/{id}/status

    Mark a follow-up as 'Done' after it has been actioned, or reset it back to 'Pending'. This updates the follow-up record and the agent's task queue in real-time.

    i

    Status must be exactly 'Pending' or 'Done' (case-sensitive). Replace {id} with the integer follow-up ID from the list response.

    Request · cURL
    curl --location --request PUT 'https://cloudtelephony.claritel.ai/api/v1/client/crm/follow-ups/45/status' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw '{
    "status": "Done"
}'
    Response Body
    {
    "success": true,
    "message": "Follow-up status updated to Done"
}

    Payload Dictionary

    PropertyTypeDescription
    id (path)req
    integer
    The ID of the follow-up record.
    statusreq
    string
    The new status. Must be "Pending" or "Done".
    Reports

    Call Logs

    GET
    /api/v1/client/reports/call-logs

    Retrieve a paginated list of call records from the telephony engine for a given date range. Supports filtering by status, agent number, customer number, and group. Access is automatically scoped by role.

    i

    Query params: start (YYYY-MM-DD), end (YYYY-MM-DD), status (Answered/Agent Missed/Customer Missed/Abandoned), agent_number, group_id, customer_number, virtual_number, q (search), limit, page. All timestamps are returned in IST (Asia/Kolkata).

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/reports/call-logs?start=2026-04-01&end=2026-04-26&limit=10&page=1' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "data": [
        {
            "id": 5021,
            "caller": "9876543210",
            "virtual_num": "02240064747",
            "agent_num": "7351216813",
            "agent_name": "Aakash Sarkar",
            "call_type": "inbound",
            "start_time": "2026-04-25T14:32:10+05:30",
            "duration": 185,
            "status": "Answered",
            "hangup_cause": "NORMAL_CLEARING",
            "hangup_by": "Agent",
            "ivr_path": "3 -> 1",
            "recording_url": "/1/2026/04/25/uuid-here.wav",
            "is_transfer": false,
            "supervisor_name": "John Doe",
            "supervisor_num": "1234567890"
        }
    ],
    "total": 320,
    "page": 1,
    "limit": 10,
    "total_pages": 32
}

    Payload Dictionary

    PropertyTypeDescription
    start (query)
    string
    Start date in YYYY-MM-DD format.
    end (query)
    string
    End date in YYYY-MM-DD format.
    status (query)
    string
    Filter by Answered, Agent Missed, Customer Missed, Abandoned.
    agent_number (query)
    string
    Filter by agent phone number.
    customer_number (query)
    string
    Filter by customer phone number.
    group_id (query)
    string
    Filter by group UUID to see calls for agents in that group.
    page (query)
    integer
    Page number for pagination.
    limit (query)
    integer
    Number of items per page.
    Reports

    Call Log Report

    GET
    /api/v1/client/reports/call-log-report

    Detailed inbound & outbound call records with agent ring attempts, recording playback, and status breakdown. Includes CRM data integration.

    i

    Query params: start_date, end_date, status, customer_number, virtual_number, q, limit, page.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/reports/call-log-report?start_date=2026-04-01&end_date=2026-04-26&limit=10&page=1' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "data": [
        {
            "id": 5021,
            "customer_number": "9876543210",
            "virtual_num": "0112345678",
            "agent_num": "9876543210",
            "agent_name": "Aakash Sarkar",
            "call_type": "inbound",
            "start_time": "2026-04-25T14:32:10+05:30",
            "duration": 185,
            "status": "Answered",
            "hangup_cause": "NORMAL_CLEARING",
            "hangup_by": "Agent",
            "ivr_path": "3 -> 1",
            "recording_url": "/1/2026/04/25/uuid-here.wav",
            "call_journey": [
                {
                    "agent_number": "9876543210",
                    "agent_name": "Aakash Sarkar",
                    "start_time": "2026-04-25T14:32:10+05:30",
                    "ring_duration": 12,
                    "talk_time": 173,
                    "status": "Answered",
                    "hangup_cause": "NORMAL_CLEARING"
                }
            ],
            "crm_data": {
                "id": "123",
                "phone_number": "9876543210",
                "name": "Aakash Sarkar",
                "email": "aakash@example.com",
                "dob": "1995-05-12",
                "address1": "123 Main Street",
                "address2": "Apartment 4B",
                "city": "Mumbai",
                "state": "Maharashtra",
                "county": "India",
                "note": "Lead created from inbound IVR call",
                "company": "Tech Corp",
                "status": "active",
                "field1": "Custom Field Value 1",
                "field2": "Custom Field Value 2",
                "disposition": "Follow up",
                "sub_disposition": "Interested",
                "follow_up_date": "2026-06-28T10:00:00Z",
                "follow_up_note": "Call back on Monday morning",
                "custom_field": {
                    "company_name": "Tech Corp"
                }
            }
        }
    ],
    "total": 320,
    "page": 1,
    "limit": 10,
    "total_pages": 32
}

    Payload Dictionary

    PropertyTypeDescription
    start_date (query)
    string
    Start date in YYYY-MM-DD format.
    end_date (query)
    string
    End date in YYYY-MM-DD format.
    status (query)
    string
    Filter by Answered, Agent Missed, Customer Missed, Abandoned.
    group_id (query)
    string
    Filter by group UUID to see calls for agents in that group.
    page (query)
    integer
    Page number for pagination.
    limit (query)
    integer
    Number of items per page.
    Reports

    Agent Performance

    GET
    /api/v1/client/reports/apr

    Track individual agent metrics including call counts, average handle time, inbound/outbound counts, and resolution rates.

    i

    Metrics reflect the specified date range. total_duration is represented in seconds.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/reports/apr?start_date=2026-04-01&end_date=2026-04-26' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "data": {
        "data": [
            {
                "agent_name": "Aakash Sarkar",
                "phone_number": "9876543210",
                "total_calls": 120,
                "answered": 105,
                "agent_missed": 15,
                "inbound_count": 80,
                "outbound_count": 40,
                "total_duration": 18500
            }
        ],
        "total_agents": 1,
        "start_date": "2026-04-01",
        "end_date": "2026-04-26"
    }
}

    Payload Dictionary

    PropertyTypeDescription
    start_date (query)
    string
    Start date in YYYY-MM-DD format.
    end_date (query)
    string
    End date in YYYY-MM-DD format.
    Reports

    Dashboard Stats

    GET
    /api/v1/client/dashboard/stats

    Retrieve aggregated call statistics for the dashboard — including total calls, answered rate, missed calls, and average call duration for a given period.

    i

    Dates default to today if omitted. The answer_rate is expressed as a percentage. avg_duration is in seconds.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/dashboard/stats?start=2026-04-01&end=2026-04-26' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "data": {
        "total_calls": 320,
        "answered": 210,
        "agent_missed": 65,
        "abandoned": 45,
        "answer_rate": 65.63,
        "avg_duration": 142,
        "inbound": 230,
        "outbound": 90
    }
}

    Payload Dictionary

    PropertyTypeDescription
    start (query)
    string
    Start date in YYYY-MM-DD format. Defaults to today.
    end (query)
    string
    End date in YYYY-MM-DD format. Defaults to today.
    Reports

    Single Leg Report

    GET
    /api/v1/telephony/single-leg

    Retrieve a paginated list of all single-leg (number masked) calls. Access is automatically scoped by role — supervisors see their team's calls, agents see only their own, and admins see all.

    i

    Single Leg calls represent number masking attempts. A SUCCESS call indicates that both agent and customer were successfully bridged together.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/telephony/single-leg?start_date=2026-04-01&end_date=2026-04-26&limit=10&page=1' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "data": {
        "data": [
            {
                "id": "e3b6f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0b",
                "status": "SUCCESS",
                "call_uuid": "c1b2f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0a",
                "agent_number": "9876543210",
                "customer_number": "8765432109",
                "virtual_number": "0112345678",
                "duration": 45,
                "hangup_by": "Agent",
                "start_time": "2026-04-25T14:32:10+05:30",
                "answer_time": "2026-04-25T14:32:15+05:30",
                "end_time": "2026-04-25T14:32:55+05:30",
                "created_at": "2026-04-25T14:30:00+05:30",
                "talk_time": 40,
                "recording_url": "https://cloudconnect.claritel.ai/api/recordings/1/2026/04/25/c1b2f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0a_0112345678_20260425_143210.wav",
                "call_type": "Inbound"
            }
        ],
        "total": 1,
        "page": 1,
        "limit": 10,
        "total_pages": 1
    }
}

    Payload Dictionary

    PropertyTypeDescription
    start_date (query)
    string
    Start date in YYYY-MM-DD format.
    end_date (query)
    string
    End date in YYYY-MM-DD format.
    status (query)
    string
    Filter by SUCCESS, FAILURE, pending.
    search (query)
    string
    Search query to filter by agent, customer, virtual number, or UUID.
    call_uuid (query)
    string
    Filter specifically by a unique call UUID.
    page (query)
    integer
    Page number for pagination. Defaults to 1.
    limit (query)
    integer
    Number of items per page. Defaults to 10.
    Reports

    Get Single Leg Call Status

    GET
    /api/v1/telephony/single-leg/{id}

    Retrieve details and live status of a single-leg request by its unique request ID (UUID) or call UUID.

    i

    Replace {id} with the single-leg request ID or the call UUID.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/telephony/single-leg/e3b6f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0b' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "data": {
        "id": "e3b6f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0b",
        "status": "SUCCESS",
        "call_uuid": "c1b2f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0a",
        "agent_number": "9876543210",
        "customer_number": "8765432109",
        "virtual_number": "0112345678",
        "duration": 45,
        "hangup_by": "Agent",
        "start_time": "2026-04-25T14:32:10+05:30",
        "answer_time": "2026-04-25T14:32:15+05:30",
        "end_time": "2026-04-25T14:32:55+05:30",
        "talk_time": 40,
        "recording_url": "https://cloudconnect.claritel.ai/api/recordings/1/2026/04/25/c1b2f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0a_0112345678_20260425_143210.wav",
        "call_type": "Inbound"
    }
}

    Payload Dictionary

    PropertyTypeDescription
    id (path)req
    string
    The unique request ID (UUID) or call UUID to retrieve.
    Groups

    Create Group

    POST
    /api/v1/client/groups

    Create a new group (team) within your tenant account. You can optionally assign a supervisor and a list of agents.

    i

    Group names must be unique within your client account. The supervisor must have the supervisor role.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/groups' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw '{
    "name": "Sales Team",
    "supervisor_id": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
    "agent_ids": [
        "11d9312c-d94b-4e7d-b1ca-beadab0d6ca5"
    ]
}'
    Response Body
    {
    "success": true,
    "data": {
        "id": 1,
        "client_id": 1,
        "name": "Sales Team",
        "supervisor": {
            "id": 10,
            "uuid": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane.doe@example.com",
            "phone_number": "9876543210",
            "role": "supervisor",
            "status": "active"
        },
        "agents": [
            {
                "id": 11,
                "uuid": "11d9312c-d94b-4e7d-b1ca-beadab0d6ca5",
                "first_name": "John",
                "last_name": "Smith",
                "email": "john.smith@example.com",
                "phone_number": "8765432109",
                "role": "agent",
                "status": "active"
            }
        ],
        "created_at": "2026-04-26T10:00:00Z",
        "updated_at": "2026-04-26T10:00:00Z"
    }
}

    Payload Dictionary

    PropertyTypeDescription
    namereq
    string
    Unique name of the group.
    supervisor_id
    string
    UUID of the user assigned as supervisor for this group.
    agent_ids
    array of strings
    List of agent UUIDs to add to this group.
    sticky_agent_ring_timeout
    integer
    The duration (in seconds) the system will attempt to ring the designated sticky agent before giving up or moving to a fallback option. Useful for ensuring callers do not wait indefinitely if their sticky agent stepped away. If an agent is on a short break, a higher timeout gives them a chance to answer; if call volume is high, a shorter timeout ensures the caller gets routed to another available agent quickly. Must be an integer between 5 and 30 seconds.
    sticky_agent_recall_limit
    integer
    The number of times a caller can be successfully re-routed back to their specific sticky agent over time. Prevents agent fatigue or over-reliance on a single employee by a specific customer. For example, setting this to 2 ensures the caller gets their preferred agent twice, but on the 3rd call, they are distributed to the general group queue to balance the workload among the team. Set to 0 or null to disable. Must be an integer between 1 and 3.
    sticky_agent_default_fallbacks
    array of strings
    A sequential priority list of UUIDs representing agents or phone numbers that the system should fall back to if the original sticky agent is unavailable or fails to answer within the sticky_agent_ring_timeout. If a caller's dedicated agent is busy, this list ensures the call goes to a trusted secondary or tertiary agent (or an external emergency number) rather than dropping into a random general queue. Maximum of 3 fallback entries.
    Groups

    List Groups

    GET
    /api/v1/client/groups

    Retrieve all groups in your tenant account. If authenticated as a supervisor, only groups you supervise are returned.

    i

    Admins see all groups. Supervisors see only the groups they supervise. Agents are typically not authorized to list groups.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/groups' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "data": [
        {
            "id": 1,
            "client_id": 1,
            "name": "Sales Team",
            "supervisor": {
                "id": 10,
                "uuid": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
                "first_name": "Jane",
                "last_name": "Doe",
                "email": "jane.doe@example.com",
                "phone_number": "9876543210",
                "role": "supervisor",
                "status": "active"
            },
            "agents": [
                {
                    "id": 11,
                    "uuid": "11d9312c-d94b-4e7d-b1ca-beadab0d6ca5",
                    "first_name": "John",
                    "last_name": "Smith",
                    "email": "john.smith@example.com",
                    "phone_number": "8765432109",
                    "role": "agent",
                    "status": "active"
                }
            ],
            "created_at": "2026-04-26T10:00:00Z",
            "updated_at": "2026-04-26T10:00:00Z"
        }
    ]
}
    Groups

    Get Group

    GET
    /api/v1/client/groups/{id}

    Retrieve a single group's details by its unique UUID.

    i

    Replace {id} with the group's UUID string.

    Request · cURL
    curl --location 'https://cloudtelephony.claritel.ai/api/v1/client/groups/e3b6f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0b' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "data": {
        "id": 1,
        "uuid": "e3b6f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0b",
        "client_id": 1,
        "name": "Sales Team",
        "supervisor": {
            "id": 10,
            "uuid": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane.doe@example.com",
            "phone_number": "9876543210",
            "role": "supervisor",
            "status": "active"
        },
        "agents": [
            {
                "id": 11,
                "uuid": "11d9312c-d94b-4e7d-b1ca-beadab0d6ca5",
                "first_name": "John",
                "last_name": "Smith",
                "email": "john.smith@example.com",
                "phone_number": "8765432109",
                "role": "agent",
                "status": "active"
            }
        ],
        "created_at": "2026-04-26T10:00:00Z",
        "updated_at": "2026-04-26T10:00:00Z"
    }
}

    Payload Dictionary

    PropertyTypeDescription
    id (path)req
    string
    The unique UUID of the group to retrieve.
    Groups

    Update Group

    PUT
    /api/v1/client/groups/{id}

    Update group name, change supervisor, or add/remove agents. All fields are optional.

    i

    Replace {id} with the group's UUID string.

    Request · cURL
    curl --location --request PUT 'https://cloudtelephony.claritel.ai/api/v1/client/groups/e3b6f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0b' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw '{
    "name": "Updated Sales Team",
    "add_agent_ids": [
        "22d9312c-d94b-4e7d-b1ca-beadab0d6ca6"
    ],
    "remove_agent_ids": [
        "11d9312c-d94b-4e7d-b1ca-beadab0d6ca5"
    ]
}'
    Response Body
    {
    "success": true,
    "data": {
        "id": 1,
        "uuid": "e3b6f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0b",
        "client_id": 1,
        "name": "Updated Sales Team",
        "supervisor": {
            "id": 10,
            "uuid": "00d9312c-d94b-4e7d-b1ca-beadab0d6ca4",
            "first_name": "Jane",
            "last_name": "Doe",
            "email": "jane.doe@example.com",
            "phone_number": "9876543210",
            "role": "supervisor",
            "status": "active"
        },
        "agents": [
            {
                "id": 12,
                "uuid": "22d9312c-d94b-4e7d-b1ca-beadab0d6ca6",
                "first_name": "Alice",
                "last_name": "Jones",
                "email": "alice.jones@example.com",
                "phone_number": "7654321098",
                "role": "agent",
                "status": "active"
            }
        ],
        "created_at": "2026-04-26T10:00:00Z",
        "updated_at": "2026-04-26T11:30:00Z"
    }
}

    Payload Dictionary

    PropertyTypeDescription
    id (path)req
    string
    The unique UUID of the group to update.
    name
    string
    New name for the group.
    supervisor_id
    string
    UUID of the user to assign as supervisor.
    add_agent_ids
    array of strings
    List of agent UUIDs to add to this group.
    remove_agent_ids
    array of strings
    List of agent UUIDs to remove from this group.
    sticky_agent_ring_timeout
    integer
    The duration (in seconds) the system will attempt to ring the designated sticky agent before giving up or moving to a fallback option. Useful for ensuring callers do not wait indefinitely if their sticky agent stepped away. If an agent is on a short break, a higher timeout gives them a chance to answer; if call volume is high, a shorter timeout ensures the caller gets routed to another available agent quickly. Must be an integer between 5 and 30 seconds.
    sticky_agent_recall_limit
    integer
    The number of times a caller can be successfully re-routed back to their specific sticky agent over time. Prevents agent fatigue or over-reliance on a single employee by a specific customer. For example, setting this to 2 ensures the caller gets their preferred agent twice, but on the 3rd call, they are distributed to the general group queue to balance the workload among the team. Set to 0 or null to disable. Must be an integer between 1 and 3.
    sticky_agent_default_fallbacks
    array of strings
    A sequential priority list of UUIDs representing agents or phone numbers that the system should fall back to if the original sticky agent is unavailable or fails to answer within the sticky_agent_ring_timeout. If a caller's dedicated agent is busy, this list ensures the call goes to a trusted secondary or tertiary agent (or an external emergency number) rather than dropping into a random general queue. Maximum of 3 fallback entries.
    Groups

    Delete Group

    DELETE
    /api/v1/client/groups/{id}

    Permanently remove a group (team) from your tenant. This action is irreversible.

    i

    Replace {id} with the group's UUID string. Deleting a group does not delete the users assigned to it; they will simply become unassigned.

    Request · cURL
    curl --location --request DELETE 'https://cloudtelephony.claritel.ai/api/v1/client/groups/e3b6f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0b' \
--header 'x-api-key: <YOUR_API_KEY>'
    Response Body
    {
    "success": true,
    "message": "Group deleted successfully"
}

    Payload Dictionary

    PropertyTypeDescription
    id (path)req
    string
    The unique UUID of the group to delete.
    Real-Time Webhooks

    Event-Driven Architecture

    Our webhook system sends instant HTTP POST notifications to your server whenever a call event occurs. This allows you to synchronize your CRM, trigger automated SMS follow-ups, or build custom real-time dashboards with zero latency.

    Call Triggered

    A call is initiated (Inbound or Outbound) via Claritel.

    Event Dispatched

    Our engine fires a POST request to your Target URL.

    Server Receives

    Your server handles the JSON payload and responds with 200 OK.

    Business Logic

    Sync to CRM, log recordings, or trigger internal workflows.

    Event Payload Explorer

    Select a call scenario to see the exact JSON payload.

    payload_preview.json
    {  "event_name": "inbound_call_start",  "call_id": "c1b2f0a4-3d9a-4c9b-8f1a-5b6c7d8e9f0a",  "did_number": "0112345678",  "call_type": "inbound",  "customer_phone": "8765432109",  "start_time": "2026-04-26T14:45:30+05:30"}

    Fires the moment a new inbound call session is initiated by FreeSWITCH. Note: agent_phone is omitted because the IVR has not yet routed the call to an agent.

    Call Status Reference

    The status field in Call End events identifies the final outcome of the call.

    Answeredboth

    The call was successfully bridged. Both agent and customer were connected. recording_url and connected_time are included.

    Agent Missedboth

    For Inbound: An agent in the queue missed the call (agent_phone is included). For Outbound: In Click-to-Call, the agent did not answer their own phone. connected_time and recording_url are omitted.

    Customer Abandonedinbound

    The customer hung up while in the IVR/queue before any agent connected. agent_phone, connected_time, and recording_url are omitted.

    Customer Missedoutbound

    An outbound Click-to-Call was initiated by an agent but the customer did not answer their phone. talk_time is 0; connected_time and recording_url are omitted.

    Dashboard Configuration Guide

    Configure your integration lifecycle in the Claritel Admin Portal.

    Phase 01

    Select Event Type

    Choose "Call Started" or "Call Ended" to define the base trigger of your automation.

    Phase 02

    Trigger Condition

    Select "Inbound" or "Outbound". Our system automatically handles event_name prefixing.

    Phase 03

    Multi-Status Selection

    Subscribe to one or many dispositions. We use OR logic for multi-status configurations.

    Conditional Status Matrix

    Selection Logic: OR Condition

    Selecting multiple statuses creates an inclusive filter. The webhook fires if ANY selected state is reached.

    Inbound Call Statuses

    Answered

    The call was successfully connected to an available agent.

    Agent Missed

    The call timed out in the queue without an agent response.

    Customer Abandoned

    Customer hung up while waiting in the IVR or queue flow.

    Outbound Call Statuses

    Answered

    The customer answered the Click-to-Call bridge request.

    Agent Missed

    The agent failed to answer their own bridge leg.

    Customer Missed

    The customer did not respond to the outbound dial request.

    Payload Dictionary

    Field NameTypeScopeDescription
    event_namestringAll

    Identifies the specific event. One of: "inbound_call_start", "outbound_call_start", "inbound_call_end", "outbound_call_end".

    call_idstringAll

    The globally unique FreeSWITCH call session identifier. Use this as the primary key to correlate CALL_START and CALL_END events for the same call.

    did_numberstringAll

    The Virtual DID (Direct Inward Dialing) number associated with this call. For inbound: the number the customer dialled. For outbound: the Leg-B DID used.

    call_typestringAll

    The direction of the call. Always either "inbound" or "outbound".

    agent_phonestringAll

    The 10-digit phone number of the agent. Present on outbound start/end and answered or missed inbound calls. Omitted on inbound call start and customer abandoned calls.

    customer_phonestringAll

    The 10-digit phone number of the external customer. Always present on all start and end events.

    start_timestring (ISO 8601 IST)CALL_START

    IST timestamp (YYYY-MM-DDTHH:mm:ss+05:30) of when the call session was first established by the telephony engine.

    statusstringCALL_END

    The final call disposition. Inbound values: "Answered", "Agent Missed", "Customer Abandoned". Outbound values: "Answered", "Customer Missed", "Agent Missed".

    durationintegerCALL_END

    Total elapsed time of the call session in seconds (from ring to hangup). Includes queue wait time. Is 0 only for Abandoned calls that dropped immediately.

    talk_timeintegerCALL_END

    The actual connected bridge time in seconds — only the time both parties were speaking. 0 if the call was never answered (missed or abandoned).

    connected_timestring (ISO 8601 IST)CALL_END (Answered)

    The IST timestamp (YYYY-MM-DDTHH:mm:ss+05:30) of when the call was answered/connected. Omitted if the call was not answered.

    recording_urlstringCALL_END (Answered)

    Relative URL path to the .wav recording file. Format: /{client_id}/{yyyy}/{mm}/{dd}/{call_id}.wav. Omitted if the call was not answered or recording is disabled.

    end_timestring (ISO 8601 IST)CALL_END

    The IST timestamp (YYYY-MM-DDTHH:mm:ss+05:30) of when the call session was fully terminated and the CDR was finalized.