Fax

Everything about Fax Sending

Languages
Servers
https://rest.clicksend.com/

Send Fax

Request

Supported File Types

  • Supported file types are listed below. If you need to convert a file to a supported format, it can be first passed to our uploads endpoint: /uploads?convert=fax
  • This will return a URL to the converted pdf file that can be used in the /fax/send endpoint.
  • Contact us to add support for any other file type.

Documents

File typeRequired to be passed to uploads endpoint first?
pdfNo
docxYes
docYes
rtfYes

Send a fax using supplied supported file-types.

Letter File Options

Use existing URL

With this option, you can use an existing URL to a pdf document. For example, you might generate the pdf on your server.

When using an existing url make sure that it is publicly accessible as it will not work if it is private.

Upload File to Our Server

With this option, you can use the /uploads endpoint to upload the document. The /uploads endpoint returns a URL that can be used in the /fax/send endpoint.

Properties

NameTypeRequiredRestrictionsDescription
file_urlstringtruenoneURL of file to send
sourcestringtruenoneYour method of sending e.g. 'wordpress', 'php', 'c#'.
tostringtruenoneRecipient fax number in E.164 format.
list_idinteger(int32)falsenoneYour list ID if sending to a whole list. Can be used instead of 'to'.
fromstringtrueyesYour sender id. Must be a valid fax number.
scheduleinteger(int32)falsenoneLeave blank for immediate delivery. Your schedule time in unix format http://help.clicksend.com/what-is-a-unix-timestamp
custom_stringstringfalsenoneYour reference. Will be passed back with all replies and delivery reports.
countrystringfalsenoneISO alpha-2 character country code e.g. 'US', we use this to format the recipient number if it's not in international format.
from_emailstringfalsenoneAn email address where the reply should be emailed to.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication,more info...
Headers
Content-Typestring
Example: application/json
Bodyapplication/json
file_urlstring
Example: "{{fileURL}}"
messagesArray of objects
Example: [{"source":"php","from":"+61411111111","to":"+61411111111","custom_string":"A custom string to fax"}]
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request POST \

     --header "Content-Type: application/json" \
     --data-binary "{
    \"file_url\":\"https://s3-ap-southeast-2.amazonaws.com/clicksend-api-downloads/_public/_examples/document.pdf\",
    \"messages\":[
        {
            \"source\":\"php\",
            \"to\":\"+61261111111\",
            \"schedule\":\"1436874701\",
            \"custom_string\":\"custom_string\",
            \"country\":\"AF\",
            \"from_email\":\"will@smith.com\"
        },
        {
            \"source\":\"php\",
            \"to\":\"+61261111122\",
            \"schedule\":\"1436874701\",
            \"custom_string\":\"custom_string\",
            \"country\":\"AF\",
            \"from_email\":\"john@doe.com\"
        }
    ]
}" \
'https://rest.clicksend.com/v3/fax/send'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP status code of the response.

Example: 200
response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Fax queued for delivery."
dataobject
Response
application/json
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Fax queued for delivery.", "data": { "total_price": 13.2, "total_count": 1, "queued_count": 1, "messages": [], "_currency": {} } }

Calculate Fax Price

Request

Calculate Total Price for Fax Messages sent

Properties

NameTypeRequiredRestrictionsDescription
file_urlstringtruenoneURL of file to send
sourcestringtruenoneYour method of sending e.g. 'wordpress', 'php', 'c#'.
tostringtruenoneRecipient fax number in E.164 format.
list_idinteger(int32)falsenoneYour list ID if sending to a whole list. Can be used instead of 'to'.
fromstringtrueyesYour sender id. Must be a valid fax number.
scheduleinteger(int32)falsenoneLeave blank for immediate delivery. Your schedule time in unix format http://help.clicksend.com/what-is-a-unix-timestamp
custom_stringstringfalsenoneYour reference. Will be passed back with all replies and delivery reports.
countrystringfalsenoneISO alpha-2 character country code e.g. 'US', we use this to format the recipient number if it's not in international format.
from_emailstringfalsenoneAn email address where the reply should be emailed to.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication,more info...
Headers
Content-Typestring
Example: application/json
Bodyapplication/json
file_urlstring
Example: "{{fileURL}}"
messagesArray of objects
Example: [{"source":"php","from":"+61411111111","to":"+61411111111","from_email":"test@test.com","schedule":"1436874701","custom_string":"custom_string"}]
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \
     --request POST \

     --header "Content-Type: application/json" \
     --data-binary "{
    \"file_url\":\"https://s3-ap-southeast-2.amazonaws.com/clicksend-api-downloads/_public/_examples/document.pdf\",
    \"messages\":[
        {
            \"source\":\"php\",
            \"to\":\"+61261111111\",
            \"schedule\":\"1436874701\",
            \"custom_string\":\"custom_string\",
            \"country\":\"AF\",
            \"from_email\":\"will@smith.com\"
        },
        {
            \"source\":\"php\",
            \"to\":\"+61261111122\",
            \"schedule\":\"1436874701\",
            \"custom_string\":\"custom_string\",
            \"country\":\"AF\",
            \"from_email\":\"john@doe.com\"
        }
    ]
}" \
'https://rest.clicksend.com/v3/fax/price'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP status code of the response.

