Ubity API Documentation

Agents

2026-08-18T00:00:00-04:00

An agent is an extension that answers the calls of one or more queues. These endpoints manage queue agents: log an agent in or out of one or more queues, pause/unpause an agent (a paused agent stays logged in but temporarily stops receiving queue calls), and get an agent's activity report — logged time, pauses, adherence and per-queue call statistics.

The account is normally implied by your API key. If your key gives access to several accounts, add an account parameter to select one.

The POST endpoints below expect a JSON body (send the header Content-Type: application/json), because queue_names is a list.

Log an agent in

Log an agent (an extension) into one or more queues.

POST https://api.ubity.com/agent/<extension>/login

Parameter	Description
key	Your Ubity API key
queue_names	The list of queue names to log the agent into
lang	The agent's language (ie. 'en', 'fr')

% curl -X POST -H "Accept: application/json;version=0" -H "Content-Type: application/json" \
    -d '{"queue_names": ["myqueue-QQQQ"], "lang": "en"}' \
    "https://api.ubity.com/agent/101/login?key=KKKK"

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "stamp": "2026-08-18 10:00",
  "url": "https://api.ubity.com/agent/101/login?key=KKKK",
  "version": 0
}

Log an agent out

POST https://api.ubity.com/agent/<extension>/logout

Parameter	Description
key	Your Ubity API key
queue_names	The list of queue names to log the agent out of

% curl -X POST -H "Accept: application/json;version=0" -H "Content-Type: application/json" \
    -d '{"queue_names": ["myqueue-QQQQ"]}' \
    "https://api.ubity.com/agent/101/logout?key=KKKK"

Pause an agent

A paused agent stays logged in the queues but does not receive queue calls.

POST https://api.ubity.com/agent/<extension>/pause

Parameter	Description
key	Your Ubity API key
queue_names	The list of queue names in which to pause the agent
reason	The pause reason (free text, ie. 'lunch')

% curl -X POST -H "Accept: application/json;version=0" -H "Content-Type: application/json" \
    -d '{"queue_names": ["myqueue-QQQQ"], "reason": "lunch"}' \
    "https://api.ubity.com/agent/101/pause?key=KKKK"

Unpause an agent

POST https://api.ubity.com/agent/<extension>/unpause

Parameter	Description
key	Your Ubity API key
queue_names	The list of queue names in which to unpause the agent

% curl -X POST -H "Accept: application/json;version=0" -H "Content-Type: application/json" \
    -d '{"queue_names": ["myqueue-QQQQ"]}' \
    "https://api.ubity.com/agent/101/unpause?key=KKKK"

Get an agent's activity

GET https://api.ubity.com/agent/<extension>

Parameter	Description
key	Your Ubity API key
period	(optional) 'live' (today, default), 'day' (yesterday), 'week' or 'month'
dashboard	(optional) '1' or 'true' to get the extended dashboard report (queues, warnings, ...)

The reply contains:

Field	Description
activity	The agent's activity: paused state, adherence, logged duration, ...
fullname	The agent's full name
callerid_name	The agent's caller ID name
callerid_num	The agent's caller ID number

With dashboard=1, the reply also contains the per-queue details (queues), the login/adherence warnings, the covered period and the outgoing calls statistics.

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/agent/101?key=KKKK&period=week"

Call Detail Records (CDR)

2026-08-18T00:00:00-04:00

A call detail record (CDR) is written for every call handled by the platform: who called whom, when, for how long, through which queue or conference, and how the call ended. These endpoints return the call detail records (call history) of your account, one month or one day at a time — a simple way to feed your own reporting, billing checks or CRM journaling.

The account is normally implied by your API key. If your key gives access to several accounts, add an account parameter to select one.

List CDRs for a month or a day

GET https://api.ubity.com/cdr/<year>/<month>

GET https://api.ubity.com/cdr/<year>/<month>/<day>

Parameter	Description
key	Your Ubity API key

Each record contains:

