Fax (/fax/)

_{You can test API methods on the interactive API browser page and without writing code}_{Some of the resources described on the page may not be available by default due to the type of application (see Creating and authorizing applications).}

This resource allows you to configure the parameters of internal fax numbers, as well as to receive and send fax messages.

Fax configuration

Parameter	Type	Mandatory	Default value	Description
fax_mailto	string	none	null	The email address to which the fax messages received by the internal number will be sent. It is possible to list several addresses separated by commas

Example

In the internal number of the “fax" type, we will add the email addresses to which the fax messages received by this internal number will be sent:

…

System response:

{
  "fax_mailto": "admin@host.com,user@host.com"
}

Receiving fax messages

It is possible to receive and manage messages received by internal fax numbers.

Description of fields

Parameter	Type	Description
caller_id	string	The number of the sender of the message
client_id	long	Client ID
datetime	string	Date and time when the message was received
destination	string	Number of the message recipient
extension_group_id	long	ID of the internal numbers group. It can have the value 'null' if the internal number does not belong to any of the groups
extension_id	long	Internal number ID
file_size	long	Message file size
uuid	string	Message ID

Example

…

System response:

[
  {
    "caller_id": "1844*001",
    "client_id": 12,
    "datetime": "2015-11-25 15:08:06",
    "destination": "78123092631",
    "extension_group_id": null,
    "extension_id": 122,
    "file_size": 23142,
    "uuid": "1a66f8c6-936d-11e5-8563-d3163e2a7e2d"
  },
  {
    "caller_id": "1844*002",
    "client_id": 12,
    "datetime": "2015-11-25 15:16:10",
    "destination": "78123092631",
    "extension_group_id": null,
    "extension_id": 122,
    "file_size": 23138,
    "uuid": "3ae42208-936e-11e5-85a2-d3163e2a7e2d"
  }
]

Sending fax messages

^{Content-Type when uploading files When uploading files via the POST method, set the}^{Content-Type header}^{to the}^{multipart/form-data}^{value with the}^boundary^{parameter, which contains a sequence of characters separating the parts of the request body. The parameters of the audio file and the file itself are passed as}^{form fields}^{. In all other methods, including updating information about the audio file, you should use the usual}^{Content-Type: application/json}^{and pass the information in JSON format. It is worth noting that in most cases, various libraries for working with web resources generate the request body and the}^Content-Type^{header with the}^boundary^{parameter automatically.}

Description of the request fields

Parameter	Type	Mandatory	Default value	Description
dst_num	string	yes		The number to send the fax to
file	file	yes		A file in tiff or pdfformat . The maximum file size is 10 megabytes

Example

Sending the faxtest.tif file to the number 1234567

…

System response:

{
  datetime: "2016-04-07 20:08:54",
  dst_num: "1234567",
  id: 174,
  status: "ready_to_send"
}

From the point of view of uploading files, sending a fax is the same as adding audio, so you can see examples of requests containing files on the "Audio Files" page.

Getting information about the sending status

To get information about the status of sending a fax message, you need to use the appropriate resource:

to get a list of all fax messages sent from an internal number: GET /extension/{extension_id}/fax/out/
to get information about a specific sent fax message: GET /extension/{extension_id}/fax/out/{message_id}

Example

Request information about a message with id 175 sent from an internal number with id 122:

…

System response:

{
  "status": "sent",
  "dst_num": "1234567",
  "id": 175,
  "datetime": "2016-04-11 18:07:53"
}

Description of fields

Parameter	Type	Description
datetime	string	Date and time when the fax message was sent
dst_num	string	The number to which the fax message was sent
id	long	Fax message ID
status	string	The status of sending the fax message. See the description below

Sending status

Status	Description
ready_to_send	The message is queued for sending. You can cancel sending a message with this status
sending	Message in the process of sending
failed	Failed to send the message. A message with this status can be sent again or canceled.
canceled	Sending canceled
error	A sending error occurred

Repeat and cancel sending

A message that failed to be sent (the failed status) can be sent again or canceled. You can also cancel sending a message with the ready_to_send status.

To retry sending a message or cancel sending a message, you must make a PUT request to the resource /extension/{extension_id}/fax/out/{message_id}?action={action},where the URL parameter “action" can take the values retry and cancel to retry sending and cancel sending a message, respectively.

Example

We will repeat sending the message with id 175 from the internal number with id 122:

…

System response:

{
  "status": "ready_to_send",
  "dst_num": "123",
  "id": 175,
  "datetime": "2016-04-11 18:07:53"
}

Resources of the "Client" section

GET /client/{client_id}/fax/in/

GET /client/{client_id}/fax/in/

Get a list of incoming fax messages for a client

URL Parameters

Name	Type
client_id	string

Request parameters

