It is possible to send and receive faxes and configure fax settings using the built-in REST API interface.
In subsequent sections you can find examples of using the API for sending, receiving faxes and changing fax settings.
The following example retrieves the fax settings for the subscriber with ID 3.
Method: GET Content-Type: application/hal+json https://127.0.0.1:1443/api/faxserversettings/3
The output format is as follows (only the relevant output data is shown):
"active" : true,
"destinations" : [
{
"destination" : "user@company.com",
"filetype" : "PDF14",
"incoming" : true,
"outgoing" : true,
"status" : true
}
],
"name" : null,
"password" : nullThe following example updates a specific parameter. Namely, it deactivates the fax feature for the subscriber with ID 3.
Method: PATCH
Content-Type: application/json-patch+json
https://127.0.0.1:1443/api/faxserversettings/3
--data-binary '[ { "op" : "replace", "path" : "/active", "value" : 0 } ]'The following request sends a PDF file located at /tmp/test_fax.pdf as fax to
431110002 from the subscriber with ID 3.
Method: POST
Content-Type: multipart/form-data
https://127.0.0.1:1443/api/faxes/
--form 'json={"destination" : "431110002", "subscriber_id" : 3}' --form 'faxfile=@/tmp/test_fax.pdf'All received faxes are stored on the server and can be retrieved on demand. You can retrieve a stored fax by following these steps:
Firstly, obtain the internal ID of the fax:
Method: GET Content-Type: application/json https://127.0.0.1:1443/api/faxes/3
This request returns the list of stored faxes for the subscriber with ID 3. One of the available faxes is returned like this:
"callee" : "431110002", "caller" : "431110001", "direction" : "out", "duration" : "0", "filename" : "d9799276-b7d9-454f-98c3-714edf7e3072.tif", "id" : 5, "pages" : "1", "quality" : "8031x7700", "reason" : "Normal Clearing / SIP 200 OK [1/3]", "signal_rate" : "14400", "status" : "SUCCESS", "subscriber_id" : 1, "time" : "2016-07-30 09:49:59"
Now, to retrieve the fax with ID 5, use the following request:
Method: GET Content-Type: application/hal+json https://127.0.0.1:1443/api/faxerecordings/5
By default, the fax is in the TIFF format. It is also possible to request it in a different format. To retrieve the same fax in PDF14, use the following request:
https://127.0.0.1:1443/api/faxerecordings/5?format=pdf14
The configuration of Mail2Fax settings via the REST API is similar to the fax settings configuration.
To get the Mail2Fax configuration for the subscriber with ID 3, use the following request:
Method: GET Content-Type: application/hal+json https://127.0.0.1:1443/api/mailtofaxsettings/3
The output format is as follows (only the relevant output data is shown):
"acl" : [],
"active" : false,
"secret_key" : "secretkeypassword",
"secret_key_renew" : "daily",
"secret_renew_notify" : [
{
"destination" : "user1@company.com"
}
]The following set of requests changes the Mail2Fax configuration with new secret key settings.
Secret key value:
Method: PATCH
Content-Type: application/json-patch+json
https://127.0.0.1:1443/api/faxserversettings/3
--data-binary '[ { "op" : "replace", "path" : "/secret_key", "value" : "newsecretkeypassword" } ]'Secret key renewal interval:
Method: PATCH
Content-Type: application/json-patch+json
--data-binary '[ { "op" : "replace", "path" : "/secret_key_renew", "value" : "monthly" } ]'List of email addresses that receive the automatic secret key update notifications:
Method: PATCH
Content-Type: application/json-patch+json
--data-binary '[ { "op" : "replace", "path" : "/secret_renew_notify", "value" : [ { "destination": "user2@company.com" }, { "destination": "user3@company.com" } ] } ]'On the NGCP REST API documentation web page you can find the complete list of available Faxserver and Mail2Fax configuration parameters: https://<ngcp_ip_address>:1443/api
| important | |
The information on the web page is relevant for your platform version and may change in next releases. |
After visiting the API documentation main page, you can find the following entries related to Faxserver operations: