Create and send a fax





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, all unicode characters accepted. 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.
header_page_nums boolean Turns page numbers in header on or off. Default: true
header_timezone string A TZ database name string specifying the timezone for the header timestamp.
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".
image_conversion_method string Determines how documents are converted to black and white. Value should be halftone or monochrome. Defaults to value selected on Fax Settings page.

Fax content

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


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


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.


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 \
    -F 'to=+14141234567' \
    -F 'file=@/path/to/a/supported/file'

Sample call with multiple content URLs and files

curl \
    -F 'to=+14141234567' \
    -F 'content_url[]=' \
    -F 'content_url[]=' \
    -F 'file[]=@/path/to/a/supported/image.png' \
    -F 'file[]=@/path/to/a/supported/document.doc'

Sample Response

    "message":"Fax queued for sending",


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.