Field	Description
id	The unique id of the call
date	The call date, as a Unix timestamp in milliseconds
from_number	The calling number
from_ext	The calling extension (if any)
to_num	The called number
to_ext	The called extension (if any)
duration	The call duration, in seconds
queue	The queue name, when the call went through a queue
conf_name	The conference name, when the call was a conference
disposition	The call disposition (ie. 'ANSWERED', 'NO ANSWER', ...)
type	The call type (see below)

The type field is one of: internal, local, long-distance, inbound, toll-free, international, conference, service (calls to 311/411/511/611/811/911) or unknown.

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/cdr/2026/08/17?key=KKKK"

{
  "api_key": "KKKK",
  "cdrs": [
    {
      "id": "1755430000.1234",
      "date": 1755430000000,
      "from_number": "5145551212",
      "from_ext": "",
      "to_num": "5145550000",
      "to_ext": "101",
      "duration": 63,
      "queue": "",
      "conf_name": "",
      "disposition": "ANSWERED",
      "type": "inbound"
    }
  ],
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "stamp": "2026-08-18 10:00",
  "url": "https://api.ubity.com/cdr/2026/08/17?key=KKKK",
  "version": 0
}

Find the CDRs matching a recording

Given a call recording file name (as returned by the recordings endpoints), return the matching CDRs. The records have the same fields as above.

GET https://api.ubity.com/cdr_by_recording/<filename>

Parameter	Description
key	Your Ubity API key

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/cdr_by_recording/1755430000.1234.mp3?key=KKKK"

Queues

2026-08-18T00:00:00-04:00

A call queue holds incoming calls and distributes them to the agents logged into it. These endpoints report the live state (who is logged in, who is available, how many calls are waiting) and the historical statistics of the call queues of your account, and let you adjust the penalty of an agent in a queue. They are the natural companions of the agents endpoints, which act on the agents themselves, and of /queue_call, which places an outgoing call into a queue.

The account is normally implied by your API key. If your key gives access to several accounts, add an account parameter to select one.

List queues (live state)

GET https://api.ubity.com/queues

Parameter	Description
key	Your Ubity API key
monitor	(optional) '1' or 'true' to include today's monitoring statistics

Each entry of queues is keyed by the queue name and contains:

Field	Description
num_agents	Number of agents currently logged in the queue
available_agents	Extensions of the agents currently available
all_agents	Extensions of all the agents logged in the queue
waiting	The calls currently waiting in the queue

With monitor=1, each queue also contains queue_stats, inqueue, longest_wait, today_longest_wait and average_wait (durations are formatted as HH:MM:SS).

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/queues?key=KKKK"

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "queues": {
    "myqueue-QQQQ": {
      "num_agents": 3,
      "available_agents": ["101", "103"],
      "all_agents": ["101", "102", "103"],
      "waiting": []
    }
  },
  "stamp": "2026-08-18 10:00",
  "time": "2026-08-18 10:00:12",
  "url": "https://api.ubity.com/queues?key=KKKK",
  "version": 0
}

List the agents of a queue

GET https://api.ubity.com/queue/<queue_name>/agents

(https://api.ubity.com/queue_agents/<queue_name> is an accepted alias)

Parameter	Description
key	Your Ubity API key

Returns one entry per agent of the queue, with (among others) the following fields:

Field	Description
agent	The agent's extension
fullname	The agent's full name
queue	The queue name
state	'available', 'oncall', 'paused', 'wrapuptime', ...
penalty	The agent's penalty in that queue (lower is called first)

Answers 404 if the queue does not exist in your account.

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/queue/myqueue-QQQQ/agents?key=KKKK"

Set the penalty of an agent in a queue

The penalty orders the agents inside a queue: agents with a lower penalty are called first, and agents with a higher penalty only receive calls when the lower-penalty agents are busy or unavailable. This is a light-weight way to define primary and backup agents, or to temporarily push an agent to the back of a queue without logging them out.

PUT https://api.ubity.com/queue/<queue_name>/agent/<extension>

Parameter	Description
key	Your Ubity API key
penalty	'inc', 'dec', or a number >= 0

Returns the new penalty.

% curl -X PUT -H "Accept: application/json;version=0" "https://api.ubity.com/queue/myqueue-QQQQ/agent/101?key=KKKK" -d penalty=inc

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "penalty": 2,
  "stamp": "2026-08-18 10:05",
  "url": "https://api.ubity.com/queue/myqueue-QQQQ/agent/101?key=KKKK",
  "version": 0
}