Name	Type
start_datetime	string
uuid	array [string]
destination	array [string]
caller_id	array [string]
end_datetime	string
extension_group_id	integer
order	string
extension_id	integer

Response fields

Name	Type
caller_id	string
client_id	long
datetime	string
destination	string
extension_group_id	long
extension_id	long
file_size	long
uuid	string

GET /client/{client_id}/fax/in/{fax_uuid}

GET /client/{client_id}/fax/in/{fax_uuid}

Get an incoming fax message file

URL Parameters

Name	Type
fax_uuid	string
client_id	string

DELETE /client/{client_id}/fax/in/{fax_uuid}

DELETE /client/{client_id}/fax/in/{fax_uuid}

Delete an incoming fax message

URL Parameters

Name	Type
fax_uuid	string
client_id	string

GET /client/{client_id}/fax/out/

GET /client/{client_id}/fax/out/

Get a list of outgoing fax messages

URL Parameters

Name	Type
client_id	string

Request parameters

Name	Type
start_datetime	string
extension_id	integer
end_datetime	string
order	string

Response fields

Name	Type
id	long
status	string
dst_num	string
extension_id	long
datetime	string

Resources of the "Internal numbers group" section

GET /extension_group/{ext_group_id}/fax/in/

GET /extension_group/{ext_group_id}/fax/in/

Get a list of incoming fax messages for a group of internal numbers

URL Parameters

Name	Type
ext_group_id	string

Request parameters

Name	Type
start_datetime	string
uuid	array [string]
destination	array [string]
caller_id	array [string]
end_datetime	string
order	string
extension_id	integer

Response fields

Name	Type
caller_id	string
client_id	long
datetime	string
destination	string
extension_group_id	long
extension_id	long
file_size	long
uuid	string

GET /extension_group/{ext_group_id}/fax/in/{fax_uuid}

GET /extension_group/{ext_group_id}/fax/in/{fax_uuid}

Get an incoming fax message file

URL Parameters

Name	Type
ext_group_id	string
fax_uuid	string

Resources of the "Internal number" section

PUT /extension/{extension_id}/fax/

PUT /extension/{extension_id}/fax/

Update the fax configuration

URL Parameters

Name	Type
extension_id	string

JSON parameters

Name	Type	Mandatory
email_to_fax_accept	string	none
fax_in_format	string	none
fax_mailto	string	none
fax_out_greeting	long	none

Response fields

Name	Type
email_to_fax_accept	string
fax_in_format	string
fax_mailto	string
fax_out_greeting	long

GET /extension/{extension_id}/fax/

GET /extension/{extension_id}/fax/

Get the fax configuration

URL Parameters

Name	Type
extension_id	string

Response fields

Name	Type
email_to_fax_accept	string
fax_in_format	string
fax_mailto	string
fax_out_greeting	long

GET /extension/{extension_id}/fax/in/

GET /extension/{extension_id}/fax/in/

Get a list of incoming fax messages for an internal number

URL Parameters

Name	Type
extension_id	string

Request parameters

Name	Type
start_datetime	string
uuid	array [string]
destination	array [string]
caller_id	array [string]
end_datetime	string
order	string

Response fields

Name	Type
caller_id	string
client_id	long
datetime	string
destination	string
extension_group_id	long
extension_id	long
file_size	long
uuid	string

GET /extension/{extension_id}/fax/in/{fax_uuid}

GET /extension/{extension_id}/fax/in/{fax_uuid}

Get an incoming fax message file

URL Parameters

Name	Type
extension_id	string
fax_uuid	string

POST /extension/{extension_id}/fax/out/

POST /extension/{extension_id}/fax/out/

Send a fax message

URL Parameters

Name	Type
extension_id	string

Response fields

Name	Type
datetime	string
dst_num	string
id	long
status	string

GET /extension/{extension_id}/fax/out/

GET /extension/{extension_id}/fax/out/

Get a list of outgoing fax messages

URL Parameters

Name	Type
extension_id	string

Request parameters

Name	Type
start_datetime	string
order	string
end_datetime	string

Response fields

Name	Type
datetime	string
dst_num	string
id	long
status	string

PUT /extension/{extension_id}/fax/out/{message_id}

PUT /extension/{extension_id}/fax/out/{message_id}

Repeat or cancel sending a fax message

URL Parameters

Name	Type
extension_id	string
message_id	integer

Request parameters

Name	Type
action	string

Response fields

Name	Type
datetime	string
dst_num	string
id	long
status	string

GET /extension/{extension_id}/fax/out/{message_id}

GET /extension/{extension_id}/fax/out/{message_id}

Get information about an outgoing fax message

URL Parameters

Name	Type
extension_id	string
message_id	integer

Response fields

Name	Type
datetime	string
dst_num	string
id	long
status	string