Third Party applications are able to send, receive, and monitor fax transmissions to the UCX Virtual Fax capability via the UCX Fax API for 3rd Party Clients. Access to the API is enabled via license, which must be applied via the System / Licenses page. It relies on one or more Virtual Fax extensions to have been created on the UCX using the steps provided in the Virtual Fax documentation page.
When using the UCX Fax API for 3rd Party Clients, it is highly recommended that individual Virtual Fax extension be created for each DID that will be dedicated to fax. This will require one universal extension license for each Virtual Fax, as Virtual Fax extensions are configured as IAX2 extensions.
The UCX Fax API for 3rd Party Clients allows 3rd party client applications to implement their own user interface for capabilities provided by the Virtual Fax feature available on UCX systems.
This document describes the REST API used to interact with the UCX Virtual Fax system.
Request Authentication
The Fax API uses HTTP bearer authentication for all requests. The bearer token is retrieved from the UCX using the Token method and client credentials (Client ID and Secret). The Token method uses HTTP Basic Authentication. The Client ID is used as the username and the Secret is used as the password.
The client credentials are provided on the System – Licenses page in the UCX management GUI (provided the system has a license for the external Fax API).
The bearer token is valid for the entire validity period of the external Fax API license. Hence, the 3rd party application needs to acquire a new token only when the external Fax API license is initially added (or after the license is removed or expires and is subsequently renewed).
Authentication Flow
- Retrieve a bearer token using the Token method and the Client ID / Secret.
- Include the returned bearer token in the Authorization header for all subsequent requests.
Authorization Header Example:
Authorization: Bearer <token>
Request Format
The Fax API uses GET requests for simple methods such as a request to get a list of virtual faxes or to get information about send requests. For GET requests:
- Parameters are passed as URL-encoded query strings.
The Fax API uses PUT requests for methods that can be used to modify the status of send requests. For PUT requests:
- Parameters are passed as JSON encoded data using the UTF-8 encoding. The header “Content-Type: application/json” should be included in the request.
The Fax API uses POST requests for methods that include file attachments. For POST requests:
- Parameters and the attachment(s) are passed in the form of multipart MIME data.
Request Examples
The request examples in this document use a simplified, implementation-independent format rather than command-line curl syntax. Each example identifies the HTTP method, API resource, and parameters required for the request.
For example:
(source_id=2, destination=14695550101, attachment=test.pdf)
This represents an HTTP POST request to /restv1/efax/filesend with the specified parameters. Parameters and attachments must be encoded according to the request format defined for the method. For example, FileSend parameters and file attachments are submitted as multipart/form-data.
Response Format
All Fax API methods provide responses in the form of JSON-encoded data using the UTF-8 encoding. The 3rd party application should include an “Accept: application/json” header in their requests to indicate the client can handle JSON responses.
Error Reporting
Standard HTTP status codes are used to report errors due to which requests cannot be processed by appropriate REST API handlers. Examples of such errors would be:
- 400 Bad Request: Invalid parameters or missing fields.
- 401 Unauthorized: Authentication failed (invalid/missing token).
- 404 Not Found: Invalid API endpoint or method.
- 500 Internal Server Error: Server-side processing failure.
If the request reaches the appropriate API handler, errors are reported through JSON-encoded data with two items – result and message. The following data is an example of an error response:
Example error response:
{"result":"Error","message":"Authentication failed"}Overview
| Method | Description |
|---|---|
| Token | Retrieve the bearer token required for all other API methods |
| FaxList | Get a list of virtual faxes (virtual fax machines configured on the system) |
| FaxUsage | Get information about the current usage of virtual faxes |
| FileSend | Send a fax file (attachment) using a specific virtual fax (from the fax list) to a single destination phone number. A job ID is generated for an accepted request. |
| JobStatus | Request the current status of a send or receive fax job using its job ID |
| JobCancel | Cancel an outstanding send request using its job ID |
| ActiveJobs | Get a list of active fax jobs (i.e., send requests or receive requests in progress) |
| RecordCount | Get the number of fax records stored in the database (either sent or received) |
| RecordsGet | Get fax job records from the database (either sent or received) |
| RecordDelete | Request to delete a fax record and the associated fax file using its job ID |
| FileDownload | Download a fax file associated with a job ID |
Method: Token
Use this method to retrieve the bearer token required for all other API methods.
Resource: /restv1/efax/token
Type: GET
Parameters:
none
Authentication:
See Request Authentication above. The Client ID and Secret are supplied using HTTP Basic Authentication (Client ID = username, Secret = password) and are not passed as request parameters.
Response:
When the request is accepted, the response is a JSON object with the bearer token. The response includes the following items:
- result Value “Success” indicates the request was successfully processed.
- token Bearer token that must be used for all other API methods.
Example request:
Example response:
{"result":"Success","token":"1f0ef7d3a547ce0dd5ed5f07ad65bd65"}Method: FaxList
Use this method to retrieve a list of virtual faxes that can be used to send/receive faxes.
Resource: /restv1/efax/faxlist
Type: GET
Parameters:
none
Response:
When the request is accepted, the response is a JSON object with data about all available faxes (virtual faxes configured on the UCX system). The response includes the following items:
- result Value “Success” indicates the request was successfully processed.
- count Number of virtual faxes returned.
- faxes Array of information about available virtual faxes.
For each virtual fax, the following items are provided:
id, extension, name, cidnumber, cidname.
Example request:
Example response:
{“id”:”1″,”extension”:”599″,”name”:”Sales”,”cidnumber”:”14695551111″,”cidname”:”EMT Sales”},
{“id”:”2″,”extension”:”598″,”name”:”Support”,”cidnumber”:”14695551112″,”cidname”:”EMT Support”}
]}
Method: FaxUsage
Use this method to retrieve information about the current usage of virtual fax(es). Resource:/restv1/efax/faxusage
Type: GET
Parameters:
- source_id (Optional) The fax ID of the virtual fax for which to return usage information. When no ID is specified, usage information for all virtual faxes is returned.
- result Value “Success” indicates the request was successfully processed.
- count Number of virtual faxes configured on the UCX system.
- faxes Array of information about the usage of virtual faxes.
Method: FileSend
Use this method to generate a request to send a fax file.
Resource: /restv1/efax/filesend
Type: POST
Parameters:
- source_id (Required)
ID of a virtual fax to be used for the send request (this ID is returned by the FaxList method) - destination (Required)
The destination phone number (the dialing string to use to contact the remote fax machine) - attachment (Required)
The file to be sent. Supported formats include POSTSCRIPT, TIFF, PDF, ASCII text, Troff output and Silicon Graphics format images.
Note: The attachment is uploaded as a standard HTTP multipart/form-data file upload.
Response:
When a request is accepted, the response is a JSON object with data about the request. The response includes the following items:
- result Value “Success” indicates the request was successfully processed.
- device Name of the TTY device that will be used for the fax transmission.
- destination Destination phone number.
- job_id Job ID assigned to the fax transmission task. This job ID can be used to query the current status of the request using the JobStatus method.
Example request:
Example response:
Method: JobStatus
Use this method to retrieve the current status of a virtual fax job. This method can be used to query the status of jobs related to both transmission and reception of faxes.
Resource: /restv1/efax/jobstatus
Type: GET
Parameters:
- job_id (Required)
ID of the virtual fax job.
Response:
When the request is accepted, the response is a JSON object with data about the job with the specified ID. The response includes the following items:
- result
Value “Success” indicates the request was processed successfully. - status
Object containing status information about the specified fax job.
The following items may be provided in the status object:
- time
Date and time (UTC) of the last update of the request. - destination
Destination phone number. - state
State of the request. - sent_pages
Number of pages that have already been sent or received. - total_pages
Total number of pages associated with the fax job. - attempts
Number of attempts made to send the fax. - max_retries
Maximum number of retries that will be used to send the fax. Provided only for send jobs that are in progress. - time_to_send
Time (UTC) when the next attempt is scheduled. Provided only for waiting or sleeping jobs. - duration
Duration of the call in seconds. Provided for completed jobs and for active receive jobs after at least one page has been received. - tsi
Transmitting Subscriber Identification of the far-end party. Provided only for active receive jobs. - cid_number
Caller ID number of the far-end party. Provided only for active receive jobs. - cid_name
Caller ID name of the far-end party. Provided only for active receive jobs. - status_text
Additional information about the current status when applicable.
Note: Several response items are provided only while the job is active. For active receive jobs, duration is provided only after at least one page has been received. For completed jobs, duration reflects the completed call duration.
Example request #1 – Send job:
Example response #1 – Send job waiting for retry:
Example request #2 – Receive job:
Example response #2 – Active receive job before a page is received:
Example response #3 – Active receive job after a page is received:
Example response #4 – Completed receive job:
Method: JobCancel
Use this method to cancel an outstanding request to send a fax. Jobs associated with the reception of faxes cannot be cancelled.
Resource: /restv1/efax/jobcancel
Type: PUT
Parameters:
- job_id (Required)
ID of a request (job) to send a fax that is currently active and is to be cancelled.
Response:
When a request is accepted, the response is a JSON object with data about the request with the specified ID. The response includes the following items:
- result
Value “Success” indicates the request was processed successfully. - status
Array of text line(s) describing the result of the cancel request. When the cancel request is successful, the status contains a single text line with the text “Job XX removed.”, where XX is the request ID.
Example request:
Example response:
Method: ActiveJobs
Use this method to get information about active send or receive fax jobs.
Resource: /restv1/efax/activejobs
Type: GET
Parameters:
- type (Required)
The type of jobs to get (either TX or RX).
Response:
When the request is accepted, the response is a JSON object with an array of information about active fax send or receive jobs. The response includes the following items:
- result
Value “Success” indicates the request was processed successfully. - count
Number of active fax jobs returned in thelistarray. - list
Array of active fax send or receive jobs.
Note: Only jobs started using the FileSend API method (requestor = API) are listed in the response to a TX query. Send fax jobs from other applications are not included.
The following fields are returned for each job:
jobid, time, time_to_send, destination, state, sent_pages, total_pages, ndials, totdials, maxdials, attempts, max_attempts, status_text, requestor, modem.
Example request:
Example response – No active jobs:
Example response – Active send job:
Method: RecordCount
Use this method to get the number of completed fax jobs stored in the database.
Resource: /restv1/efax/recordcount
Type: GET
Parameters:
- type (Required)
The type of jobs to query (either TX or RX).
Response:
When the request is accepted, the response is a JSON object with the count of completed fax jobs stored in the database. The response includes the following items:
- result
Value “Success” indicates the request was processed successfully. - count
Number of completed fax jobs.
Note: Only jobs started using the FileSend API method (requestor = API) are counted in the response to a TX query. Send fax jobs from other applications are not included.
Example request:
Example response:
Method: RecordsGet
Use this method to get data for completed fax jobs.
Resource: /restv1/efax/recordsget
Type: GET
Parameters:
- type (Required)
The type of jobs to query (either TX or RX) - limit (Optional)
The maximum number of records to be returned - offset (Optional)
The number of records to be skipped. The offset parameter is valid only when limit is specified.
Response:
When a request is accepted, the response is a JSON object with the count of completed fax requests returned in the records array followed by the array of records. The response includes the following items:
- result Value “Success” indicates the request was processed successfully.
- count Number of fax records returned in the array.
- records Array with data of completed fax jobs.
Note: Only jobs started via the FileSend API method (the requestor = API) are included in the response to the TX query. Send fax jobs from other applications are not included.
The following fields are returned in each record:
jobid, time (UTC timestamp), phone_number, cid_name, station_id, state, sent_pages, total_pages, attempts, duration, status_text, requestor and modem.
Example request:
Example response:
Method: RecordDelete
Use this method to delete the record for the specified job ID and the associated fax file (if any).
Resource: /restv1/efax/recorddelete
Type: PUT
Parameters:
- job_id (Required)
ID of the job for which the record and the fax file (if any) are to be deleted.
Response:
When a request is processed, the response is a JSON object with information about the result of the request. The response includes the following items:
- result
Value “Success” indicates the request was processed successfully. Value “Error” indicates the request failed. - status
Array containing a text line describing the result of a successful delete request. - message
Information describing the error when the request cannot be completed.
Example request – Delete sent fax record:
Example response – Successful sent fax deletion:
Example request – Delete received fax record:
Example response – Successful received fax deletion:
Example response – Record not found:
Method: FileDownload
Use this method to download the file associated with the specified job ID.
Resource: /restv1/efax/filedownload
Type: GET
Parameters:
- job_id (Required)
ID of a request (job) associated with the fax file that is to be downloaded.
Response:
When the request is successful, HTTP status code 200 OK is returned and the associated fax file is downloaded.
When the request cannot be completed, an HTTP error status is returned with a JSON object containing information about the error. The response includes the following items:
- result
Value “Error” indicates the request failed. - message
Information describing the error.
Example request:
Example response – Successful download:
Example response – Job not found:
