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. A 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).
batch_collision_avoidance boolean When batch_delay is set, fax will be blocked until the receiving machine is no longer busy. See batching for more info.
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 10 files may be submitted per fax.