faxapi.voxtelesys.com Open in urlscan Pro
104.18.12.150  Public Scan

Form analysis
0 forms found in the DOM

Text Content

shell

Fax API Introduction
* Base URL
* Number Formatting
Authentication Faxes
* Retrieve a fax
* List faxes
* Send a fax
Webhooks
* Fax Webhooks
Errors
* HTTP errors
* Fax 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": 1,
    "page_size": 1,
    "page_count": 83,
    "count": 83,
    "results": [
        {
            "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/path/to/image.jpg",
            "pages": 0,
            "duration": 0,
            "attempts": 1,
            "error": {
                "code": 5312,
                "description": "internal error"
            }
        }
    ]
}


Endpoint for retrieving a list of inbound and outbound faxes.


HTTP REQUEST

GET /faxes


QUERY PARAMETERS

Param Type Description Example page integer page number 1 page_size integer
number of items to return per page 25




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




shell