Queue statistics

GET https://api.ubity.com/queue/<queue_name>/stats

GET https://api.ubity.com/queue/<queue_name>/stats/<start>

GET https://api.ubity.com/queue/<queue_name>/stats/<start>/<end>

Parameter	Description
key	Your Ubity API key
start	(optional, in URL) Unix timestamp (seconds); rounded down to start of the day
end	(optional, in URL) Unix timestamp (seconds); rounded up to end of the day
agent	(optional) restrict the statistics to one agent's extension

Use ALL as <queue_name> to get the statistics of every queue of the account.
Without start, the statistics cover the current day.
Without end, the statistics cover the single day of start.
The date range is limited (about 100 days); a larger range answers 400.

The reply contains, per queue: total_calls, answered_calls, abandoned_calls, average_duration, total_duration, average_waiting_duration, abandon_average_duration and abandon_percent, plus per-agent statistics and a grand total.

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/queue/ALL/stats/1755230400/1755835200?key=KKKK"

Introduction

2019-08-30T00:00:00-04:00

Welcome to the Ubity API documentation.

The Ubity API is a simple HTTPS/REST-style API that gives your applications programmatic access to the Ubity telephony/UC platform. With it you can, among other things:

initiate and control calls (answer, hang up, transfer, send to voicemail),
place calls into your call queues, monitor those queues and manage their agents,
send and receive text messages (SMS),
browse your call history (CDR) and download your call recordings,
get the live phone presence status of your users/extensions,
be notified of call events on your account through HTTP callbacks.

All requests are made against the base URL:

https://api.ubity.com

Every request must be authenticated with an API key (see the Authentication section) and should carry an Accept header selecting the encoding and the API version (see the Requesting, headers and encoding section). Unless noted otherwise, replies share a common envelope containing at least code, diagnostic, stamp, url and version, alongside the data specific to the endpoint.

Sample code is available in Shell (curl) in the dark area to the right. The examples use placeholders such as KKKK (your API key), QQQQ (a queue name) or EEE (an extension); replace them with your own values.

Authentication

2019-08-29T00:00:00-04:00

To interact with the Ubity API, you will need an API key. You can request an API key by writing to Ubity Support.

The Ubity API expects an API key to be included in all API requests to the server as part of the GET or POST parameters, using the key parameter:

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/extensions?key=KKKK"

What a key carries

An API key is not only a secret: it also defines what the requests made with it are allowed to do.

A key always belongs to an application, which conveys a set of permissions. Some endpoints require a specific permission to be granted to the application.
A key may be bound to a user; in that case a permission must be granted both to the application and to the user.
A key may be bound to an account, in which case all the requests made with it are limited to the realm of that account. When a key is not bound to a single account (for example an integrator's key which manages several customer accounts), the endpoints that operate on an account accept an account parameter to select the account to work on.

A key may also carry a few restrictions: a list of allowed source IP addresses, an absolute expiration date, or an inactivity timeout. Requests that do not satisfy these restrictions are answered with a 401 error and a diagnostic explaining the reason.

Keeping the key secret

The API key is a secret; treat it like a password. Do not embed it in client-side code delivered to end users, and take reasonable measures to keep it out of logs and version control.

All requests to the API must be made using HTTPS. ↩

Requesting, headers and encoding (and version)

2019-08-28T00:00:00-04:00

Most endpoints support both GET and POST. Parameters may be passed as query-string parameters, as form-encoded POST data, or as a JSON body (with Content-Type: application/json); the three forms are equivalent, and a few endpoints whose parameters are lists — this is then documented — require the JSON body form.

You may specify the encoding the API should use to return data through standard HTTP content negotiation.

The header to use is "Accept" and must contain a version information.

Accept: application/json;version=0

(version must be present, but is usually reserved for the future, therefore, some endpoints like SMS functions require another value, in that case, this is documented)

Available encoders are:

Encoding	Comment
JSON	Available
XML	Available
YAML	partially implemented, nested dictionaries can have issues
TEXT	partially implemented, nested dictionaries can have issues
HTML	not always available, exists for user comfort, but not really usable as an API

The reply envelope

Whatever the encoding, successful replies share a common envelope: the endpoint-specific data is accompanied by a few common fields — code (the HTTP status, repeated in the body), diagnostic (a short human-readable outcome, "Success" on success), stamp (the server time of the reply), url (the requested URL) and version (the API version used to answer). Errors use the same envelope, with the appropriate code and a diagnostic explaining what went wrong.

Here is an example of a query with good headers:

% curl -H 'Accept: application/json;version=0' 'https://api.ubity.com/call?key=KKKK&exten=EEE&number=NNN'

{
 "api_call_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "api_key": "KKKK",
 "code": 200,
 "diagnostic": "Success",
 "mode": "normal",
 "stamp": "2018-02-06 10:10",
 "url": "https://api.ubity.com/call?key=KKKK&exten=EEE&number=NNN",
 "version": 0
}

For historical reasons and compatibility concerns, some endpoints do not have a consistent encoding when used without specifying headers. This is called the legacy behaviour, it's not supported nor documented, please don't use it (anymore) as it can be removed at any moment. So, it's strongly recommended to always request using the headers (encoding and version). ↩

Calls

2019-08-27T00:00:00-04:00

These endpoints let your application place calls on behalf of your users and control the calls in progress on your account: list them, answer them, send them to voicemail or hang them up. A typical click-to-call integration only needs /call; supervision or screen-pop applications will also use /calls and the per-call actions below, together with the event callbacks.

Initiate An Outgoing Call

Initiate an outgoing call on behalf of a user. The user who initiates the call is called first, and upon answering that call, is connected to the other party. The initial call will contain the other party's phone number as the CallerID number.

GET or POST https://api.ubity.com/call

Parameter	Description
key	Your Ubity API key
exten	The extension or phone number of the user initiating the call (ie. '100')
number	The extension or phone number to call (ie. '5145551212')
redirect	The HTTP redirect code and URL that the API must answer (useful from a web browser)
cid_name	Lets you override the default callerid name (you must specify a 'cid_num' too)
cid_num	Lets you override the default callerid number (you must own that number at Ubity)
autoanswer	('on' 'off' '1' or '0' The extension will autoanswer if 'on' or '1')

Any arbitrary parameter is accepted and will be given back along the callbacks related to that call (see callback section).

The phone or softphone bound to your extension MUST understand the auto-answer SIP header.

Alert-Info: info=alert-autoanswer

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/call?key=KKKK&exten=EEE&number=NNN"

{
 "api_call_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
 "api_key": "KKKK",
 "code": 200,
 "diagnostic": "Success",
 "mode": "normal",
 "stamp": "2018-02-06 10:10",
 "url": "https://api.ubity.com/call?key=KKKK&exten=EEE&number=NNN",
 "version": 0
}

`api_call_uuid`

The api_call_uuid can be found or used with the following method (or because /call was used to trigger a call and you got it in response).

List running calls

GET or POST https://api.ubity.com/calls

Parameter	Description
key	Your Ubity API key
filter	A simple string to filter calls list

curl -H 'Accept: application/json;version=0' 'https://api.ubity.com/calls?key=KKKK'

{
  "api_key": "KKKK",
  "calls": {
    "hrVVY8OX0NIkEbwAbK3STB3i_kWlyOZ9Zs5DWsNGsxE": {
      "api_call_uuid": "9bab78c0-511f-471e-908f-676ca7ccf8ca",
      "answered": true,
      "from_callerid_name": "Foo Bar",
      "from_callerid_num": "42",
      "to_callerid_name": "",
      "to_callerid_num": "5556548424",
      "ts": 1518555171.0
    },
    "hrVVY8OX0NIkEbwAbYQYM0DGO9YdFz_v2QvTu257730": {
      "answered": true,
      "from_callerid_name": "Baz Qwe",
      "from_callerid_num": "43",
      "to_callerid_name": "Plouf",
      "to_callerid_num": "44",
      "ts": 1518554523.0
    },
  },
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "stamp": "2018-02-13 15:54",
  "url": "https://api.ubity.com/calls?key=KKKK",
  "version": 0
}%

In that example, the first call was triggered by the API, so it has additional data: api_call_uuid which is the id that the /call query would have returned.
You can also see that calls is a dictionary. The keys of that dictionary are the long id of each call.

In the example we can see a call with the long id is hrVVY8OX0NIkEbwAbK3STB3i_kWlyOZ9Zs5DWsNGsxE and the api_call_uuid is 9bab78c0-511f-471e-908f-676ca7ccf8ca.

Answering a call

GET or POST https://api.ubity.com/call_answer

Parameter	Description
key	Your Ubity API key
call	The long id of the call you want to answer

curl -H 'Accept: application/json;version=0' 'https://api.ubity.com/call_answer?key=KKKK&call=hrVVY8OX0NIkEbwAb4wI7opkNE4xcZ4YVv955CSyXEk'

{
  "answered": true,
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "stamp": "2018-02-13 16:18",
  "url": "https://api.ubity.com/call_answer?key=KKKK&call=hrVVY8OX0NIkEbwAb4wI7opkNE4xcZ4YVv955CSyXEk",
  "version": 0
}

Send a call to voicemail (while ringing)

GET or POST https://api.ubity.com/call_send_to_voicemail

Parameter	Description
key	Your Ubity API key
call	The long id of the call you want to send to voicemail

curl -H 'Accept: application/json;version=0' 'https://api.ubity.com/call_send_to_voicemail?key=KKKK&call=hrVVY8OX0NIkEbwAb41tLtzMyxhBdsxSD8cgzglWbRs'

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "sent_to_voicemail": true,
  "stamp": "2018-02-13 16:17",
  "url": "https://api.ubity.com/call_send_to_voicemail?key=KKKK&call=hrVVY8OX0NIkEbwAb41tLtzMyxhBdsxSD8cgzglWbRs",
  "version": 0
}

