Create and send a fax

Method

POST

Path

faxes

Request Parameters

Name	Type	Description
to	Phone Number	A phone number in E.164 format (+[country code][number]). Put square brackets after parameter name to send to multiple recipients (e.g. to[])
file	Binary Stream	The file you wish to fax. At least one file or content_url parameter is required. Must have file name in the file field of the body-part header. Put square brackets after parameter name to send multiple files (e.g. file[])
content_url	string	A URL to be rendered and sent as the fax content. At least one file or content_url parameter is required. Put square brackets after parameter name to include content from multiple URLs (e.g. content_url[]). If the file param is specified as well, content from URLs will be rendered before content from files.
header_text	string	Text that will be displayed at the top of each page of the fax. 50 characters maximum. Default header text is "-". Note that the header is not applied until the fax is transmitted, so it will not appear on fax PDFs or thumbnails.
batch_delay	int	Enables batching and specifies the amount of time, in seconds, before the batch is fired. Maximum delay is 3600 (1 hour). Actual delay will be at least 5 seconds.
batch_collision_avoidance	boolean	When batch_delay is set to 'true', fax will be blocked until the receiving machine is no longer busy. See batching for more info. Default is 'false'.
callback_url	URL	You can specify a callback url that will override the one you have defined globally for your account.
cancel_timeout	int	A number of minutes after which the fax will be canceled if it hasn't yet completed. Must be between 3 and 60. Additionally, for faxes with a batch_delay, the cancel_timeout must be at least 3 minutes after the batch_delay. If it is not, it will automatically be extended when batching.
tag[TAG_NAME]	string	A tag that contains metadata relevant to your application. (e.g. You may wish to tag a fax with an order id in your application. You could pass Phaxio the following parameter: tag[order_id]=1234). You may specify up to 10 tags.
caller_id	Phone Number	A Phaxio phone number you would like to use for the caller id.
test_fail	string	When using a test API key, this will simulate a sending failure at Phaxio. The contents of this parameter should be one of the Phaxio error types which will dictate how the fax will "fail".

Fax content

Fax content may be supplied via one or more files or URLs of supported filetypes.

file

Files may be included in the POST request as multipart/form-data parts.

content_url

Give us any URL on the Internet (including ones with basic authentication), and we’ll pull it down and make it a fax. This might be useful to you if you’re using a web framework for templating and creating fancy fax files.

Please note: If you are passing Phaxio a secure URL (starting with https://), make sure that your SSL certificate (including your intermediate cert, if you have one) is installed properly, valid, and up-to-date.

Response

A JSON object with success, message, and data attributes. The data attribute contains one element, id, which is the ID number of the fax.

Sample Call

curl https://api.phaxio.com/v2/faxes \
    -u 'API_KEY:API_SECRET' \
    -F 'to=+14141234567' \
    -F 'file=@/path/to/a/supported/file'

Sample call with multiple content URLs and files

curl https://api.phaxio.com/v2/faxes \
    -u 'API_KEY:API_SECRET' \
    -F 'to=+14141234567' \
    -F 'content_url[]=http://www.google.com' \
    -F 'content_url[]=http://www.yahoo.com' \
    -F 'file[]=@/path/to/a/supported/image.png' \
    -F 'file[]=@/path/to/a/supported/document.doc'

Sample Response

{
    "success":true,
    "message":"Fax queued for sending",
    "data":{
        "id":1234
    }
}

Restrictions

Phaxio places some restrictions on request files and page length in order to ensure timely processing of your faxes and to ensure a high transmission success rate.

The total request size for sending a fax may not exceed 20MB.
The total number of pages for any fax may not exceed 200 pages.
A maximum of 20 files may be submitted per fax.
A maximum of 15 recipients may be submitted per fax.