Fax API Introduction

Welcome the Voxtelesys Fax REST API. This API offers an easy, secure solution to send and receive faxes. If you have questions or would like more information, please reach out to support.

Base URL

All URLs referenced in this document have the following base:

https://faxapi.voxtelesys.net/api/v1

This API is served over HTTPS to ensure data privacy. Unencrypted HTTP is not supported.

Number Formatting

This API uses E.164 number formatting. E.164 is an international standard for the PSTN that ensures number uniqueness. E.164 numbers are formatted [country code][subscriber number] and can have a maximum of 15 digits.

Examples:

E.164 Format	Country	Country Code	Subscriber Number
+17019299797	US	1	7019299797

Authentication

Request:

curl -X GET \
  --url https://faxapi.voxtelesys.net/api/v1/faxes \
  --header 'authorization: Bearer YOUR_API_KEY'

The Voxtelesys Fax API uses API keys to authenticate requests. You can view and manage your API keys via the Voxtelesys Portal. Be sure to keep your API keys secure, and do not share in publicly accessible areas such as GitHub, client-side code, etc.

To use your API key, simply pass the key in the Authorization header:

Authorization: Bearer [YOUR_API_KEY]

Faxes

The faxes resource gives you the ability to send outbound faxes and to retrieve both inbound and outbound faxes.

Retrieve a fax

Request:

curl --request GET
    --header 'Authorization: Bearer APIKEY' 
    --url 'https://faxapi.voxtelesys.net/api/v1/faxes/fc90ecf7-ada9-4843-9bd2-3cd9ddfa33b7'

Response:

{
    "id": "fc90ecf7-ada9-4843-9bd2-3cd9ddfa33b7",
    "created_at": "2024-01-01T16:51:16.979Z",
    "modified_at": "2024-01-01T16:51:17.320Z",
    "direction": "outbound",
    "to": "15556667777",
    "from": "15556668888",
    "status": "failed",
    "url": "https://example.com/file.pdf",
    "pages": 0,
    "duration": 0,
    "attempts": 1,
    "error": {
        "code": 5312,
        "description": "internal error"
    }
}

Endpoint for retrieving an inbound or outbound fax.

HTTP Request

GET /faxes/{id}

URL Parameters

Param	Type	Description	Example
id	string	ID of fax	fc90ecf7-ada9-4843-9bd2-3cd9ddfa33b7

List faxes

Request:

curl --request GET
    --header 'Authorization: Bearer APIKEY' 
    --url 'https://faxapi.voxtelesys.net/api/v1/faxes'

Response:

{
    "page_size": 1,
    "next_page": "K0NFRUBbQV00YjkxYmRkMWU0ZjlhY2Q4ZDUiXQ==",
    "results": [
        {
            "id": "4f778644-6e11-48f2-99eb-a32e4e1a5748",
            "created_at": "2024-06-19T15:38:16.451Z",
            "modified_at": "2024-06-19T15:38:17.140Z",
            "direction": "outbound",
            "to": "15556667777",
            "from": "15556668888",
            "status": "delivering",
            "url": "https://example.com/path/to/image.jpg",
            "pages": 0,
            "duration": 0,
            "attempts": 3
        }
    ]
}

Endpoint for retrieving a list of inbound and outbound faxes. To fetch all available faxes, the next_page parameter is available as a cursor to iterate over. The iteration process works by taking the next_page field in the response from the /faxes route and then providing the next_page parameter in the subsequent request to /faxes.

HTTP Request

GET /faxes

Query Parameters

Param	Type	Description	Example
page	integer	page number	1
next_page	string	page cursor	abc123

Send a fax

Request:

curl --request POST
    --header 'Authorization: Bearer APIKEY' 
    --header 'Content-Type: application/json' 
    --data '{"to": "13003003000", "from": "13003003001", "url": "https://example.com/path/to/image.jpg", "attempts": 1}'
    --url 'https://faxapi.voxtelesys.net/api/v1/faxes'

Response:

{
    "id": "fc90ecf7-ada9-4843-9bd2-3cd9ddfa33b7",
    "created_at": "2024-01-01T16:51:16.979Z",
    "modified_at": "2024-01-01T16:51:16.979Z",
    "direction": "outbound",
    "to": "15556667777",
    "from": "15556668888",
    "status": "queued",
    "url": "https://example.com/file.pdf",
    "attempts": 1
}

Endpoint for creating a new outbound fax.

HTTP Request

POST /faxes

HTTP Body

The body of the request should be JSON with the following data:

Field	Type	Required	Description	Example
to	string	yes	The number to dial in E.164 format.	+15556667777
from	string	yes	The number to originate the call from in E.164 format.	+15556668888
url	string	yes	The URL to download the file to fax. Must be a JPEG, PDF, PNG, or TIFF.	https://example.com/file.pdf
attempts	number	no	The number of attempts to make when sending the fax. Defaults to 3.	3

Webhooks

Webhooks are user-defined HTTP callbacks. They are triggered by some event in a web application and can facilitate integrating different application or third-party APIs, like Voxtelesys.