Example: 200
response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here are some prices."
dataobject
Response
application/json
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Here are some prices.", "data": { "total_price": 13.2, "total_count": 1, "queued_count": 1, "messages": [], "_currency": {} } }

View Fax Receipts

Request

Get List of Fax Receipts

Push Delivery Receipts

If you prefer, we can push message replies to your server as they arrive with us.

  1. Log into your account.
  2. Click on your profile on the top right.
  3. Then click on the Messaging Settings option.
  4. Click on Fax then Delivery Reports.
  5. Click the 'Add New Rule' button.
  6. Select the 'URL' action.
  7. Enter the URL and click 'Save'.

The following variables will be posted to the URL specified:

VariableDescription
timestamp_sendTimestamp of the original send request in UNIX format. e.g 1439173980
timestampTimestamp of delivery report in UNIX format. e.g 1439173981
message_idMessage ID, returned when originally sending the message.
statusDelivered or Undelivered
status_codeStatus code. Refer to 'Fax Delivery Status Codes' in docs.
status_textStatus text.
error_codeError code.
error_textError text.
custom_stringA custom string used when sending the original message.
user_idThe user ID of the user who sent the message.
subaccount_idThe subaccount ID of the user who sent the message.
message_type'fax' (constant).

Pull Delivery Receipts

Receive delivery reports by polling. You can poll our server and retrieve delivery reports at a time that suits you.

  1. Log into your account.
  2. Click on your profile on the top right.
  3. Then click on the Messaging Settings option.
  4. Click on Fax then Delivery Rules.
  5. Click the 'Add New Rule' button.
  6. Select the 'Poll' action.
  7. Then click 'Save'.

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication,more info...
Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/fax/receipts'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP status code of the response.

Example: 200
response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here are your delivery receipts."
dataobject
Response
application/json
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Here are your delivery receipts.", "data": { "total": 2, "per_page": 15, "current_page": 1, "last_page": 1, "next_page_url": null, "prev_page_url": null, "from": 1, "to": 2, "data": [] } }

View Specific Fax Receipt

Request

Get a single fax receipt based on message id.

Parameters

ParameterInTypeRequiredDescription
message_idpathstringtrueID of the message receipt to retrieve

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication,more info...
Path
message_idstringrequired
Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/fax/receipts/{message_id}'

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP status code of the response.

Example: 200
response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here is your fax receipt."
dataobject(fax)
Response
application/json
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Here is your fax receipt.", "data": { "user_id": 1, "subaccount_id": 1, "list_id": null, "message_id": "6BBEB11E-CAA6-4B04-8537-63619F3D6B37", "to": "+61261111122", "from": "+61298441484", "carrier": "", "country": "AU", "custom_string": "custom_string", "schedule": "1436874701", "message_pages": 6, "message_price": "13.2000", "status_code": "201", "status_text": "Sent", "date_added": 1457504350, "from_email": "john@doe.com", "_file_url": "https://rest.clicksend.com/files/98DDA1A4-8A74-4831-8FAF-CC4B4EBD8241.pdf", "status": "SUCCESS" } }

View Fax History

Request

Get a list of Fax History.

Parameters

ParameterInTypeRequiredDescription
date_fromqueryinteger(int32)falseStart date (Unix Timestamp e.g. 1436849372)
date_toqueryinteger(int32)falseEnd date (Unix Timestamp e.g. 1436879372)
qquerystringfalseCustom query Example: status:Sent,status_code:201.
orderquerystringfalseOrder result by Example: date_added:desc,list_id:desc.
pagequeryinteger(int32)falsePage number
limitqueryinteger(int32)falseNumber of records per page

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication, more info...

Refer to Status Codes for definitions of HTTP status code responses.

This endpoint requires authentication,more info...
Headers
Content-Typestring
Example: application/json
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/fax/

Responses

Successful response

Bodyapplication/json
http_codeinteger

The HTTP status code of the response.

Example: 200
response_codestring

The response code indicating the status of the operation.

Example: "SUCCESS"
response_msgstring

A message describing the outcome of the operation.

Example: "Here is your history."
dataobject
Response
application/json
{ "http_code": 200, "response_code": "SUCCESS", "response_msg": "Here is your history.", "data": { "total": 2, "per_page": 15, "current_page": 1, "last_page": 1, "next_page_url": null, "prev_page_url": null, "from": 1, "to": 2, "data": [] } }