NAV Navbar
shell
  • Introduction
  • Authentication
  • Contacts API
  • Users API
  • Webhook subscriptions API
  • Webhooks
  • Telephony events API
  • Click-to-call API
  • Errors
  • Introduction

    Welcome to the Voxloud API reference! You can use our API key to access Voxloud API endpoints.

    At the moment we don't offer specific language bindings but we offer a REST API with webhooks in order to rapidly work with our API. JSON is the data exchange format used in all endpoints.

    Authentication

    To authenticate and authorize every call, you must provide a specific HTTP header in every API request:

    In this way you can pass the correct header with each request

    curl -X GET "https://developer.voxloud.com/api/v1/some_call" -H "Voverc-Auth: your_api_key"
    

    Voverc-Auth: your_api_key

    Validate authentication

    To validate your authentication key you can call /validate-auth endpoint which will return related company name and email if key is valid, HTTP 401 otherwise.

    HTTP Request

    POST https://developer.voxloud.com/api/v1/validate-auth

    curl -X POST "https://developer.voxloud.com/api/v1/validate-auth" -H "Voverc-Auth: your_api_key"
    

    It returns JSON structured like this:

    {
        "name": "company name",
        "email": "administrator email"
    }
    

    Contacts API

    Contact section of the API allows to create and manage your company contact resources in Voxloud.

    Create contact

    This endpoint creates a contact

    HTTP Request

    POST https://developer.voxloud.com/api/v1/contacts

    This request creates a contact

    curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    -d '{"first_name":"John","last_name":"Doe","primary_phone":"+390312345678","phones":["+390387654321"],"primary_email":"[email protected]","emails":["[email protected]"],"company_name":"John&Associates","job_title":"CEO","website":"www.johna.com","crm_name":"Voxloud","crm_contact_url":"https://www.crm.com/contacts/profile/1"}'
    "https://developer.voxloud.com/api/v1/contacts"
    

    It returns JSON structured like this:

    {
      "id" : "54db43f0-7d1c-11fd-8149-bdf161b05c48",
      "first_name" : "John",
      "last_name" : "Doe",
      "primary_phone" : "+390312345678",
      "phones" : [
        "+390387654321"
      ],
      "primary_email" : "[email protected]",
      "emails" : [
        "[email protected]"
      ],
      "company_name" : "John & Associates",
      "job_title" : "CEO",
      "website" : "www.johna.com",
      "crm_name" : "Voxloud",
      "crm_contact_url" : "https://www.crm.com/contacts/profile/1",
      "created_at" : "2022-12-27T14:42:37+01:00",
      "updated_at" : "2022-12-27T14:42:37+01:00"
    }
    

    Request object

    Property Type Required Description
    first_name string true Contact first name
    last_name string false Contact last name
    primary_phone string true Contact primary phone number, must be in e164 format
    phones array[string] false Contact secondary phone numbers, must be in e164 format
    primary_email string false Contact primary email
    emails array[string] false Contact secondary emails
    company_name string false Contact company name
    job_title string false Contact job title
    website string false Contact company website
    crm_name string false name of CRM where contact is from, will be set to Voxloud if not specified
    crm_contact_url string false Contact URL which points to the contact profile in CRM portal

    Response object

    Property Type Description
    id string Contact identifier
    first_name string Contact first name
    last_name string Contact last name
    primary_phone string Contact primary phone number in e164 format
    phones array[string] Contact secondary phone numbers in e164 format
    primary_email string Contact primary email
    emails array[string] Contact secondary emails
    company_name string Contact company name
    job_title string Contact job title
    website string Contact company website
    crm_name string Name of CRM where contact is from
    crm_contact_url string Contact URL which points to the contact profile in CRM portal
    created_at datetime Contact created date in ISO-8601 format
    updated_at datetime Contact updated date in ISO-8601 format

    Update contact

    This endpoint updates a contact

    HTTP Request

    POST https://developer.voxloud.com/api/v1/contacts/${id}

    This request updates a contact

    curl -X PUT -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    -d '{"first_name":"John","last_name":"Doe","primary_phone":"+390312345678","phones":["+390387654321","+390387654323"],"primary_email":"[email protected]","emails":["[email protected]"],"company_name":"John&Associates","job_title":"CEO","website":"www.johna.com","crm_name":"Voxloud","crm_contact_url":"https://www.crm.com/contacts/profile/1"}'
    "https://developer.voxloud.com/api/v1/contacts/54db43f0-7d1c-11fd-8149-bdf161b05c48"
    

    It returns JSON structured like this:

    {
      "id" : "54db43f0-7d1c-11fd-8149-bdf161b05c48",
      "first_name" : "John",
      "last_name" : "Doe",
      "primary_phone" : "+390312345678",
      "phones" : [
        "+390387654321",
        "+390387654323"
      ],
      "primary_email" : "[email protected]",
      "emails" : [
        "[email protected]"
      ],
      "company_name" : "John & Associates",
      "job_title" : "CEO",
      "website" : "www.johna.com",
      "crm_name" : "Voxloud",
      "crm_contact_url" : "https://www.crm.com/contacts/profile/1",
      "created_at" : "2022-12-27T14:42:37+01:00",
      "updated_at" : "2022-12-27T14:42:37+01:00"
    }
    

    Request object

    Property Type Required Description
    first_name string true Contact first name
    last_name string false Contact last name
    primary_phone string true Contact primary phone number, must be in e164 format
    phones array[string] false Contact secondary phone numbers, must be in e164 format
    primary_email string false Contact primary email
    emails array[string] false Contact secondary emails
    company_name string false Contact company name
    job_title string false Contact job title
    website string false Contact company website
    crm_name string false name of CRM where contact is from, will be set to Voxloud if not specified
    crm_contact_url string false Contact URL which points to the contact profile in CRM portal

    Response object

    Property Type Description
    id string Contact identifier
    first_name string Contact first name
    last_name string Contact last name
    primary_phone string Contact primary phone number in e164 format
    phones array[string] Contact secondary phone numbers in e164 format
    primary_email string Contact primary email
    emails array[string] Contact secondary emails
    company_name string Contact company name
    job_title string Contact job title
    website string Contact company website
    crm_name string Name of CRM where contact is from
    crm_contact_url string Contact URL which points to the contact profile in CRM portal
    created_at datetime Contact created date in ISO-8601 format
    updated_at datetime Contact updated date in ISO-8601 format

    Search Contacts

    This endpoint allows to search contacts by the set of parameters, like first name or phone number.

    HTTP Request

    GET https://developer.voxloud.com/api/v1/contacts

    This request allows to search contacts by the set of parameters, like first name or phone number.

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voxloud.com/api/v1/contacts?offset=350&limit=25&first_name=jOhN&last_name=dOe&email=j.doe0&phone=678"
    

    It returns JSON structured like this:

    {
      "data" : [
        {
          "id" : "54db43f0-7d1c-11fd-8149-bdf161b05c48",
          "first_name" : "John",
          "last_name" : "Doe",
          "primary_phone" : "+390312345678",
          "phones" : [
            "+390387654321"
          ],
          "primary_email" : "[email protected]",
          "emails" : [
            "[email protected]"
          ],
          "company_name" : "John & Associates",
          "job_title" : "CEO",
          "website" : "www.johna.com",
          "crm_name" : "Voxloud",
          "crm_contact_url" : "https://www.crm.com/contacts/profile/1",
          "created_at" : "2022-12-27T14:42:37+01:00",
          "updated_at" : "2022-12-27T14:42:37+01:00"
        },
        {
          "id" : "54db43f0-7d1c-11fd-8149-bdf161b05c49",
          "first_name" : "Maria",
          "last_name" : "Rosi",
          "primary_phone" : "+390312345637",
          "phones" : [
            "+390387654322"
          ],
          "primary_email" : "[email protected]",
          "emails" : [
            "[email protected]"
          ],
          "company_name" : "Maria & Associates",
          "job_title" : "CEO",
          "website" : "www.maria.com",
          "crm_name" : "Voxloud",
          "crm_contact_url" : "https://www.crm.com/contacts/profile/2",
          "created_at" : "2022-12-28T14:42:37+01:00",
          "updated_at" : "2022-12-28T14:42:37+01:00"
        }
      ],
      "has_next" : false
    }
    

    Query params

    Property Type Required Description
    first_name string false Contact full or partial first name
    last_name string false Contact full or partial last name
    phone string false Contact full or partial phone number, must be in e164 format
    email string false Contact full or partial email
    offset string false Must be positive value. Default value is 0
    limit string false Must be more than 0 and less than or equal to 100. Default value is 20

    Response object

    Property Type Description
    data array[objects] List of found contacts
    has_next boolean Indicates is there at least 1 more contact after requested page

    Get a contact

    This endpoint returns an existing contact

    HTTP Request

    GET https://developer.voxloud.com/api/v1/contacts/${id}

    This request returns an existing contact

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voxloud.com/api/v1/contacts/54db43f0-7d1c-11fd-8149-bdf161b05c48"
    

    It returns JSON structured like this:

    {
      "id" : "54db43f0-7d1c-11fd-8149-bdf161b05c48",
      "first_name" : "John",
      "last_name" : "Doe",
      "primary_phone" : "+390312345678",
      "phones" : [
        "+390387654321"
      ],
      "primary_email" : "[email protected]",
      "emails" : [
        "[email protected]"
      ],
      "company_name" : "John & Associates",
      "job_title" : "CEO",
      "website" : "www.johna.com",
      "crm_name" : "Voxloud",
      "crm_contact_url" : "https://www.crm.com/contacts/profile/1",
      "created_at" : "2022-12-27T14:42:37+01:00",
      "updated_at" : "2022-12-27T14:42:37+01:00"
    }
    

    Response object

    Property Type Description
    id string Contact identifier
    first_name string Contact first name
    last_name string Contact last name
    primary_phone string Contact primary phone number in e164 format
    phones array[string] Contact secondary phone numbers in e164 format
    primary_email string Contact primary email
    emails array[string] Contact secondary emails
    company_name string Contact company name
    job_title string Contact job title
    website string Contact company website
    crm_name string Name of CRM where contact is from
    crm_contact_url string Contact URL which points to the contact profile in CRM portal
    created_at datetime Contact created date in ISO-8601 format
    updated_at datetime Contact updated date in ISO-8601 format

    Delete contact

    This endpoint removes an existing contact

    HTTP Request

    DELETE https://developer.voxloud.com/api/v1/contacts/${id}

    This request deletes existing contact

    curl -X DELETE -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voxloud.com/api/v1/contacts/54db43f0-7d1c-11fd-8149-bdf161b05c48"
    

    Users API

    This API allows you query users

    Get all users

    This endpoint returns all users

    HTTP Request

    GET https://developer.voxloud.com/api/v2/users

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" "https://developer.voxloud.com/api/v2/users"
    

    It returns JSON structured like this:

    [
      {
        "id" : "facbb7fe-f845-11ee-b19b-960000128e6c",
        "first_name" : "John",
        "last_name" : "Smith",
        "extension_number" : 101,
        "outbound_cli" : {
          "outbound_did" : {
            "number" : "+390112121212",
            "label" : "Main office"
          },
          "available_dids" : [
            {
              "number" : "+390112121212",
              "label" : "Main office"
            },
            {
              "number" : "+3943212332432",
              "label" : "Customer support"
            },
            {
              "number" : "+3902421321222",
              "label" : "Secondary office"
            }
          ]
        }
      },
      {
        "id": "facc2109-f845-11ee-b99b-960000128e6c",
        "first_name": "Federico",
        "last_name": "Support",
        "extension_number": 102,
        "outbound_cli": {
          "outbound_did": {
            "number" : "+3943212332432",
            "label" : "Customer support"
          },
          "available_dids": [
            {
              "number" : "+3943212332432",
              "label" : "Customer support"
            }
          ]
        }
      }
    ]
    

    Response object

    Property Type Description
    id string User identifier
    first_name string User first name
    last_name string User last name
    extension_number integer User's extension number
    outbound_cli OutboundCli User's outbound numbers configuration

    OutboundCli

    Property Type Description
    outbound_did Did Currently selected outbound number
    available_dids array[Did] All available outbound numbers

    Did

    Property Type Description
    number string Phone number (international format)
    label string Phone number label

    Webhook subscriptions API

    This API allows you to be notified in real-time via webhooks whenever events occur, allowing you to integrate your system with Voxloud, for example by showing detailed contact information when an incoming call arrives. In order to correctly setup this mechanism you need to configure a webhook subscription before.

    Create a webhook subscription

    This endpoint creates a webhook subscription

    HTTP Request

    POST https://developer.voxloud.com/api/v1/webhook-subscriptions

    This request setups a notification on endpoint http://my_endpoint.domain when CALL_INCOMING event occurs

    curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    -d '{"callback_url":"http://my_endpoint.domain","event_type":"CALL_INCOMING","notification_email":"[email protected]"}'
    "https://developer.voxloud.com/api/v1/webhook-subscriptions"
    

    It returns JSON structured like this:

    {
      "id": "119a7b3d-00b9-4445-808a-a69676f86763",
      "enabled": true,
      "event_type": "CALL_INCOMING",
      "failed_count": 0,
      "callback_url": "http://my_endpoint.domain",
      "notification_email": "[email protected]"
    }
    

    Request object

    Property Required Description
    callback_url true It is the URL that will be invoked via webhook on every event
    event_type true Can be one of the following values: FAX_CALL, PHONE_CALL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP
    notification_email false Email that will be used for notifications if your subscription become disabled

    Response object

    Property Description
    id A unique identifier for the subscription
    callback_url It is the URL that will be invoked via webhook on every event
    event_type Can be one of the following values: FAX_CALL, PHONE_CALL, CLICK_TO_CALL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP
    failed_count Number of failed attempts
    last_error Last occurred error
    notification_email Email that will be used for notifications if your subscription become disabled

    Update a webhook subscription

    This endpoint updates an existing webhook subscription

    HTTP Request

    PUT https://developer.voxloud.com/api/v1/webhook-subscriptions/${id}

    curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    -d '{"id":"119a7b3d-00b9-4445-808a-a69676f86763","enabled":true,"callback_url":"http://my_endpoint.domain","event_type":"CALL_ANSWERED"}'
    "https://developer.voxloud.com/api/v1/webhook-subscriptions/119a7b3d-00b9-4445-808a-a69676f86763"
    

    It returns JSON structured like this:

    {
      "id": "119a7b3d-00b9-4445-808a-a69676f86763",
      "enabled": true,
      "event_type": "CALL_ANSWERED",
      "failed_count": 0,
      "callback_url": "http://my_endpoint.domain",
      "notification_email": "[email protected]"
    }
    

    Request object

    Property Required Description
    id true A unique identifier for the subscription
    callback_url true It is the URL that will be invoked via webhook on every event
    event_type true Can be one of the following values: FAX_CALL, PHONE_CALL, CLICK_TO_CALL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP
    enabled false Boolean to enable / disable subscription
    notification_email false Email that will be used for notifications if your subscription become disabled

    Response object

    Property Description
    id A unique identifier for the subscription
    callback_url It is the URL that will be invoked via webhook on every event
    event_type Can be one of the following values: FAX_CALL, PHONE_CALL, CLICK_TO_CALL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP
    enabled Boolean to enable / disable subscription
    failed_count Number of failed attempts
    last_error Last occurred error
    notification_email Email that will be used for notifications if your subscription become disabled

    Get webhook subscriptions

    This endpoint returns all the existing webhook subscriptions

    HTTP Request

    GET https://developer.voxloud.com/api/v1/webhook-subscriptions

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voxloud.com/api/v1/webhook-subscriptions"
    

    It returns JSON structured like this:

    [
      {
        "id": "119a7b3d-00b9-4445-808a-a69676f86763",
        "event_type": "CALL_INCOMING",
        "failed_count": 0,
        "enabled": true,
        "callback_url": "http://my_endpoint.domain",
        "notification_email": "[email protected]"
      },
      {
        "id": "f98b8c5d-4935-4e32-b6e4-490687c7f14d",
        "type": "CALL_ANSWERED",
        "failed_count": 0,
        "enabled": true,
        "callback_url": "http://my_endpoint.domain",
        "notification_email": "[email protected]"
      },
      {
        "id": "9cf8e5e7-d32a-4fc9-bc4a-1c2c9f2aa82d",
        "type": "CALL_HANGUP",
        "failed_count": 0,
        "enabled": true,
        "callback_url": "http://my_endpoint.domain",
        "notification_email": "[email protected]"
      }
    ]
    

    Response object

    An array of the following objects:

    Property Description
    id A unique identifier for the subscription
    callback_url It is the URL that will be invoked via webhook on every event
    event_type Can be one of the following values: FAX_CALL, PHONE_CALL, CLICK_TO_CALL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP
    enabled Boolean to enable / disable subscription
    failed_count Number of failed attempts
    last_error Last occurred error
    notification_email Email that will be used for notifications if your subscription become disabled

    Get call webhook subscription

    This endpoint returns an existing webhook subscription

    HTTP Request

    GET https://developer.voxloud.com/api/v1/webhook-subscriptions/${id}

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voxloud.com/api/v1/webhook-subscriptions/119a7b3d-00b9-4445-808a-a69676f86763"
    

    It returns JSON structured like this:

    {
      "id": "119a7b3d-00b9-4445-808a-a69676f86763",
      "event_type": "CALL_INCOMING",
      "failed_count": 0,
      "enabled": true,
      "callback_url": "http://my_endpoint.domain",
      "notification_email": "[email protected]"
    }
    

    Response object

    Property Description
    id A unique identifier for the subscription
    callback_url It is the URL that will be invoked via webhook on every event
    event_type Can be one of the following values: FAX_CALL, PHONE_CALL, CLICK_TO_CALL, CALL_STARTED, CALL_INCOMING, CALL_ANSWERED, CALL_HANGUP
    enabled Boolean to enable / disable subscription
    failed_count Number of failed attempts
    last_error Last occurred error
    notification_email Email that will be used for notifications if your subscription become disabled

    Delete a webhook subscription

    This endpoint removes an existing webhook subscription

    HTTP Request

    DELETE https://developer.voxloud.com/api/v1/webhook-subscriptions/${id}

    curl -X DELETE -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voxloud.com/api/v1/webhook-subscriptions/119a7b3d-00b9-4445-808a-a69676f86763"
    

    Webhooks

    On occurrence of specific events on our platform, we can call your system through webhooks mechanism. You will receive a payload that helps you integrating your application with Voxloud. You need to setup a webhook subscription to receive these webhooks.

    Every webhook that is sent has the following structure:

    {
      "timestamp": 1523025126000,
      "type": "CALL_STARTED",
      "data": {
        "timestamp": 1523025126000,
        "destinationNumber": "102",
        "destinationName": "User2 User2",
        "originatorNumber": "101",
        "originatorName": "User1 User1",
        "callId": "9cb33f1b427c4d8983a064f0bd68be95",
        "type": "STARTED",
        "userExtension": 101
      },
      "pbx_id": 117
    }
    

    The fields timestamp, type, and pbx_id are common to every webhook, while the data payload varies depending on the event type. All the event types are described in the following sections.

    Phone call events

    These webhooks are sent in real-time on occurence of some conditions on phone calls. They are emitted in the following conditions:

    Property Type Description
    timestamp number Event timestamp represented in milliseconds elapsed from 01/01/1970 (Unix Epoch)
    callId string Call identifier
    destinationNumber string The destination number (callee) expressed in e164 format
    destinationName string Name of the user as configured in the PBX
    originatorNumber string The caller number expressed in e164 format
    originatorName string The caller name (where allowed) or some other identification string as configured in the PBX
    type string Can be one of the following values: INCOMING, STARTED, ANSWERED, HANGUP
    userExtension number Extension of the user subject of the event

    Example of a JSON payload on an incoming call

    {
        "timestamp": 1512552226000,
        "callId": "9cb33f1b427c4d8983a064f0bd68be95",
        "destinationNumber": "+3912345678",
        "destinationName": "Some User",
        "originatorNumber": "+390687654321",
        "originatorName": "Another User",
        "type": "INCOMING",
        "userExtension" : 101
    }
    

    Telephony events

    These webhooks are sent at the end of a series of micro-events (e.g. at the end of a phone call lasted 2 minutes) and represent the CDR (Call Detail Record). A delay of some seconds is normally present from the last micro-event to the dispatch of these webhooks, due to the processing of some additional data (e.g. call recording, call cost, ...). They are emitted for the following events:

    Phone call

    A phone call event has the following payload:

    Property Type Description
    timestamp number Event timestamp represented in milliseconds elapsed from 01/01/1970 (Unix Epoch)
    callId string Call identifier
    destinationNumber string The destination number (callee) expressed in e164 format
    destinationName string Name of the user as configured in the PBX
    originatorNumber string The caller number expressed in e164 format
    originatorName string The caller name (where allowed) or some other identification string as configured in the PBX
    answererName string The answerer name (where allowed) or some other identification string as configured in the PBX
    answererNumber string The answerer number expressed in e164 format
    maskCallerNumber boolean True if the caller number was masked
    type string Can be one of the following values: PHONE_CALL, FAX_CALL, CLICK_TO_CALL
    direction string Can be one of the following values: INTERNAL, OUTBOUND, INBOUND
    accountId string PBX unique identifier
    lastEvent string Last event occurred on a phone call. Can be one of the following values: CALL_REQUEST, CALL_STARTED, CALL_CANCELED_BY_ORIGINATOR, CALL_ANSWERED, CALL_TERMINATED, CALL_REJECTED, CALL_LOST_LOSE_RACE, CALL_LOST_NO_ANSWER, CALL_TRANSFERRED, CALL_LOST_USER_BUSY
    duration number Duration of the phone call in seconds (ringTime included)
    ringTime number Duration of the call before first answerer action
    archived boolean True if this event has been marked as archived
    recorded boolean True if this phone call has an associated call recording
    recordingUrl string The URL of the recorded media (if phone call recording is enabled)
    voicemail boolean True if this event has a voicemail
    labels array (string) Custom labels assigned to the call
    ruleNames array (string) Names of the IVR rules triggered during the call
    contactCrm string Name of the CRM contact was found in
    contactCrmUrl string URL to the contact on CRM
    crmLogo string URL to the CRM logo
    transcription string Transcription of the call (length <= 65,535)
    summary string Short summary of the call (length <= 3500)
    sentiment_score number Numeric representation of call sentiment (0 - 100)

    Example of a JSON payload on an incoming call

    {
        "id": 8395,
        "type": "PHONE_CALL",
        "accountId": "faffd4879c2b686fe9c5fb1673ce2800",
        "direction": "INTERNAL",
        "timestamp": 1523369486000,
        "originatorName": "User1 User2",
        "originatorNumber": "101",
        "destinationName": "User2 User2",
        "destinationNumber": "102",
        "answererName": "User2 User2",
        "answererNumber": "102",
        "maskCallerNumber" : false,
        "lastEvent": "CALL_TERMINATED",
        "duration": 4,
        "ringTime": 1,
        "archived": false,
        "callId": "1734bfbbd5dc4a9c8de1d2e5235e6389",
        "recorded": true,
        "recordingUrl": "https://vmediaproduction.s3.eu-central-1.amazonaws.com/213/call_recordings/call_recording_1734bfbbd5dc4a9c8de1d2e5235e6389.mp3",
        "voicemail": true,
        "voicemail_url": "https://vmediaproduction.s3.eu-central-1.amazonaws.com/213/call_recordings/vm_1734bfbbd5dc4a9c8de1d2e5235e6389.mp3",
        "labels" : [ "label1", "label2" ],
        "ruleNames" : [ "IVRRule1", "IVRRule2" ],
        "contactCrm" : "Hubspot",
        "contactCrmUrl"  : "https://app.hubspot.com/contacts/1111111/contact/1111111",
        "crmLogo" : "https://fake.cloudfront.net/image/logos/fake-hubspot.png",
        "transcription": "Workers who telecommute tend to be more aware of cybersecurity threats than those who spend most of their time in a physical office and are more likely to take action to ward them off, according to our new peer-reviewed study.",
        "summary": "A study has found that remote workers tend to be more aware of cybersecurity threats and are more likely to take action to protect against them compared to in-office workers.",
        "sentiment_score": 73
    }
    

    Fax

    A fax event has the following payload:

    Property Type Description
    timestamp number Event timestamp represented in milliseconds elapsed from 01/01/1970 (Unix Epoch)
    id number Identifier of the fax
    recipient string The recipient number expressed in e164 format
    sender string The sender number expressed in e164 format
    direction string The direction of the fax (inbound, outbound)
    attachment_url string The URL of the fax attachment
    total_pages number The number of total page of the fax attachment
    description string The fax description (only present if outbound faxes)

    Example of a JSON payload on an outbound fax

    {
        "id": 1234,
        "timestamp": 1523369486000,
        "direction": "outbound",    
        "sender": "39123456789",
        "recipient": "39987654321",
        "attachment_url": "https://prod-fax-service.s3.eu-central-1.amazonaws.com/1/1/fax_2011_5_11_11_32_30.pdf",
        "total_pages": 4,
        "description": "A fax description"
    }
    

    Click to call

    A click to call event has the following payload:

    Property Type Description
    timestamp number Event timestamp represented in milliseconds elapsed from 01/01/1970 (Unix Epoch)
    id number Identifier of the click to call event
    callId string Call identifier
    destinationNumber string The destination number (callee) expressed in e164 format
    destinationName string Name of the user as configured in the PBX
    originatorNumber string The caller number expressed in e164 format
    originatorName string The caller name (where allowed) or some other identification string as configured in the PBX
    clickToCallType string Can be one of the following values: EXTENSION, CONTACT
    direction string Can be one of the following values: INTERNAL, OUTBOUND, INBOUND
    accountId string PBX unique identifier
    duration number Duration of the phone call in seconds
    ringTime number Duration of the call before first answerer action
    archived boolean True if this event has been marked as archived
    recorded boolean True if this phone call has an associated call recording
    recordingUrl string The URL of the recorded media (if phone call recording is enabled)
    labels array (string) Custom labels assigned to the call
    ruleNames array (string) Names of the IVR rules triggered during the call
    contactCrm string Name of the CRM contact was found in
    contactCrmUrl string URL to the contact on CRM
    crmLogo string URL to the CRM logo
    transcription string Transcription of the call (length <= 65,535)
    summary string Short summary of the call (length <= 3500)
    sentiment_score number Numeric representation of call sentiment (0 - 100)

    Example of a JSON payload on a click to call

    {
        "id": 517,
        "type": "CLICK_TO_CALL",
        "accountId": "2b7c39f77b46eb2899fc39d0b1bd4329",
        "direction": "OUTBOUND",
        "timestamp": 1569525122000,
        "originatorName": "Pinco Pallino",
        "originatorNumber": "390663971096",
        "destinationName": "393287035654",
        "destinationNumber": "393287035654",
        "duration": 40,
        "ringTime": 1,
        "queueCallId": "303b553038d9847c93ca59ebd310225fae95-clicktocall",
        "clickToCallType": "EXTENSION",    
        "archived": false,
        "callId": "303b553038d9847c93ca59ebd310225fae95-clicktocall",
        "recorded": true,
        "recordingUrl": "https://voxloud.s3.eu-central-1.amazonaws.com/6/call_recordings/call_recording_303b553038d9847c93ca59ebd310225fae95-clicktocall.mp3",
        "labels" : [ "label1", "label2" ],
        "ruleNames" : [ "IVRRule1", "IVRRule2" ],
        "contactCrm" : "Hubspot",
        "contactCrmUrl"  : "https://app.hubspot.com/contacts/1111111/contact/1111111",
        "crmLogo" : "https://fake.cloudfront.net/image/logos/fake-hubspot.png",
        "transcription": "Workers who telecommute tend to be more aware of cybersecurity threats than those who spend most of their time in a physical office and are more likely to take action to ward them off, according to our new peer-reviewed study.",
        "summary": "A study has found that remote workers tend to be more aware of cybersecurity threats and are more likely to take action to protect against them compared to in-office workers.",
        "sentiment_score": 73
    }
    

    Telephony events API

    This API allows you to query for telephony events and get their details. This includes phone calls and fax calls

    Query

    This endpoint gives the possibility to perform paged queries on telephony events. The result can be returned as application/json or text/csv. This is handled by specifying the Accept header with the desired representation. By default, JSON is returned.

    HTTP Request

    POST https://developer.voxloud.com/api/v1/telephony-events

    This request fetches all events related to number 06123456789, between dates 2018-03-11T07:00:00.000Z and 2018-04-16T07:00:00.000Z

    curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    -d '{"date_time_from":"2018-03-11T07:00:00.000Z","date_time_to":"2018-04-16T07:00:00.000Z", "number":"06123456789"}'
    "https://developer.voxloud.com/api/v1/telephony-events?sort=timestamp,desc&size=30&page=0"
    

    It returns JSON structured like this:

    {
        "content": [
         {
                "id": 8563,
                "type": "FAX_CALL",
                "accountId": "faffd4879c2b686fe9c5fb1673ce2800",
                "direction": "INBOUND",
                "timestamp": "2018-05-15T15:47:03.000+0000",
                "originatorName": "anonymous",
                "originatorNumber": "anonymous",
                "destinationName": "3907331980093-fax-caller-id-name",
                "destinationNumber": "3907331980093",
                "callId": "fae5d4a5-d2f9-1236-57a7-06f6192f6ec4",
                "duration": 32,
                "archived": false
            },
                  {
                "id": 8536,
                "type": "PHONE_CALL",
                "accountId": "faffd4879c2b686fe9c5fb1673ce2800",
                "direction": "INBOUND",
                "timestamp": "2018-05-07T13:47:49.000+0000",
                "originatorName": "Emanuele De Amicis",
                "originatorNumber": "0697631539",
                "destinationName": "3907761790162",
                "destinationNumber": "3907761790162",
                "lastEvent": "CALL_CANCELED_BY_ORIGINATOR",
                "duration": 7,
                "archived": false,
                "callId": "125113c1-cca0-1236-9ea3-06f6192f6ec4",
                "recorded": false,
                "voicemail": false
            }
      ],
        "last": true,
        "totalElements": 8,
        "totalPages": 1,
        "sort": [
            {
                "direction": "DESC",
                "property": "timestamp",
                "ignoreCase": false,
                "nullHandling": "NATIVE",
                "ascending": false,
                "descending": true
            }
        ],
        "first": true,
        "numberOfElements": 8,
        "size": 30,
        "number": 0
    }
    

    Request object

    Property Required Description
    number false Telephone number to fetch events related to it
    date_time_from false Temporal interval start in ISO8601 format with timezone (example for UTC = 2021-01-01T00:00:00.000Z)
    date_time_to false Temporal interval end in ISO8601 format with timezone (example for Europe/Rome = 2021-01-01T00:00:00.000+01:00)

    Request parameters

    Parameter Required Description
    sort false The property used for sorting the query results. The syntax should be like: sort=timestamp,desc where timestamp is the name of the property and desc is indicating descending sorting
    size false The number of elements in a query page
    page false The number of requested query page

    Response object (JSON)

    Property Description
    content The array of query elements (see webhooks) for element field details
    last Indicates if this is the last page of the result set
    totalElements The total number of elements in the result set
    totalPages The number of pages in the result set
    sort.property The property name used to sort the result set
    sort.ascending Indicates if the result set is sorted ascending
    sort.descending Indicates if the result set is sorted descending
    first true if this is the first page in the result set
    numberOfElements Number of elements in this page
    size The size of the page
    number The number of page

    Get by ID

    This endpoint returns a telephony event using its ID

    HTTP Request

    GET https://developer.voxloud.com/api/v1/telephony-events/${id}

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voxloud.com/api/v1/telephony-events/11231"
    

    It returns JSON structured like the ones described in section webhooks

    Get by callId

    This endpoint returns a telephony event using its callId

    HTTP Request

    GET https://developer.voxloud.com/api/v1/telephony-events?callId=${callId}

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key"
    "https://developer.voxloud.com/api/v1/telephony-events?callId=aabbccddeeff123456"
    

    It returns JSON structured like the ones described in section webhooks

    Click-to-call API

    This feature allows you to generate click-to-call resources that can be invoked, giving a contact number and creating a phone call from the provided contact to an extension you have pre-determined. For example, this mechanism can be used to call back users visiting your site, allowing them to be put directly in contact with your PBX extensions. Important: click-to-call objects should be reused after their creation as there is a limit on the amount of click-to-call objects that can be created and it is dependent on the sum of number of users (extensions) and groups. For example, if your PBX has 3 users and 2 groups, you will be allowed to create a total of 5 click-to-call objects.

    Create a click-to-call

    This endpoint creates a click-to-call resource

    HTTP Request

    POST https://developer.voxloud.com/api/v1/click-to-call

    This request creates a click-to-call resource for extension 101

    curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    -d '{"name":"support","extension":"101","outboundNumber":"+39123456789","dial_first":"contact"}'
    "https://developer.voxloud.com/api/v1/click-to-call"
    

    It returns JSON structured like this:

    {
        "id": "8ff3728fb5c5d9560e81c3c7080c3b95",
        "name": "ctc-support",
        "extension": "101",
        "outboundNumber": "+390660786731",
        "dial_first": "contact"
    }
    

    Request object

    Property Required Description
    name true Friendly name for the click-to-call resource
    extension true The extension to be called
    outboundNumber true The outbound number used to call the contact. It should match one of your PBX configured numbers
    dial_first false Indicates who will be called first. Allowed values are contact or extension. Default value: extension

    Response object

    Property Description
    id A unique identifier for the click-to-call resource
    extension It is the URL that will be invoked via webhook on every phone call fact
    outboundNumber true
    dial_first Indicates who will be called first. Allowed values are contact or extension

    Get a click-to-call

    This endpoint returns an existing click-to-call resource

    HTTP Request

    GET https://developer.voxloud.com/api/v1/click-to-call/${id}

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voxloud.com/api/v1/click-to-call/8ff3728fb5c5d9560e81c3c7080c3b95"
    

    It returns JSON structured like this:

    {
        "id": "8ff3728fb5c5d9560e81c3c7080c3b95",
        "name": "ctc_support",
        "extension": "101",
        "outboundNumber": "+390660786731",
        "dial_first": "contact"
    }
    

    Response object

    Property Description
    id A unique identifier for the click-to-call resource
    extension It is the URL that will be invoked via webhook on every phone call fact
    outboundNumber true
    dial_first Indicates who will be called first. Allowed values are contact or extension

    Get all click-to-call

    This endpoint returns all existing click-to-call resources

    HTTP Request

    GET https://developer.voxloud.com/api/v1/click-to-call

    curl -X GET -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voxloud.com/api/v1/click-to-call"
    

    It returns JSON structured like this:

    [
        {
            "id": "8ff3728fb5c5d9560e81c3c7080c3b95",
            "name": "ctc-support",
            "extension": "101",
            "outboundNumber": "+390660786731",
            "dial_first": "contact"
        },
        {
            "id": "7fad6102abe18759324cd292344aa3213",
            "name": "ctc-marketing",
            "extension": "102",
            "outboundNumber": "+390660786731",
            "dial_first": "contact"
        }
    ]
    

    Response object

    An array of the following objects:

    Property Description
    id A unique identifier for the click-to-call resource
    extension It is the URL that will be invoked via webhook on every phone call fact
    outboundNumber true
    dial_first Indicates who will be called first. Allowed values are contact or extension

    Delete a click-to-call

    This endpoint removes an existing click-to-call resource

    HTTP Request

    DELETE https://developer.voxloud.com/api/v1/click-to-call/${id}

    curl -X DELETE -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    "https://developer.voxloud.com/api/v1/click-to-call/8ff3728fb5c5d9560e81c3c7080c3b95"
    

    Connect click-to-call

    This endpoint setups a call between the extension indicated in the click-to-call resource and the provided contact. Depending on the value of the dial_first field, the contact or the extension is called first.

    HTTP Request

    POST https://developer.voxloud.com/api/v1/click-to-call/${id}/connect

    This request connects with a phone call contact +39123456789 and extension 101

    curl -X POST -H "Content-Type: application/json" -H "Voverc-Auth: your_api_key" 
    -d '{"contact":"+39987654321"}'
    "https://developer.voxloud.com/api/v1/click-to-call/8ff3728fb5c5d9560e81c3c7080c3b95/connect"
    

    It returns JSON structured like this:

    {
      "contact": "+39987654321"
    }
    

    Request object

    Property Required Description
    contact true Contact number in e164 format

    Response object

    Property Description
    contact Contact number in e164 format

    Errors

    The Voxloud API uses the following error codes:

    Error Code Meaning
    400 Bad Request -- Your request is not well-formed.
    401 Unauthorized -- Your API key is wrong.
    403 Forbidden -- The requested resource is not accessible with your credentials.
    404 Not Found -- The specified resource could not be found.
    405 Method Not Allowed -- You tried to access an endpoint with an invalid method.
    406 Not Acceptable -- You requested a format that isn't JSON.
    429 Too Many Requests -- You're doing too many requests! Slow down!
    500 Internal Server Error -- We had a problem with our server. Try again later.
    503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.