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[])
filename Binary Stream The file you wish to fax. This is optional if you specify string_data. Must have file name in the filename field of the body-part header. Put square brackets after parameter name to send multiple files (e.g. filename[])
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.
string_data string A string of html, plain text, or a URL. If additional files are specified as well, this data will be included first in the fax.
string_data_type enum Can be 'html', 'url', or 'text'. If not specified, default is 'text'. See string data rendering for more info.
batch boolean If present and true, fax will be sent in batching mode. Requires batch_delay to be specified. See batching for more info.
batch_delay int The amount of time, in seconds, before the batch is fired. Must be specified if `batch=true`. Maximum delay is 3600 (1 hour). Actual delay will be at least 5 seconds.
batch_collision_avoidance boolean If true when `batch=true`, 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.
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 tag: 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".
api_key string Your api key
api_secret string Your api secret


A JSON object with success, message, and faxId attributes.

Sample Call

curl \
    -F 'to=4141234567' \
    -F 'filename=@/path/to/a/supported/file' \
    -F 'api_key=API_KEY' \
    -F 'api_secret=API_SECRET'

Click here for a list of supported filetypes.

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.