Hangup a call

GET or POST https://api.ubity.com/call_hangup

Parameter	Description
key	Your Ubity API key
call	The long id of the call you want to hangup

curl -H 'Accept: application/json;version=0' 'https://api.ubity.com/call_hangup?key=KKKK&call=hrVVY8OX0NIkEbwAbK3STB3i_kWlyOZ9Zs5DWsNGsxE'

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "rang off": true,
  "stamp": "2018-02-13 16:01",
  "url": "https://api.ubity.com/call_hangup?key=KKKK&call=hrVVY8OX0NIkEbwAbK3STB3i_kWlyOZ9Zs5DWsNGsxE",
  "version": 0
}

The phone or softphone bound to your extension MUST understand the auto-answer SIP infos packet. Alert-Info: info=alert-autoanswer ↩

Queue calls

2019-08-26T00:00:00-04:00

Trigger/schedule a call to a queue

Initiate a call and place it in a queue.

This is the "call back" building block: instead of connecting the called party to a specific user (as /call does), the call is placed into one of your call queues and will be distributed to the next available agent, exactly as if the person had called in and waited. The optional position parameter lets you insert the call at a given waiting position in the queue instead of at the end.

GET or POST https://api.ubity.com/queue_call

Parameter	Description
key	Your Ubity API key
queue	The queue you want the call to be placed in
number	The phone number to call (ie. '5551112222')
redirect	(optional) The HTTP redirect code and URL that the API must answer (useful from a web browser)
timeout	(optional) Timeout
position	(optional) Waiting position in queue

