Introduction
The EQ API is a REST API, which means it uses resource-oriented URLs and makes use of GET, POST, PUT, and DELETE methods to determine the type of action desired. Standard HTTP response codes are used to signify whether the request was successful, and if not, what went wrong; any further error details are included in the body of the response. All data is returned as JSON.
The API is versioned independently of the EQ software package version to ensure that thirty-party clients relying on the API will not be broken with software updates. A certain version of the API can always be expected to work exactly the same way and return data in exactly the same format. New features may be added to an existing version of the API, but existing features will not be changed in any way that would break functionality depending on them.
Base URL
The endpoint URLs are dependent on the domain name or IP address of the server on which EQ is installed. The base URL is therefore: http://[server]/eq/api/2.0
Authentication
API Key
All requests to the API must be authenticated by a valid API key generated on the EQ system. API keys can be generated in EQ Administration.
The API key must be passed in either the URL as a query string parameter called auth_key or in the body of the request if applicable (e.g. the POST data). Either location for the parameter is acceptable for POST, PUT, or DELETE requests. However, due to the nature of GET requests, which have no POST data, the key must be in the URL.
For the sake of consistency, it is recommended to always pass the key in the URL as a query string parameter.
If the key is passed in the URL, the base URL becomes:
http://[server]/eq/api/2.0?auth_key=[key]
User Session API keys requests are always authenticated by the provided API key. However, requests can optionally be additionally authenticated by a user session token if the request is done on behalf of a certain user. To maintain proper historical data, such as activity logs, it is recommended to authenticate requests as a certain user whenever possible. If a user session token is provided, then the session is validated and refreshed (i.e. pinged / kept alive). The entire request will fail with an error if the session is invalid, or if the session token is valid, but for circumstantial reasons, the session is inactive and cannot be reactivated (usually because the user is signed in elsewhere, or another user is signed in at the same extension). In such cases, the HTTP response code will be 401, and the relevant errors will be returned as JSON in the body of the response as with any other request. Keep in mind that any request to the API authenticated as a certain user will cause that user to be signed in again if they were not previously and the session token is valid and there are no circumstantial conflicts. This normally only happens if the user previously timed out. If the user is signed out using the API, the session is destroyed, so it would not be possible that any further requests would accidentally sign them in again. Since there are two primary types of users, supervisors and agents, there are two separate session tokens that can be passed, although only one or the other will be used for any given request. To send a request on behalf of a supervisor, the session token must be passed in the URL or the POST/PUT data as the auth_supervisor_session parameter. For an agent, the session token must be passed as the auth_agent_session parameter. Only one type of session token (supervisor or agent) should be provided on any given request. If both a supervisor session token and an agent session token are passed, the supervisor one will always be given priority, and the agent one will have no effect. If neither session token is provided, then the API request is not authenticated as any certain user, and a valid API key is sufficient to authenticate the request. Like the API key, the user session token can be provided in either the URL (GET, POST, PUT, or DELETE) or in the body of the request (POST, PUT, or DELETE). If the API key and user session token are passed in the URL, the base URL becomes:JSON Parameters
All data is returned as JSON, but some endpoints accept JSON for certain parameters as well. For example, when creating a new agent, the agent's attributes must be passed as a JSON object for the data parameter. In general, endpoints accept/require JSON for parameters when an entire entity is being passed to the API, whether to create it or update it. Otherwise parameters are simply strings. When a JSON object is required for a parameter, some attributes of the object may not be required. In those cases, the attributes may be omitted entirely, and the default value (usually null or blank) will be used.
Deleted Entities
It is important to know how the EQ software treats deleted entities to understand some aspects of the API. For historical reporting purposes, any primary entities that could have historical data attached to them are never actually deleted, but are only flagged as deleted. Users, queues, and pause codes are some examples. Such entities contain a boolean deleted attribute. The deleted flag allows the EQ software to ignore the entity and treat it as nonexistent except when its details are needed for historical reporting purposes. Whether the API treats an entity as nonexistent based on its deleted status depends on the endpoint. If it makes sense to retrieve or act on deleted entities for a certain endpoint, then the endpoint will do so without complaint. However, if it only makes sense that deleted entities are ignored or treated as nonexistent, then the endpoint will do so and will throw an error if a deleted entity if specified. For example, when retrieving agent details from the API, deleted agents are considered existent (but deleted) and will be returned (and their deleted attribute will signify that they are deleted). However, when signing an agent in and creating a new session for them, it would not make sense to allow a deleted agent to sign in, so the API would treat the agent as nonexistent and refuse the request. In general, entities cannot be edited while in a deleted state. PUT requests to update a deleted entity will fail with a 404 response code. The specifications for each endpoint will clarify how deleted entities are treated if necessary.
User Sessions
It is important to understand how user sessions work in the EQ software to understand some aspects of the API. Each user can only have one active session at a time. Signing in again or elsewhere will either fail or force out any other active sessions (depending on the parameters of the sign-in). If a user signs out or is forced to sign out, the session is destroyed. However, if a user simply times out, meaning their ping (keep alive) stopped for some reason, the session is deactivated, but remains it valid. As soon as the user pings the system again, the session is reactivated (if no conflicts), and the user is signed in again. A user is considered signed in if and only if they have a valid, active session. If a session is destroyed or deactivated, that user is no longer considered signed in. Once a deactivated session is reactivated, the user is considered signed in again.
Date/Times
All date/times accepted or returned by the API are UNIX timestamps, or seconds since January 1, 1970.
Errors
Standard HTTP response codes indicate success or failure of the request...
Code | Description |
---|---|
200 | Request was successful |
400 | Request not valid |
401 | Unauthorized |
404 | Not Found |
500 | Server error |
Endpoints
Each endpoint handles a certain type of entity/resource or a certain action on resources/entities of that type. Each endpoint supports some or all of the four standard HTTP methods (GET, POST, PUT, DELETE).
Supervisor Session
Create Supervisor Session (Sign In) This endpoint is used to create a new session for a supervisor user, i.e. sign the user in.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | user | Yes | User ID of supervisor for which to create session |
Request Body | extension | No | Extension to sign supervisor in at |
Request Body | force | No | 1 - force new session if supervisor already signed in 0 - do not force new session (will fail with error if supervisor already signed in) |
Return Data
If the request is successful, the returned data is the token of the new supervisor session (64-byte string).
Example:
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
token | nonexistent | The session doesn't exist or is no longer valid |
[null] | already_signed_in | The supervisor is already signed in with another session |
extension | in_use | Another user is signed in at the extension |
extension | nonexistent | Extension does not exist |
Delete Supervisor Session (Sign Out)
This endpoint is used to delete a certain supervisor session, i.e. signing the user out.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | token | Yes | Token of the supervisor session for which to sign user out |
Return Data
[None]
Create Agent Session (Sign In)
This endpoint is used to create a new session for an agent user, i.e. sign the user in.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | user | Yes | User ID of agent for which to create session |
Request Body | extension | Yes | Extension to sign agent in at |
Request Body | force | No | 1 - force new session if agent already signed in 0 - do not force new session (will fail with error if agent already signed in) |
Return Data
If the request is successful, the returned data is the token of the new agent session (64-byte string).
Example:
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
[null] | already_signed_in | The agent is already signed in with another session |
extension | blank | Extension not specified |
extension | nonexistent | Extension does not exist |
extension | in_use | Another user is signed in at the extension |
Supervisor
Get Supervisor
This endpoint is used to get a certain supervisor user.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | User ID of the supervisor |
Return Data
If the request is successful, the returned data is a supervisor user object.
Example:
Create Supervisor
This endpoint is used to create a new supervisor user.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | data | Yes | JSON object containing attributes of supervisor user to create |
data parameter (JSON object) | username | Yes | 3-20 alphanumeric characters |
data parameter (JSON object) | firstName | Yes | 1-32 characters |
data parameter (JSON object) | lastName | No | 1-32 characters, or blank/null |
data parameter (JSON object) | password | Yes | 4-20 characters |
data parameter (JSON object) | emailAddress | Yes | valid email address |
data parameter (JSON object) | language | No | valid language code: en (English) es (Spanish) he (Hebrew) or blank/null for default language |
data parameter (JSON object) | type | Yes | valid type code: full monitorOnly |
Return Data
If the request is successful, the returned data is the ID of the new supervisor user (integer).
Example:
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
username | in_use | A supervisor with the specified username already exists |
emailAddress | in_use | A supervisor with the specified email address already exists |
Update Supervisor
This endpoint is used to update an existing supervisor user.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | User ID of the supervisor |
Request Body | data | Yes | JSON object containing attributes of supervisor user to update |
data parameter (JSON object) | username | Yes | 3-20 alphanumeric characters |
data parameter (JSON object) | firstName | Yes | 1-32 characters |
data parameter (JSON object) | lastName | No | 1-32 characters, or blank/null |
data parameter (JSON object) | password | No | 4-20 characters |
data parameter (JSON object) | emailAddress | Yes | valid email address |
data parameter (JSON object) | language | No | valid language code: en (English) es (Spanish) he (Hebrew) or blank/null for default language |
data parameter (JSON object) | type | Yes | valid type code: full monitorOnly |
Return Data
[None]
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
username | in_use | A supervisor with the specified username already exists |
emailAddress | in_use | A supervisor with the specified email address already exists |
Delete Supervisor
This endpoint is used to delete a certain supervisor user. The user is not actually deleted, but is flagged as deleted and treated accordingly.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | User ID of the supervisor |
Return Data
[None]
Undelete Supervisor
This endpoint is used to undelete a certain supervisor user.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | User ID of the supervisor |
Query String | undelete | Yes | 1 |
Return Data
[None]
Agent
Get Agent
This endpoint is used to get a certain agent user.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | User ID of the agent |
Return Data
If the request is successful, the returned data is a agent user object.
Example:
Create Agent
This endpoint is used to create a new agent user.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | data | Yes | JSON object containing attributes of agent user to create |
data parameter (JSON object) | number | Yes | 1-5 digits, not starting with 0 |
data parameter (JSON object) | firstName | Yes | 1-32 characters |
data parameter (JSON object) | lastName | No | 1-32 characters, or blank/null |
data parameter (JSON object) | password | Yes | 3-10 digits |
data parameter (JSON object) | emailAddress | No | valid email address, or blank/null |
data parameter (JSON object) | language | No | valid language code: en - English es - Spanish he - Hebrew or blank/null for default language |
Return Data
If the request is successful, the returned data is the ID of the new agent user (integer).
Example:
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
number | in_use | An agent with the specified number already exists |
emailAddress | in_use | An agent with the specified email address already exists |
Update Agent
This endpoint is used to update an existing agent user.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | User ID of the supervisor |
Request Body | data | Yes | JSON object containing attributes of agent user to update |
data parameter (JSON object) | number | Yes | 1-5 digits, not starting with 0 |
data parameter (JSON object) | firstName | Yes | 1-32 characters |
data parameter (JSON object) | lastName | No | 1-32 characters, or blank/null |
data parameter (JSON object) | password | No | 3-10 digits |
data parameter (JSON object) | emailAddress | No | valid email address, or blank/null |
data parameter (JSON object) | language | No | valid language code: en - English es - Spanish he - Hebrew or blank/null for default language |
Return Data
[None]
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
number | in_use | An agent with the specified number already exists |
emailAddress | in_use | An agent with the specified email address already exists |
Delete Agent
This endpoint is used to delete a certain agent user. The user is not actually deleted, but is flagged as deleted and treated accordingly.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | User ID of the agent |
Return Data
[None]
Undelete Agent
This endpoint is used to undelete a certain agent user.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | User ID of the agent |
Query String | undelete | Yes | 1 |
Return Data
[None]
Call Queue
Get Call Queue
This endpoint is used to get a certain call queue.
Note: Many of the call queue attributes are normally configured in FreePBX and are not managed or used by the EQ software directly. See the FreePBX queue configuration page for more information on any attributes that aren't self-explanatory.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | extension | Yes | Extension of the call queue |
Return Data
If the request is successful, the returned data is a call queue object.
Example:
Create Call Queue
This endpoint is used to create a new call queue.
Note: Many of the call queue attributes are normally configured in FreePBX and are not managed or used by the EQ software directly. See the FreePBX queue configuration page for more information on any attributes that aren't self-explanatory.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | data | Yes | JSON object containing attributes of call queue to create |
data parameter (JSON object) | extension | Yes | digits only, not starting with 0 |
data parameter (JSON object) | name | Yes | 1-35 characters |
data parameter (JSON object) | type | Yes | valid type code: 0 (inbound) 1 (outbound) |
data parameter (JSON object) | autoAnswerAcd | No | boolean |
data parameter (JSON object) | sysResume | No | integer > 0 (seconds), or null to disable |
data parameter (JSON object) | wrapUpTime | No | integer > 0 (seconds), 0 for unlimited, or null to disable |
data parameter (JSON object) | wrapUpAllQueues | No | boolean |
data parameter (JSON object) | cidNamePrefix | No | string, or blank/null |
data parameter (JSON object) | agentRestrictions | No | valid choice: 0 (Call as Dialed) 1 (No Follow-Me or Call Forward) 2 (Extensions Only) |
data parameter (JSON object) | ringStrategy | No | valid choice: ringall leastrecent fewestcalls random rrmemory rrordered linear wrandom |
data parameter (JSON object) | weight | No | integer 0-10 |
data parameter (JSON object) | mohClass | No | valid choice: inherit default none |
data parameter (JSON object) | ringingMoh | No | boolean |
data parameter (JSON object) | recordingFormat | No | "wav", or blank/null to disableNote: FreePBX lists two other formats that are not supported by EQ and should not be used. |
data parameter (JSON object) | recordingMode | No | valid choice: includeholdtime afteranswered |
data parameter (JSON object) | maxWaitTime | No | integer > 0, or null for unlimited |
data parameter (JSON object) | agentTimeout | No | integer > 0, or null for unlimited |
data parameter (JSON object) | agentRetryTime | No | integer >= 0, or null for no retry |
data parameter (JSON object) | maxCallers | No | integer > 0, or null for unlimited |
data parameter (JSON object) | joinEmpty | No | valid choice: yes no strict ultrastrict loose |
data parameter (JSON object) | leaveEmpty | No | valid choice: yes no strict ultrastrict loose |
data parameter (JSON object) | announceFrequency | No | integer >= 0 |
data parameter (JSON object) | announcePosition | No | valid choice: yes no |
data parameter (JSON object) | announceHoldTime | No | valid choice: yes no once |
Return Data
If the request is successful, the returned data is the extension of the new call queue.
Example:
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
extension | in_use | A call queue with the specified extension already exists |
name | in_use | A call queue with the specified name already exists |
Update Call Queue
This endpoint is used to update an existing call queue.
Note: Many of the call queue attributes are normally configured in FreePBX and are not managed or used by the EQ software directly. See the FreePBX queue configuration page for more information on any attributes that aren't self-explanatory.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | extension | Yes | Extension of the call queue |
Request Body | data | Yes | JSON object containing attributes of call queue to create |
data parameter (JSON object) | name | Yes | 1-35 characters |
data parameter (JSON object) | type | Yes | valid type code: 0 (inbound) 1 (outbound) |
data parameter (JSON object) | autoAnswerAcd | No | boolean |
data parameter (JSON object) | sysResume | No | integer > 0 (seconds), or null to disable |
data parameter (JSON object) | wrapUpTime | No | integer > 0 (seconds), 0 for unlimited, or null to disable |
data parameter (JSON object) | wrapUpAllQueues | No | boolean |
data parameter (JSON object) | cidNamePrefix | No | string, or blank/null |
data parameter (JSON object) | agentRestrictions | No | valid choice: 0 (Call as Dialed) 1 (No Follow-Me or Call Forward) 2 (Extensions Only) |
data parameter (JSON object) | ringStrategy | No | valid choice: ringall leastrecent fewestcalls random rrmemory rrordered linear wrandom |
data parameter (JSON object) | weight | No | integer 0-10 |
data parameter (JSON object) | mohClass | No | valid choice: inherit default none |
data parameter (JSON object) | ringingMoh | No | boolean |
data parameter (JSON object) | recordingFormat | No | "wav", or blank/null to disableNote: FreePBX lists two other formats that are not supported by EQ and should not be used. |
data parameter (JSON object) | recordingMode | No | valid choice: includeholdtime afteranswered |
data parameter (JSON object) | maxWaitTime | No | integer > 0, or null for unlimited |
data parameter (JSON object) | agentTimeout | No | integer > 0, or null for unlimited |
data parameter (JSON object) | agentRetryTime | No | integer >= 0, or null for no retry |
data parameter (JSON object) | maxCallers | No | integer > 0, or null for unlimited |
data parameter (JSON object) | joinEmpty | No | valid choice: yes no strict ultrastrict loose |
data parameter (JSON object) | leaveEmpty | No | valid choice: yes no strict ultrastrict loose |
data parameter (JSON object) | announceFrequency | No | integer >= 0 |
data parameter (JSON object) | announcePosition | No | valid choice: yes no |
data parameter (JSON object) | announceHoldTime | No | valid choice: yes no once |
Return Data
[None]
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
extension | in_use | A call queue with the specified extension already exists |
name | in_use | A call queue with the specified name already exists |
Delete Call Queue
This endpoint is used to delete a certain call queue. The queue is removed completely form Asterisk, but the call queue is not actually deleted in the EQ system, but is flagged as deleted and treated accordingly.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | extension | Yes | Extension of the call queue |
Return Data
[None]
Undelete Call Queue
This endpoint is used to undelete a certain call queue.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | Extension of the call queue |
Query String | undelete | Yes | 1 |
Return Data
[None]
Undelete Call Queue
This endpoint is used to undelete a certain call queue.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | Extension of the call queue |
Query String | undelete | Yes | 1 |
Return Data
[None]
Pause Code
Get Pause Code
This endpoint is used to get a certain pause code.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | ID of the pause code |
Return Data
If the request is successful, the returned data is a pause code object.
Example:
Create Pause Code
This endpoint is used to create a new pause code.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | data | Yes | JSON object containing attributes of pause code to create |
data parameter (JSON object) | name | Yes | 1-16 characters |
Return Data
If the request is successful, the returned data is the ID of the new pause code (integer).
Example:
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
name | in_use | A pause code with the specified name already exists |
Update Pause Code
This endpoint is used to update an existing pause code.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | ID of the pause code |
Request Body | data | Yes | JSON object containing attributes of pause code to update |
data parameter (JSON object) | name | Yes | 1-16 characters |
Return Data
[None]
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
name | in_use | Another pause code with the specified name already exists |
Delete Pause Code
This endpoint is used to delete a certain pause code. The pause code is not actually deleted, but is flagged as deleted and treated accordingly.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | ID of the pause code |
Return Data
[None]
Undelete Pause Code
This endpoint is used to undelete a certain pause code.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | ID of the pause code |
Query String | undelete | Yes | 1 |
Return Data
[None]
Extension
Get Extension
This endpoint is used to get a certain user extension.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | extension | Yes | Extension |
Return Data
If the request is successful, the returned data is a extension object.
Example:
Create Extension
This endpoint is used to create a new user extension.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | data | Yes | JSON object containing attributes of extension to create |
data parameter (JSON object) | extension | Yes | digits only, not starting with 0 |
data parameter (JSON object) | name | Yes | 1-50 characters |
data parameter (JSON object) | cidMasquerade | No | digits, or blank/null |
data parameter (JSON object) | outboundCid | No | digits, or blank/null |
data parameter (JSON object) | emergencyCid | No | digits, or blank/null |
data parameter (JSON object) | callWaiting | No | boolean |
data parameter (JSON object) | recording.inboundExternal | No | valid choice: dontcare always never |
data parameter (JSON object) | recording.inboundInternal | No | valid choice: dontcare always never |
data parameter (JSON object) | recording.outboundExternal | No | valid choice: dontcare always never |
data parameter (JSON object) | recording.outboundInternal | No | valid choice: dontcare always never |
data parameter (JSON object) | recording.onDemand | No | boolean |
data parameter (JSON object) | sip.secret | No | string, or blank/null |
data parameter (JSON object) | sip.dtmfMode | No | valid choice: rfc2833 (RFC 2833) inband (In band audio) auto (Auto) info (SIP INFO (application/dtmf-relay) shortinfo (SIF INFO (application/dtmf) |
data parameter (JSON object) | sip.context | No | string, or blank/null for default ("from-internal") |
data parameter (JSON object) | sip.nat | No | valid choice: yes (Yes) no (No - RFC3581) never (never - no RFC3581) route (route - NAT no rport) |
data parameter (JSON object) | voicemail | No | JSON object containing voicemail config, or null to disable |
data parameter (JSON object) | voicemail.context | No | string, or blank/null for default ("default") |
data parameter (JSON object) | voicemail.password | No | digits, or blank/null |
data parameter (JSON object) | voicemail.emailAddress | No | valid email address, or blank/null |
data parameter (JSON object) | voicemail.pagerEmailAddress | No | valid email address, or blank/null |
data parameter (JSON object) | voicemail.options | No | JSON object containing voicemail options with option names as keys and option values as values, or null for defaults |
data parameter (JSON object) | voicemail.options.attach | No | valid choice: yes no |
data parameter (JSON object) | voicemail.options.saycid | No | valid choice: yes no |
data parameter (JSON object) | voicemail.options.envelope | No | valid choice: yes no |
data parameter (JSON object) | voicemail.options.delete | No | valid choice: yes no |
Return Data
If the request is successful, the returned data is the new extension.
Example:
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
extension | in_use | A extension with the specified extension already exists |
name | in_use | A extension with the specified name already exists |
Update Extension
This endpoint is used to update an existing user extension.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | extension | Yes | Extension |
Request Body | data | Yes | JSON object containing attributes of extension to create |
data parameter (JSON object) | extension | Yes | digits only, not starting with 0 |
data parameter (JSON object) | name | Yes | 1-50 characters |
data parameter (JSON object) | cidMasquerade | No | digits, or blank/null |
data parameter (JSON object) | outboundCid | No | digits, or blank/null |
data parameter (JSON object) | emergencyCid | No | digits, or blank/null |
data parameter (JSON object) | callWaiting | No | boolean |
data parameter (JSON object) | recording.inboundExternal | No | valid choice: dontcare always never |
data parameter (JSON object) | recording.inboundInternal | No | valid choice: dontcare always never |
data parameter (JSON object) | recording.outboundExternal | No | valid choice: dontcare always never |
data parameter (JSON object) | recording.outboundInternal | No | valid choice: dontcare always never |
data parameter (JSON object) | recording.onDemand | No | boolean |
data parameter (JSON object) | sip.secret | No | string, or blank/null |
data parameter (JSON object) | sip.dtmfMode | No | valid choice: rfc2833 (RFC 2833) inband (In band audio) auto (Auto) info (SIP INFO (application/dtmf-relay) shortinfo (SIF INFO (application/dtmf) |
data parameter (JSON object) | sip.context | No | string, or blank/null for default ("from-internal") |
data parameter (JSON object) | sip.nat | No | valid choice: yes (Yes) no (No - RFC3581) never (never - no RFC3581) route (route - NAT no rport) |
data parameter (JSON object) | voicemail | No | JSON object containing voicemail config, or null to disable |
data parameter (JSON object) | voicemail.context | No | string, or blank/null for default |
data parameter (JSON object) | voicemail.password | No | digits, or blank/null |
data parameter (JSON object) | voicemail.emailAddress | No | valid email address, or blank/null |
data parameter (JSON object) | voicemail.pagerEmailAddress | No | valid email address, or blank/null |
data parameter (JSON object) | voicemail.options | No | JSON object containing voicemail options with option names as keys and option values as values, or null for defaults |
data parameter (JSON object) | voicemail.options.attach | No | valid choice: yes no |
data parameter (JSON object) | voicemail.options.saycid | No | valid choice: yes no |
data parameter (JSON object) | voicemail.options.envelope | No | valid choice: yes no |
data parameter (JSON object) | voicemail.options.delete | No | valid choice: yes no |
Return Data
[None]
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
extension | in_use | A extension with the specified extension already exists |
name | in_use | A extension with the specified name already exists |
Delete Extension
This endpoint is used to delete a certain user extension.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | extension | Yes | Extension |
Return Data
[None]
Phone
Get Phone
This endpoint is used to get the details of the phone for a certain extension.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Query String | extension | Yes | Extension |
Return Data
If the request is successful, the returned data is a phone object.
Example:
Alert
Create Alert
This endpoint is used to create a new alert.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | data | Yes | JSON object containing attributes of alert to create |
data parameter (JSON object) | user | No | User ID of supervisor the alert is for, or null for system-wide alert (custom notification type only) |
data parameter (JSON object) | name | Yes | 1-48 characters |
data parameter (JSON object) | type | Yes | valid alert type code: callQueueCallsHigh callQueueWaitTimeHigh callQueueAgentsLow callQueueAgentsAvailableLow emailQueueEmailsHigh emailQueueAgentsLow emailQueueAgentsAvailableLow licenseExceeded processStopped diskUsageHigh |
data parameter (JSON object) | callQueue | Yes, if applicable | Extension of call queue |
data parameter (JSON object) | emailQueue | Yes, if applicable | ID of email queue |
data parameter (JSON object) | threshold | Yes, if applicable | integer |
data parameter (JSON object) | notificationType | Yes | valid notification type string: realtime email sms custom |
data parameter (JSON object) | color | Yes, if applicable | color to display alert as for realtime notification type only RGB color string in format #XXXXXX |
data parameter (JSON object) | interval | Yes, if applicable | minimum interval in minutes between alert notifications for email, SMS, and custom notification types only |
data parameter (JSON object) | daysOfWeek | Yes | days of week for which alert is active array of integers, each 0-6: 0 = sunday 1 = monday 2 = tuesday 3 = wednesday 4 = thursday 5 = friday 6 = saturday Example for Monday, Wednesday, and Friday: [1, 3, 5] |
data parameter (JSON object) | fromTime | Yes | beginning of interval of time in day for which alert is active string in format HH:MM AM or HH:MM PM |
data parameter (JSON object) | toTime | Yes | end of interval of time in day for which alert is active string in format HH:MM AM or HH:MM PM use 12:00 AM for very end of day |
Return Data
If the request is successful, the returned data is the ID of the new alert (integer).
Example:
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
name | in_use | An alert with the specified name already exists for the user |
Update Alert
This endpoint is used to update an existing alert.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | ID of the alert |
Request Body | data | Yes | JSON object containing attributes of alert to update |
data parameter (JSON object) | name | Yes | 1-48 characters |
data parameter (JSON object) | type | Yes | valid alert type code: callQueueCallsHigh callQueueWaitTimeHigh callQueueAgentsLow callQueueAgentsAvailableLow emailQueueEmailsHigh emailQueueAgentsLow emailQueueAgentsAvailableLow licenseExceeded processStopped diskUsageHigh |
data parameter (JSON object) | callQueue | Yes, if applicable | Extension of call queue |
data parameter (JSON object) | emailQueue | Yes, if applicable | ID of email queue |
data parameter (JSON object) | threshold | Yes, if applicable | integer |
data parameter (JSON object) | notificationType | Yes | valid notification type: realtime email sms custom |
data parameter (JSON object) | color | Yes, if applicable | color to display alert as for realtime notification type only RGB color string in format #XXXXXX |
data parameter (JSON object) | interval | Yes, if applicable | minimum interval in minutes between alert notifications for email, SMS, and custom notification types only |
data parameter (JSON object) | daysOfWeek | Yes | days of week for which alert is active array of integers, each 0-6: 0 = sunday 1 = monday 2 = tuesday 3 = wednesday 4 = thursday 5 = friday 6 = saturday Example for Monday, Wednesday, and Friday: [1, 3, 5] |
data parameter (JSON object) | fromTime | Yes | beginning of interval of time in day for which alert is active string in format HH:MM AM or HH:MM PM |
data parameter (JSON object) | toTime | Yes | end of interval of time in day for which alert is active string in format HH:MM AM or HH:MM PM use 12:00 AM for very end of day |
Return Data
[None]
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
name | in_use | An alert with the specified name already exists for the user |
Delete Alert
This endpoint is used to delete a certain alert permanently.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
URL | id | Yes | ID of the alert |
Return Data
[None]
Active Supervisor Sessions
Get Active Supervisor Sessions
This endpoint is used to get the details of active supervisor sessions.
Parameters/Attributes
Location | Name | Required | Description |
---|
Return Data
The returned data is an array of supervisor session objects.
Example:
Active Agent Sessions
Get Active Agent Sessions
This endpoint is used to get the details of active agent sessions.
Parameters/Attributes
Location | Name | Required | Description |
---|
Return Data
The returned data is an array of agent session objects.
Example:
Queued Calls
Get Queued Calls
This endpoint is used to get the details of calls in queue for a certain queue or all queues.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Query String | queue | No | Extension of the call queue, or blank for all queues |
Return Data
The returned data is an array of queued call objects.
Example (all queues):
Steal Queued Call
Steal Queued Call
This endpoint is used to steal a call from queue and transfer it to an extension.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | channel | Yes | Channel of the queued call to steal |
Request Body | destination | Yes | Extension or destination to which to send the call |
Return Data
[None]
Parked Calls
Get Parked Calls
This endpoint is used to get the details of calls in the parking lot.
Parameters/Attributes
Location | Name | Required | Description |
---|
Return Data
The returned data is an array of parked call objects.
Example:
Pick Up Parked Call
Pick Up Parked Call
This endpoint is used to pick up a parked call and transfer it to an extension.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | channel | Yes | Channel of the parked call to pick up |
Request Body | destination | Yes | Extension or destination to which to send the call |
Return Data
[None]
Active Calls
Get Active Calls
This endpoint is used to get the details of active calls for a certain extension.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Query String | extension | Yes | Extension for which to retrieve calls |
Return Data
The returned data is an array of parked call objects.
Example:
Call Recordings
Get Call Recordings
This endpoint is used to get the file paths of call recordings for a certain call.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Query String | call | Yes (unless call unique ID specified) | ID of the call for which to retrieve recordings |
Query String | call_unique_id | No (unless call ID not specified) | Unique IDof the call for which to retrieve recordings |
Return Data
The returned data is an array of absolute file paths.
Example:
Get Call Queue Agent Status
Get Call Queue Agent Status
This endpoint is used to get the call queue agent statuses for a certain queue, a certain agent, or all queues and agents.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Query String | queue | No | Extension of a call queue, or blank for all queues or if specifying agent |
Query String | agent | No | User ID of an agent, or blank for all agents or if specifying queue |
Query String | combined | No | 0 or 1 (false or true) Value of 1 causes combined status across all queues for each agent to be returned Takes affect only if no queue or agent is specified |
Return Data
The returned data is an array of call queue agent status objects.
Example (all queues and agents):
Execute Call Queue Agent Action (Sign In, Sign Out, Pause, Resume, Exit Wrap Up)
Execute Call Queue Agent Action (Sign In, Sign Out, Pause, Resume, Exit Wrap Up)
This endpoint is used to execute an action for an agent in a certain call queue or in all relevant call queues.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | action | Yes | Valid action type: signIn signOut pause resume exitWrapUp |
Request Body | options | Yes | JSON object containing options for action |
options parameter (JSON object) | agent | Yes | User ID of agent for which to execute action |
options parameter (JSON object) | queue | No | Extension of queue for which to execute action for agent If not specified or null (and queues parameter not specified either--signIn only), the action will be executed on all relevant queues, meaning (according to action type): signIn: sign in all bound queues signOut: sign out all queues currently signed in pause: pause all queues currently signed in resume: resume all queues currently signed in exitWrapUp: exit wrap up for all queues currently signed in |
options parameter (JSON object) | queues | No | Array of extensions of queues for which to sign agent into Example: ["500", "501", "504"] |
options parameter (JSON object) | skill | No | Skill level (penalty) with which to sign agent into queue (lower number means less penalty == higher priority) 5 - Lowest 4 - Below Normal 3 - Normal 2 - Above Normal 1 - Highest or null for default (3 - Normal) Has no effect for actions other than signIn |
options parameter (JSON object) | skills | No | Array of skill levels (penalty) with which to sign agent into queues (lower number means less penalty == higher priority) when signing in multiple specific queues Size of array must be equal to size of queues array Each array element must be a valid skill integer: 5 - Lowest 4 - Below Normal 3 - Normal 2 - Above Normal 1 - Highest Example: [3, 3, 5] Has no effect for actions other than signInAlso has no effect if queues parameter is not used |
options parameter (JSON object) | paused | No | Whether to sign queues in as paused Has no effect for actions other than signIn |
options parameter (JSON object) | pauseCode | No | ID of pause code to use for pause action or null for no pause code Has no effect for actions other than pause |
Return Data
[None]
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
action | invalid | Action type not valid |
agent | blank | Agent ID not specified |
agent | nonexistent | Agent does not exist (or is deleted) |
agent | not_signed_in | Agent not signed in (to system, not to queue) / has no active session |
queue | already_signed_in | Agent already signed into queue (applies only to signIn action with certain queue specified) |
queue | not_signed_in | Agent not signed into queue (applies only to signOut, pause, resume, and exitWrapUp actions with certain queue specified) |
pauseCode | nonexistent | Pause code does not exist (applies only to pause action with pause code specified) |
Get Call Queue Statistics
Get Call Queue Statistics
This endpoint is used to get a summary of calls and agents for a certain queue or all queues.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Query String | queue | No | Extension of the call queue, or blank for all queues |
Return Data
The returned data is a call queue statistics object, or an array of call queue statistics objects if returning data for all queues.
Example (single queue):
Execute Extension Action (Dial, Blind Transfer, Park, Hang Up)
Execute Extension Action (Dial, Blind Transfer, Park, Hang Up)
This endpoint is used to dial, blind transfer, park, or hang up for an extension.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | extension | Yes | Extension |
Request Body | action | Yes | Valid action type: dial blindTransfer park hangUp |
Request Body | channel | No | Extension's channel on which to act If not specified or blank, first channel found for extension will be used For blindTransfer, park, and hangUp types only |
Request Body | destination | Yes, if applicable | Phone number or extension For dial and blindTransfer types only |
Return Data
[None]
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
extension | nonexistent | Extension does not exist |
Execute Call Recording Action (Start, Stop, Cancel)
Execute Call Recording Action (Start, Stop, Cancel)
This endpoint is used to manually record, stop recording, or cancel recording for an extension.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | extension | Yes | Extension |
Request Body | action | Yes | Valid action type: start stop cancel |
Return Data
[None]
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
extension | nonexistent | Extension does not exist |
Execute Call Monitor Action (Spy, Barge In, Whisper)
Execute Call Monitor Action (Spy, Barge In, Whisper)
This endpoint is used to spy, barge in, or whisper to an extension.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | action | Yes | Valid action type: spy bargeIn whisper |
Request Body | targetExtension | Yes | Extension to monitor |
Request Body | monitorExtension | Yes | Extension from which to monitor |
Return Data
[None]
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
targetExtension | nonexistent | Target extension does not exist |
monitorExtension | nonexistent | Monitor extension does not exist |
Execute Phone Command (Press a Key)
Execute Phone Command (Press a Key)
This endpoint is used to press a button on a certain phone.
Parameters/Attributes
Location | Name | Required | Description |
---|---|---|---|
Request Body | phone | Yes (unless extension specified) | JSON object containing attributes for phone Must be a valid phone object, as returned by the phone endpoint |
Request Body | extension | No | Extension of phone Can be specified in place of a phone object |
Request Body | key | Yes | Valid key: line1, line2, ... soft_key1, soft_key2, ... up down left right enter cancel volume_up volume_down headset speaker mute menu messages applications directory dnd conference transfer redial hold 1, 2, 3, 4, 5, 6, 7, 8, 9, 0 star pound |
Return Data
[None]
Special Errors
Parameter/Attribute | Type | Description |
---|---|---|
extension | nonexistent | Extension does not exist |
phone | nonexistent | Phone does not exist (extension not registered or phone type undetectable) |
key | invalid | Key is not valid for phone |
Get Active Conferences
Get Active Conferences
This endpoint is used to get the statuses of any active conferences.
Parameters/Attributes
Location | Name | Required | Description |
---|
Return Data
The returned data is an array of parked call objects.
Example:
License
License
This endpoint is used to get the license details.
Parameters/Attributes
[None]
Return Data
The returned data is a license object.
Example:
License Usage
License Usage
This endpoint is used to get the current license usage.
Parameters/Attributes
[None]
Return Data
The returned data is a license usage object.
Example:
Configuration Check
Configuration Check
This endpoint is used to check for problems in the configuration of the system.
Parameters/Attributes
[None]
Return Data
The returned data is a configuration check object.
Example: