Send a fax

Operation

send

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

Response

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

Sample Call

curl https://api.phaxio.com/v1/send \
    -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

{
    "success":true,
    "message":"Fax queued for sending",
    "faxId":1234,
    "data":{
        "faxId":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.