Voxtelesys uses webhooks to let your application know when events happen, such as receiving an inbound fax. When the event occurs, Voxtelesys makes an HTTP request (usually a POST or a GET) to the URL you configured for the webhook. Voxtelesys' request will include details of the event such as the incoming phone number. For POST HTTP requests, the content will be sent in the body as type application/json.

Fax Webhooks

Working with the Voxtelesys Fax API, your web application can receive webhooks for sent and received faxes.

When receiving a fax, a webhook will be sent once the fax has been fulled received and the URL is available to download the file.

When sending a fax, a webhook is sent upon completion of the fax.

Fax Webhook

Property	Type	Required	Description
type	string	true	Callback type. Always fax.
id	string	true	ID of fax.
direction	string	true	Direction of fax.
to	string	true	Recipient of fax.
from	string	true	Sender of fax.
status	string	true	A descriptive status for the fax.
time	string	true	Timestamp of fax.
pages	string	true	The number of pages associated with fax.
duration	string	true	The duration of the fax, in seconds.
url	string	false	Public URL of file used to send fax.
links	string	false	Object containing related data.
links[].media	string	false	Linked media, if applicable.
error	string	false	Object containing error information, if applicable.
error.code	string	false	Error code.
error.description	string	false	Error description.

Errors

Voxtelesys reports faxing errors via HTTP callbacks. Errors while interacting with the REST API are returned in response to the request. If you have any questions, or need help resolving errors, please contact support.

HTTP errors

Error Response JSON:

{
  "status": "error", // label for error status
  "message": "missing service_trunk_group_id", // description of error
  "error_id": "330d1614-f204-411f-a518-1f3aa15773e7" // unique error ID
}

Code	Description
401	Unauthorized - The provided credentials failed. Please see authentication for more details.
404	Not Found - The request URL and/or HTTP method was not found.
422	Unprocessable Entity - The request data and/or parameters are not valid.
500	Internal Server Error - An error occurred within the server. Please contact Voxtelesys with the provided error_id to resolve this error.

Fax Errors

Code	Description
4201	file format invalid
4202	file too large
4203	file download failed
5100	unknown fax failure
5101	the CED tone exceeded 5s
5102	timed out waiting for initial communication
5103	timed out waiting for the first message
5104	timed out waiting for procedural interrupt
5105	the HDLC carrier did not stop in a timely manner
5106	failed to train with any of the compatible modems
5107	operator intervention failed
5108	far end is not compatible
5109	far end is not able to receive
5110	far end is not able to transmit
5111	far end cannot receive at the resolution of the image
5112	far end cannot receive at the size of image
5113	unexpected message received
5114	received bad response to DCS or training
5115	received a DCN from remote after sending a page
5116	invalid ECM response received from receiver
5117	received a DCN while waiting for a DIS
5118	invalid response after sending a page
5119	received other than DIS while waiting for DIS
5120	received no response to DCS, training or TCF
5121	no response after sending a page
5122	timed out waiting for receiver ready (ECM mode)
5123	invalid ECM response received from transmitter
5124	DCS received while waiting for DTC
5125	unexpected command after page received
5126	carrier lost during fax receive
5127	timed out while waiting for EOL (end of line)
5128	timed out while waiting for first line
5129	timer T2 expired while waiting for DCN
5130	timer T2 expired while waiting for phase D
5131	timer T2 expired while waiting for fax page
5132	timer T2 expired while waiting for next fax page
5133	timer T2 expired while waiting for RR command
5134	timer T2 expired while waiting for NSS, DCS or MCF
5135	unexpected DCN while waiting for DCS or DIS
5136	unexpected DCN while waiting for image data
5137	unexpected DCN while waiting for EOM, EOP or MPS
5138	unexpected DCN after EOM or MPS sequence
5139	unexpected DCN after RR/RNR sequence
5140	unexpected DCN after requested retransmission
5141	TIFF/F file cannot be opened
5142	TIFF/F page not found
5143	TIFF/F format is not compatible
5144	TIFF/F page number tag missing
5145	incorrect values for TIFF/F tags
5146	bad TIFF/F header - incorrect values in fields
5147	cannot allocate memory for more pages
5148	disconnected after permitted retries
5149	the call dropped prematurely
5150	poll not accepted
5151	far end's ident is not acceptable
5152	far end's sub-address is not acceptable
5153	far end's selective polling address is not acceptable
5154	far end's polled sub-address is not acceptable
5155	far end's sender identification is not acceptable
5156	far end's password is not acceptable
5157	far end's transmitting subscriber internet address is not acceptable
5158	far end's internet routing address is not acceptable
5159	far end's calling subscriber internet address is not acceptable
5160	far end's internet selective polling address is not acceptable
5161	far end's called subscriber internet address is not acceptable
5300	internal error
5301	internal error
5302	internal error
5303	internal error
5304	internal error
5305	internal error
5306	internal error
5307	internal error
5308	internal error
5309	internal error
5310	internal error
5311	internal error
5312	internal error
5313	internal error
5314	failed to fetch file
5315	internal error
5316	internal error
5317	internal error