Fax

Messaging

Fax

Everything about Fax Sending

Download OpenAPI description

fax.json

fax.yaml

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 type	Required to be passed to uploads endpoint first?
pdf	No
docx	Yes
doc	Yes
rtf	Yes

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

Name	Type	Required	Restrictions	Description
file_url	string	true	none	URL of file to send
source	string	true	none	Your method of sending e.g. 'wordpress', 'php', 'c#'.
to	string	true	none	Recipient fax number in E.164 format.
list_id	integer(int32)	false	none	Your list ID if sending to a whole list. Can be used instead of 'to'.
from	string	true	yes	Your sender id. Must be a valid fax number.
schedule	integer(int32)	false	none	Leave blank for immediate delivery. Your schedule time in unix format http://help.clicksend.com/what-is-a-unix-timestamp
custom_string	string	false	none	Your reference. Will be passed back with all replies and delivery reports.
country	string	false	none	ISO alpha-2 character country code e.g. 'US', we use this to format the recipient number if it's not in international format.
from_email	string	false	none	An 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...

Security

basicAuth

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

Name	Type	Required	Restrictions	Description
file_url	string	true	none	URL of file to send
source	string	true	none	Your method of sending e.g. 'wordpress', 'php', 'c#'.
to	string	true	none	Recipient fax number in E.164 format.
list_id	integer(int32)	false	none	Your list ID if sending to a whole list. Can be used instead of 'to'.
from	string	true	yes	Your sender id. Must be a valid fax number.
schedule	integer(int32)	false	none	Leave blank for immediate delivery. Your schedule time in unix format http://help.clicksend.com/what-is-a-unix-timestamp
custom_string	string	false	none	Your reference. Will be passed back with all replies and delivery reports.
country	string	false	none	ISO alpha-2 character country code e.g. 'US', we use this to format the recipient number if it's not in international format.
from_email	string	false	none	An 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...

Security

basicAuth

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.

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

The following variables will be posted to the URL specified:

Variable	Description
`timestamp_send`	Timestamp of the original send request in UNIX format. e.g 1439173980
`timestamp`	Timestamp of delivery report in UNIX format. e.g 1439173981
`message_id`	Message ID, returned when originally sending the message.
`status`	Delivered or Undelivered
`status_code`	Status code. Refer to 'Fax Delivery Status Codes' in docs.
`status_text`	Status text.
`error_code`	Error code.
`error_text`	Error text.
`custom_string`	A custom string used when sending the original message.
`user_id`	The user ID of the user who sent the message.
`subaccount_id`	The 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.

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

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

This endpoint requires authentication,more info...

Security

basicAuth

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

Parameter	In	Type	Required	Description
message_id	path	string	true	ID of the message receipt to retrieve

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

This endpoint requires authentication,more info...

Security

basicAuth

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

Parameter	In	Type	Required	Description
date_from	query	integer(int32)	false	Start date (Unix Timestamp e.g. 1436849372)
date_to	query	integer(int32)	false	End date (Unix Timestamp e.g. 1436879372)
q	query	string	false	Custom query Example: status:Sent,status_code:201.
order	query	string	false	Order result by Example: date_added:desc,list_id:desc.
page	query	integer(int32)	false	Page number
limit	query	integer(int32)	false	Number 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...

Security

basicAuth

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": [ … ]
  }
}

Fax

Send Fax

Request

Supported File Types

Documents

Letter File Options

Use existing URL

Upload File to Our Server

Properties

Responses

Was this helpful?

Calculate Fax Price

Request

Properties

Responses

Was this helpful?

View Fax Receipts

Request

Responses

Was this helpful?

View Specific Fax Receipt

Request

Parameters

Responses

Was this helpful?

View Fax History

Request

Parameters

Responses

Was this helpful?

Fax

Send Fax

RequestExpand all

Supported File Types

Documents

Letter File Options

Use existing URL

Upload File to Our Server

Properties

Responses

Was this helpful?

Calculate Fax Price

RequestExpand all

Properties

Responses

Was this helpful?

View Fax Receipts

Request

Responses

Was this helpful?

View Specific Fax Receipt

Request

Parameters

Responses

Was this helpful?

View Fax History

Request

Parameters

Responses

Was this helpful?

Request

Request