Any arbitrary parameter is accepted and will be given back along the callbacks related to that call (see callback section).

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/queue_call?key=KKKK&queue=QQQQ&number=5551112222"

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "queue_call": true,
  "stamp": "2018-02-16 14:39",
  "url": "https://api.ubity.com/queue_call?key=KKKK&queue=QQQQ&number=5551112222",
  "version": 0
}%

Extensions

2019-08-25T00:00:00-04:00

Get extensions list

This endpoint allows your application to get a list of your company's users, or extensions, as well as their current phone presence status (free, oncall).

Each entry is keyed by the extension number and contains the callerid (the display name of the user), the current state, and updated, the Unix timestamp of the last state change. This is handy to display a live "who is on the phone" view, or to decide whether a call can be transferred to someone right away.

GET or POST https://api.ubity.com/extensions?key=KKKK

Parameter	Description
key	Your Ubity API key

% curl -H "Accept: application/json;version=0" "https://api.ubity.com/extensions?key=KKKK"

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "extensions": {
    "42": {
      "callerid": "Foo Bar",
      "state": "free",
      "updated": 1518636657.0
    },
    "43": {
      "callerid": "Baz Qwe",
      "state": "oncall",
      "updated": 1518627835.0
    },
  },
  "stamp": "2018-02-14 15:37",
  "url": "https://api.ubity.com/extensions?key=KKKK",
  "version": 0
}

Text Messages (SMS)

2019-08-24T00:00:00-04:00

This endpoint delivers a text message (SMS) to a mobile phone number, from one of the phone numbers of your account.

On success, the reply contains a smsid, a unique identifier you can keep to correlate the message with delivery notifications or with your own records.

POST /sms

GET /sms/send

Parameter	Description
key	Your Ubity API key
from_number	Phone number of the sender (ie. 5551112222)
to_number	Phone number of the recipient (ie. 5551113333)
message	Body of the message

curl -H "Accept: application/json;version=1" --data "key=KKKK&from_number=5551112222&to_number=5551113333&message=test" https://api.ubity.com/sms

or

curl -H "Accept: application/json;version=1" "https://api.ubity.com/sms/send?key=KKKK&from_number=5551112222&to_number=5551113333&message=test"

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "mode": "normal",
  "sms": {
    "smsid": "92ee37f0-c315-42fa-b287-ca1f43ca5e62",
    "success": true
  },
  "stamp": "2018-02-14 16:36",
  "url": "https://api.ubity.com/sms",
  "version": 1
}%

The version header must be 1 ↩
Please note that the from_number parameter needs to be a phone number that belongs to your account and has the SMS service enabled. ↩

Call Recordings

2019-08-23T00:00:00-04:00

These endpoints give access to the call recordings of your account: browse them as a hierarchy (year / month / day / direction), download or delete individual recordings, retrieve a recording directly from a call id received in a callback, and pause the recording in the middle of a call. To find the calls matching a recording file name, see the CDR section.

Get recordings list

This endpoint allows you to get a list of your call recordings and their duration in seconds (or null for directories). The recordings are listed by year, month, day, call direction.

The legacy behaviour of that endpoint (when you request without any header) is to give you the list formatted in HTML. Using that HTML view, you can use your browser to access the recordings or you can use a web crawler like wget and download all your recordings in a batch.

GET https://api.ubity.com/recordings

Parameter	Description
key	Your Ubity API key

# Using the wget

wget -r -np -c "https://api.ubity.com/recordings?key=KKKK"

# Example using headers
curl -H "Accept: application/json;version=0" "https://api.ubity.com/recordings?key=KKKK"

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "names": [
    [
      "https://api.ubity.com/recordings/2017?key=KKKK",
      "2017",
      null
    ],
    [
      "https://api.ubity.com/recordings/2018?key=KKKK",
      "2018",
      null
    ]
  ],
  "stamp": "2018-02-15 11:27",
  "title": "",
  "url": "https://api.ubity.com/recordings?key=KKKK",
  "version": 0
}

# Using headers and specific day and direction
% curl -H "Accept: application/json;version=0" "https://api.ubity.com/recordings/2018/02/15/out?key=KKKK"

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "names": [
    [
      "https://api.ubity.com/recordings/2018/02/15/out/42_20180215105055_15551112222_vgw99-1518709855.9602776.mp3?key=KKKK",
      "42_20180215105055_15551112222_vgw99-1518709855.9602776.mp3",
      123
    ],
    [
      "https://api.ubity.com/recordings/2018/02/15/out/43_20180215105055_15551113333_vgw99-1518709855.9602776.mp3?key=KKKK",
      "43_20180215105055_15551113333_vgw99-1518709855.9602776.mp3",
      456
    ],
  ],
  "stamp": "2018-02-15 11:31",
  "title": "2018/02/15/out",
  "url": "https://api.ubity.com/recordings/2018/02/15/out?key=KKKK",
  "version": 0
}

Get one recording from that list

You can just follow the URL available in the list. (headers are not needed)

curl "https://api.ubity.com/recordings/2018/02/15/out/43_20180215105055_15551113333_vgw99-1518709855.9602776.mp3?key=KKKK" --output recording.mp3

Delete one recording from that list

You can just follow the URL available in the list. (headers are not needed), and use the method DELETE.

curl -X DELETE "https://api.ubity.com/recordings/2018/02/15/out/43_20180215105055_15551113333_vgw99-1518709855.9602776.mp3?key=KKKK"

Get a specific call recording from an ID

In some cases, you would want to download a recording from an ID received from a callback. This endpoint allows your application to retrieve the recording of a specific call using its callid. The response is the actual MP3 file, with a Content-Type: audio/mpeg header.

GET https://api.ubity.com/recording

Parameter	Description
key	Your Ubity API key
callid	The call's unique identifier string

curl "https://api.ubity.com/recording?key=KKKK&callid=vgw99-9518705130.2593504" --output recording.mp3

Delete a specific call recording from an ID

In some cases, you would want to delete a recording from an ID received from a callback. This endpoint allows your application to delete the recording of a specific call using its callid.

DELETE https://api.ubity.com/recording

Parameter	Description
key	Your Ubity API key
callid	The call's unique identifier string

curl -X DELETE "https://api.ubity.com/recording?key=KKKK&callid=vgw99-9518705130.2593504"

Check if a call recording actually exists

