Fax Service

Send Fax

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/fax/

Send a file to be faxed to an user’s phone number.

Authorization rights: minimum EndUser.

Example request:

POST /api/v1/tenants/foo/groups/foogroup/users/foouser/services/fax/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "faxNumber": "+3225126780",
   "faxFile": {
      "content": CONTENT_PNG_IMAGE_FILE,
      "fileName": "BWFaxDoc.png"
   }
}

Request JSON Object:

• faxNumber (string) – (Required) the fax phone number. Can be a fax number (see Phone Number) or an extension (see Extension).

• faxFile (object) – (Required) the file to upload. See Fax File Attributes.

Example response:

HTTP/1.1 201 CREATED
Content-Type: "application/json"

{
   "faxId": "bw_3ecf7fa63af349ddaf36833afbc45b5c"
}

Response JSON Object:

• faxId (string) – (Always returned) the fax ID.

Status Codes:

• 201 Created – fax initiated

• 400 Bad Request –

  invalid request due to invalid parameters or invalid file content, with possible sub error codes:

  • 2 INVALID_PARAMETERS: “The image size is too big.”

  • 2 INVALID_PARAMETERS: “The image file is not valid.”

  • 2 INVALID_PARAMETERS: “The file is not an image.”

  • 2 INVALID_PARAMETERS: “Address must be a sip or tel URI.”

  • 18 INVALID_OPERATION: “The image size is too big.”

• 403 Forbidden – error invalid calling user

Retrieve Fax List

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/fax/

Retrieve all of the non-expired statuses of previous fax requests initiated by the user or an error response.

Authorization rights: minimum EndUser.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/users/foouser/services/fax/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}

Example response:

HTTP/1.1 201 CREATED
Content-Type: "application/json"

{
   "faxes": [
      {
         "faxId": "bw_3ecf7fa63af349ddaf36833afbc45b5c",
         "faxNumber": "+3225126780",
         "fileName": "BWFaxDoc.png",
         "status": "Transmitting",
         "timestamp": "2021-11-25T11:57:51.717000"
      },
      {
         "faxId": "bw_b97b932ed0374428864142c0d9071983",
         "faxNumber": "+3225126778",
         "fileName": "1PageDoc.tiff",
         "status": "Error - File Transfer Failed",
         "timestamp": "2021-11-25T12:12:54.964000"
      },
      {
         "faxId": "bw_1aa12511669341c6a9e787124bd08c7b",
         "faxNumber": "Fax_ApioUserTest@netaxis.be",
         "fileName": "5PagesDoc.tiff",
         "status": "Preparing To Transmit",
         "timestamp": "2021-11-25T10:31:23.763000"
      }
   ]
}

Response JSON Object:

• faxes (array) – (Always returned) the non-expired statuses of previous fax. See Fax List Item.

Status Codes:

• 200 OK – ok

• 400 Bad Request – error

Retrieve Fax

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/fax/bw_3ecf7fa63af349ddaf36833afbc45b5c/

Retrieve all of the non-expired statuses of previous fax requests initiated by the user or an error response.

Authorization rights: minimum EndUser.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/users/foouser/services/fax/bw_3ecf7fa63af349ddaf36833afbc45b5c/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "faxId": "bw_3ecf7fa63af349ddaf36833afbc45b5c",
   "faxNumber": "+3225126780",
   "fileName": "BWFaxDoc.png",
   "status": "Transmitting",
   "timestamp": "2021-11-25T11:57:51.717000"
}

Response JSON Object:

• faxId (array) – (Always returned) See faxId from Fax List Item.

• faxNumber (array) – (Always returned) See faxNumber from Fax List Item.

• fileName (array) – (Always returned) See fileName from Fax List Item.

• status (array) – (Always returned) See status from Fax List Item.

• timestamp (array) – (Always returned) See timestamp from Fax List Item.

Status Codes:

• 200 OK – ok

• 404 Not Found – not found

Fax File Attributes

Name	Type	Method	Description
		POST
content	String	R	The image file to upload, base64 encoded.
fileName	String	R	The file name.

Fax List Item

Name	Type	Method	Description
		GET
faxId	String	A	The unique identifier.
faxNumber	String	A	The destination.
fileName	String	A	The file name.
status	String	A	The status. Possible values (may be a not exhaustive list): * “Preparing To Transmit”, * “Transmitting”, * “Error - File Transfer Failed”.
timestamp	String	A	The timestamp.