Fax (1.0.0)

Everything about Fax Sending

Send Fax

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...
Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

post/v3/fax/send
Request samples
application/json
{
  • "file_url": "{{fileURL}}",
  • "messages": [
    ]
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Fax queued for delivery.",
  • "data": {
    }
}

Calculate Fax Price

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...
Request
header Parameters
Content-Type
string
Example: application/json
Request Body schema: application/json
object
Responses
200

Successful response

post/v3/fax/price
Request samples
application/json
{
  • "file_url": "{{fileURL}}",
  • "messages": [
    ]
}
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here are some prices.",
  • "data": {
    }
}

View Fax Receipts

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:

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.

  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...
Request
header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/fax/receipts
Request samples 
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/fax/receipts'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here are your delivery receipts.",
  • "data": {
    }
}

View Specific Fax Receipt

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...
Request
path Parameters
message_id
required
string
header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/fax/receipts/{message_id}
Request samples 
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/fax/receipts/{message_id}'
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here is your fax receipt.",
  • "data": {
    }
}

View Fax History

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...
Request
header Parameters
Content-Type
string
Example: application/json
Responses
200

Successful response

get/v3/fax/history
Request samples 
curl --include \
     --header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA=="  \

'https://rest.clicksend.com/v3/fax/
Response samples
application/json
{
  • "http_code": 200,
  • "response_code": "SUCCESS",
  • "response_msg": "Here is your history.",
  • "data": {
    }
}
Copyright © ClickSend 2024. All right reserved.