Your application might want to know if a call recording exists before exposing it to the user (eg: if it's a web application). This endpoint allows your application to tell if a recording exists for a specific call.

GET https://api.ubity.com/recording_exists

Parameter	Description
key	Your Ubity API key
callid	The call's unique identifier string

curl -H "Accept: application/json;version=0" "https://api.ubity.com/recording_exists?key=KKKK&callid=vgw99-9518705130.2593504"

{
  "api_key": "KKKK",
  "code": 200,
  "diagnostic": "Success",
  "exists": true,
  "mode": "normal",
  "stamp": "2018-02-15 12:03",
  "url": "https://api.ubity.com/recording_exists?key=KKKK&callid=vgw99-9518705130.2593504",
  "version": 0
}

Pause recording while on call

You may want to pause recording while on call temporarily (for example when somebody is about to say their credit card number).

GET https://api.ubity.com/pause_recording

Parameter	Description
key	Your Ubity API key
extension	extension with an active call
state	1 for pause 0 for unpause

Tested scenarios are:

Incoming call to extension
Outgoing call from extension
Blind or assisted transfer to extension

curl -H "Accept: application/json;version=0" "https://api.ubity.com/pause_recording?key=KKKK&extension=42&state=1"

{
  "api_key": "KKKK",
  "code": 200,
  "details": {
    "SIP/xxxxxxx-xxxxxxx": {
      "reason": "",
      "success": true
    }
  },
  "diagnostic": "Success",
  "mode": "normal",
  "stamp": "2018-09-26 09:03",
  "url": "https://api.ubity.com/pause_recording?key=KKKK&extension=42&state=1",
  "version": 0
}%

Event Callbacks

2019-08-22T00:00:00-04:00

Event Callbacks are used to notify your application whenever particular events occur on the Ubity telephony/UC platform. These events can range from a user making or receiving a call, to a call being answered or ended.

Callbacks turn the API around: instead of your application polling the platform, the platform calls URLs of your choosing, in real time, as things happen. Combined with the calls endpoints, they are the natural way to build screen-pop, call journaling or CRM integrations. The callid given in each event is stable across the events of one call, and is the same identifier used by the recordings endpoints.

At the moment, these are the events that your application can subscribe to:

CallInitiated event
CallAnswered event
CallEnded event

To set up the callbacks, you will need to ask Ubity Support specifying the URLs you want to be requested for each event. You may have to prove that you own those URLs.

CALLBACK URLS

In order for your application to be notified of a particular event, one or more callback URLs need to be associated to that event.

HTTP REQUEST

Both GET and POST requests are supported.

CallInitiated Event

This event notifies your application whenever a user or extension in your company makes or receives a call. This event indicates that the other end is ringing, and not that it has answered (see CallAnswered event).

HTTP REQUEST

Both GET and POST requests are supported.

QUERY PARAMETERS

Parameter	Description
callid	A unique identifier string for the call
type	The type of the call, or its direction (`incoming`, `outgoing`)
caller	The extension or phone number that initiated the call
callee	The extension or phone number that received the call

EXAMPLES

An outgoing call initiated by extension 100 to phone number 5145551212 will trigger the following event:

GET https://yourapp.com/init?callid=ABC12345&type=outgoing&caller=100&callee=5145551212

An incoming call received by extension 100 from phone number 5145551212 will trigger the following event:

POST https://yourapp.com/init?callid=ABC12345&type=incoming&caller=5145551212&callee=100

CallAnswered Event

This event notifies your application when a previously initiated call (see CallInitiated event) has been answered by its recipient.

HTTP REQUEST

Both GET and POST requests are supported.

QUERY PARAMETERS

Parameter	Description
callid	A unique identifier string for the call (same as `CallInitiated`)
type	The type of the call, or its direction (`incoming`, `outgoing`)
caller	The extension or phone number that initiated the call
callee	The extension or phone number that received the call

EXAMPLES

An outgoing call initiated by extension 100 to phone number 5145551212 has now been answered by 5145551212:

GET https://yourapp.com/answered?callid=ABC12345&type=outgoing&caller=100&callee=5145551212

An incoming call received by extension 100 from phone number 5145551212 has now been answered by extension 100:

POST https://yourapp.com/answered?callid=ABC12345&type=incoming&caller=5145551212&callee=100

CallEnded Event

This event notifies your application when a previously initiated, then answered call is hung up.

HTTP REQUEST

Both GET and POST requests are supported.

QUERY PARAMETERS

Parameter	Description
callid	A unique identifier string for the call (same as `CallInitiated` and `CallAnswered`)
type	The type of the call, or its direction (`incoming`, `outgoing`)
caller	The extension or phone number that initiated the call
callee	The extension or phone number that received the call
duration	The duration of the call (in seconds)

EXAMPLES

An outgoing call between extension 100 and 5145551212 ends after 300 seconds (5 minutes):

GET https://yourapp.com/ended?callid=ABC12345&type=outgoing&caller=100&callee=5145551212&duration=300

An incoming call for extension 100 from 5145551212 ends after 300 seconds (5 minutes):

POST https://yourapp.com/ended?callid=ABC12345&type=incoming&caller=5145551212&callee=100&duration=300

The type or direction of a call is always taken from the user's perspective. ↩