Navbar
shell
  • Fax API Introduction
  • Authentication
  • Faxes
  • Webhooks
  • Errors
  • 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