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

You must replace your_api_key with your personal 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"

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",
    "sipUsername": "sip_138oksfg",
    "userEmail": "[email protected]",
    "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:

Inbound call
Call start (outbound and internal)
Answered call
Call hangup

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
userEmail	string	Email address of the user subject of the event
userExtension	number	Extension of the user subject of the event
sipUsername	string	SIP username 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",
    "userEmail" : "[email protected]",
    "userExtension" : 101,
    "sipUsername" : "sip_user"
}

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
Fax
Click to call

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

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"
}

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

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"
}

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.