10. Managing Faxes via the REST API

10.1. Configuring Fax Settings
10.1.1. Retrieving Fax Settings
10.1.2. Updating Fax Settings
10.2. Sending a Fax
10.3. Receiving a Fax
10.4. Configuring Mail2Fax Settings
10.4.1. Retrieving Mail2Fax Configuration
10.4.2. Updating Mail2Fax Configuration
10.5. Using Advanced Faxserver and Mail2Fax Settings via the REST API

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.

10.1. Configuring Fax Settings

10.1.1. Retrieving 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" : null
10.1.2. Updating Fax Settings

The 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 } ]'

10.2. Sending a Fax

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'

10.3. Receiving a Fax

All received faxes are stored on the server and can be retrieved on demand. You can retrieve a stored fax by following these steps:

  1. 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"
  2. 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

10.4. Configuring Mail2Fax Settings

The configuration of Mail2Fax settings via the REST API is similar to the fax settings configuration.

10.4.1. Retrieving Mail2Fax 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"
      }
   ]
10.4.2. Updating Mail2Fax Configuration

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" } ] } ]'

10.5. Using Advanced Faxserver and Mail2Fax Settings via the REST API

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: