Skip to content

Incoming Fax REST API

Jump to bottom Edit New page
JR Comision edited this page Apr 14, 2020 · 16 revisions

I. API Access and General Usage

Prerequisites

To gain access to the system you must have a Monopond user account that is subscribed to a Fax Plan and a Numbers Plan.

API Web Service

The API is available as a RESTful Web Service and uses JSON format for the request and response body.

To access the API, use the following URLs:

  • Test environment: Please contact support to access the test environment
  • Production environment: https://api.monopond.com

Building a Request

Authorization Headers

The Incoming Fax API uses bearer tokens to authorize users on the platform.

To generate a token, log in to your account then go to Account Settings > Profile > API Tokens.

Once you have an API token, you can use it to send requests to the API. Simply add an authorization header in your requests:

Authorization: Bearer your_api_token

Accept Header

Your requests must contain an accept header for application/json:

Accept: application/json

Role Authorization

Aside from user authentication, users are authorized or restricted to access API functions based on the assigned user roles.

Roles

Here are the available roles for a user:

ROLE_TEAM_OWNER
ROLE_TEAM_MANAGER
ROLE_FINANCE_ADMIN
ROLE_PRODUCT_ACCESS

The allowed roles for each of the API functions are listed in the request definition.

II. Function Definitions

NOTE: To be able to receive messages, you must first own a fax number. The first few API functions below show how you can subscribe to fax numbers.

Show Available Fax Number Locations/Areas

Description

This function allows you to see the locations of fax numbers enabled for your account. The area ID is needed to view the list of available numbers for subscription.

Request

  • URL: /api/v1/number/available-location
  • Method: GET
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER

Response

  • Status: 200 OK
  • Body: List of Available Location Objects

Available Location:

Name Type Description
area Number Area The fax number area/location
cost BigDecimal The monthly cost of a number for the specific location
currency Currency The currency for the monthly cost
allowedToUseCredits Boolean Indicates whether number credits can be used to pay for numbers for the specific location

Number Area:

Name Type Description
id Long The id for the fax number area
name String The area/location name (this is usually the city name)
areaPrefix String The local prefix for the number
country String The country name where the area belongs to
countryPrefix String The country prefix for the number

Sample Response Body:

[
    {
        "area": {
            "id": 107,
            "name": "Whitby",
            "areaPrefix": "289",
            "areaGroup": {
                "id": 1,
                "type": "PROVINCE",
                "name": "Ontario"
            },
            "country": "Canada",
            "countryPrefix": "1",
            "_entityType": "NumberArea"
        },
        "cost": 0.22,
        "currency": "USD",
        "allowedToUseCredits": true
    },
    {
        "area": {
            "id": 108,
            "name": "Coniston",
            "areaPrefix": "705",
            "areaGroup": {
                "id": 1,
                "type": "PROVINCE",
                "name": "Ontario"
            },
            "country": "Canada",
            "countryPrefix": "1",
            "_entityType": "NumberArea"
        },
        "cost": 0.22,
        "currency": "USD",
        "allowedToUseCredits": true
    }
]

Show Available Fax Numbers

Description

This function allows you to see the list of available numbers for a specified location/area id. These available numbers are the numbers that you can subscribe to and receive fax from.

Request

  • URL: /api/v1/number/area/{areaId}/available-number
  • Method: GET
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER

Request Parameters:

Name Required Type Description
areaId X Long The area ID for the number
max Integer The maximum number of records to fetch; Default: 10

Response

  • Status: 200 OK
  • Body: List of Available Number Objects

Available Number:

Name Type Description
number String The fax number
numberArea Number Area The area of the specific fax number

Sample Response Body:

[
    {
        "number":"61290000001",
        "numberArea": {
            "id":24,
            "name":"Sydney",
            "areaPrefix":"29",
            "areaGroup":null,
            "country":"Australia",
            "countryPrefix":"61",
            "_entityType":"NumberArea"
        },
        "_entityType":"AvailableNumberDisplayDto"
    },
    {
        "number":"61290000002",
        "numberArea": {
            "id":24,
            "name":"Sydney",
            "areaPrefix":"29",
            "areaGroup":null,
            "country":"Australia",
            "countryPrefix":"61",
            "_entityType":"NumberArea"
        },
        "_entityType":"AvailableNumberDisplayDto"
    }
]

Show Subscription

Description

This function allows you to see the list of your plan subscriptions. One of the prerequisites for subscribing to a fax number is that your account must be subscribed to a numbers plan. The subscription, particularly the product subscription ID for "phone number", is needed to subscribe to a fax number.

Request

  • URL: /api/v1/subscription
  • Method: GET
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER, ROLE_FINANCE_ADMIN, ROLE_PRODUCT_ACCESS

Response

  • Status: 200 OK
  • Body: Subscription Object

Subscription:

Name Type Description
dateFrom Date The start date of the subscription
dateTo Date The end date of the subscription
isProcessing Boolean Indicates whether there are ongoing changes for the subscription
status String The current status of the subscription
subscriptions List of Product Subscriptions The list of product subscriptions
subscriptionCredits List of Subscription Credits The list of monthly inclusions/credits
teamId Date The account ID of the user

Product Subscription:

Name Type Description
id Long The id for the product subscription
type String The type of product subscription; Possible Values: PHONE_NUMBER, OUTGOING_FAX
currentPlan Plan Subscription The plan subscription you're currently subscribed to
nextPlan Plan Subscription The plan subscription to be subscribed to next period (Note: If a downgrade was made, the current and next plan subscriptions are different)

Plan Subscription:

Name Type Description
planId Long The ID of the subscribed plan
planName String The name of the subscribed plan
status String The status of the plan subscription
recurringFee BigDecimal The recurring/monthly cost for the subscribed plan
currency Currency The currency for the recurring/monthly cost of the plan

Subscription Credits:

Name Type Description
teamId Long The account ID of the user
type String The type of subscription credits that identifies where it can be used; Possible Values: INCOMING_FAX_PAGES, OUTGOING_FAX_PAGES, PHONE_NUMBER_CREDITS, CURRENCY
amount String The remaining amount of credits left for the subscription period
currency Currency The currency for the credits amount (Only valid for CURRENCY type)

Sample Response Body:

{  
   "teamId":5,
   "dateFrom":"2019-06-13T16:00:00.000Z",
   "dateTo":"2019-07-13T16:00:00.000Z",
   "status":"ACTIVE",
   "isProcessing":false,
   "subscriptionCredits":[  
      {  
         "teamId":5,
         "currency":null,
         "amount":13,
         "type":"INCOMING_FAX_PAGES",
         "_entityType":"SubscriptionCredits"
      },
      {  
         "teamId":5,
         "currency":null,
         "amount":3.0000000000,
         "type":"PHONE_NUMBER_CREDITS",
         "_entityType":"SubscriptionCredits"
      }
   ],
   "subscriptions":[  
      {  
         "id":10,
         "type":"PHONE_NUMBER",
         "currentPlan":{  
            "planId":5,
            "planName":"Sample Plan",
            "status":"ACTIVE",
            "recurringFee":0,
            "currency":"USD",
            "_entityType":"PlanSubscription"
         },
         "nextPlan":{  
            "planId":5,
            "planName":"Sample Plan",
            "status":"ACTIVE",
            "recurringFee":0,
            "currency":"USD",
            "_entityType":"PlanSubscription"
         },
         "_entityType":"ProductSubscription"
      },
      {  
         "id":4,
         "type":"OUTGOING_FAX",
         "currentPlan":{  
            "planId":3,
            "planName":"Sample Fax Plan",
            "status":"ACTIVE",
            "recurringFee":10.0000000000,
            "currency":"USD",
            "_entityType":"PlanSubscription"
         },
         "nextPlan":{  
            "planId":3,
            "planName":"Sample Fax Plan",
            "status":"ACTIVE",
            "recurringFee":10.0000000000,
            "currency":"USD",
            "_entityType":"PlanSubscription"
         },
         "_entityType":"ProductSubscription"
      }
   ],
   "_entityType":"Subscription"
}

Subscribe to Fax Numbers

Description

This is the core function for fax numbers. It allows you to subscribe to available fax numbers. Each subscription to a fax number has a monthly cost. If available, number credits may be used to pay for the fax numbers.

Request

  • URL: /api/v1/number-subscription-request
  • Method: POST
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER, ROLE_FINANCE_ADMIN, ROLE_PRODUCT_ACCESS

Request Body:

Name Required Type Description
productSubscriptionId X Long The account's product subscription ID for number plan (See Show Subscription)
numbers X List of Strings The list of numbers to subscribe to (See Show Available Numbers)

Sample Request Body:

{  
   "productSubscriptionId":"10",
   "numbers":[  
      "61290000001"
   ]
}

Response

Sample Response Body:

{  
   "id":4,
   "status":"PROCESSING",
   "numbers":[  
      {  
         "referenceId":"61290000001",
         "subscriptionId":10,
         "result":null,
         "error":null,
         "_entityType":"AddonSubscriptionAction"
      }
   ],
   "_entityType":"NumberSubscriptionUserRequest"
}

Show Number Subscription Request

Description

This function allows you to view the result of the fax number subscription request. Since subscription to the number is not synchronous, you can check the status and result of the request using this function.

Request

  • URL: /api/v1/number-subscription-request/{numberSubscriptionRequestId}
  • Method: POST
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER, ROLE_FINANCE_ADMIN, ROLE_PRODUCT_ACCESS

Request Parameters:

Name Required Type Description
numberSubscriptionRequestId X Long The ID of the number subscription request

Response

Sample Response Body:

{  
   "id":4,
   "status":"DONE",
   "numbers":[  
      {  
         "referenceId":"61290000001",
         "subscriptionId":10,
         "result":"SUCCESS",
         "error":null,
         "_entityType":"AddonSubscriptionAction"
      }
   ],
   "_entityType":"NumberSubscriptionUserRequest"
}

Number Subscription Request:

Name Type Description
id Long The ID of the number subscription request
status String The status of the subscription to the fax number; Possible Values: PROCESSING, DONE
numbers List of Addon Subscription Actions The result for the subscription to the fax number

Addon Subscription Action:

Name Type Description
referenceId String The fax number in the subscription request
result String The result of the subscription; Possible Values: SUCCESS, FAIL
error String The specific error for the subscription if the result is FAIL (See below for the list of possible errors)
subscriptionId Long The account's product subscription ID for number plan

Number Subscription Errors:

Error Name Description
NOT_FOUND The fax number is not valid
FAILED_RESERVATION The fax number is not available anymore. Other users could have subscribed to the same number.
RESERVATION_ERROR Other fax number/s included in the request is/are not available anymore.
INSUFFICIENT_FUNDS The account doesn't have enough credits to purchase the number.
CHARGING_ERROR There was a problem when trying to charge your account for the number. Try again or contact support if error still occurs.
SERVICE_CONNECTION_ERROR There was a problem with the connection when trying to subscribe to the number. Try again or contact support if error still occurs.

Show All Subscribed Numbers

Description

This function allows you to see the list of all the numbers subscribed for your account. A subscribed number may be active or inactive. A number is inactive if 1) the number has been unsubscribed or 2) account didn't have enough credits to renew the subscription for the number.

If the number is inactive, you will not be able to view new faxes received for that number. The inactive number is still reserved for your account within 30 days after it's been deactivated. This means it's guaranteed that you could still resubscribe to the number within 30 days. After that, the number is unlinked from your account and may not be available anymore.

Request

  • URL: /api/v1/number/team-number
  • Method: GET
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER

Request Parameters:

Name Required Type Description
offset Integer The starting index for the records to be fetched; Must be greater than -1; Default: 0
max Integer The maximum number of records to fetch; Must be greater than 0; Maximum: 100; Default: 100
status String Filter for the status of the number; Possible Values: ACTIVE, INACTIVE

Response

  • Status: 200 OK
  • Body: Paged Team Number (See Pagination)

Team Number:

Name Type Description
id Long The ID of the team fax number
teamId Long The account ID of the user
number String The fax number
numberArea Number Area The area of the fax number
status String The status of the fax number; Possible Values: ACTIVE, INACTIVE
inactiveReason String The reason why the number is inactive; Possible Values: UNSUBSCRIBED, INSUFFICIENT_FUNDS, UNABLE_TO_CALCULATE_COST, CHARGING_ERROR
dateActivated Date The date when the fax number was activated
dateDeactivated Date The date when the fax number was deactivated
forRenewal Boolean Indicates whether the number will be renewed next subscription period

Sample Response Body:

{
	"id": 1,
	"teamId": 5,
	"status": "ACTIVE",
	"inactiveReason": "",
	"dateActivated": "2018-07-17T12:08:17.808Z",
	"dateDeactivated": null,
	"forRenewal": true,
	"number": "61290000001",
        "numberArea":{
            "id":24,
            "name":"Sydney",
            "areaPrefix":"29",
            "areaGroup":null,
            "country":"Australia",
            "countryPrefix":"61",
            "_entityType":"NumberArea"
        },
	"_entityType": "TeamNumber"
}

Unsubscribe Fax Numbers

Description

This function allows you to unsubscribe from fax numbers. When you send a request to unsubscribe from a fax number, the number will be unsubscribed from your account next subscription period. This means that you can still use the fax number before your subscription is renewed.

Once a number has been unsubscribed from your account, you have 30 days until the number is revoked. During this time, you can still resubscribe to your number and there's no risk that other users have purchased that same number. After 30 days, the number will be revoked and there's no guarantee that you can subscribe to the number again.

Request

  • URL: /api/v1/number-subscription/{number}/unsubscribe
  • Method: POST
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER, ROLE_FINANCE_ADMIN, ROLE_PRODUCT_ACCESS

Request Parameters:

Name Required Type Description
number X String The active fax number to unsubscribe

Response

  • Status: 200 OK
  • Body: None

Unsubscribe Inactive Fax Numbers

Description

Aside from unsubscribing, there are other reasons for a fax number to be inactive. It might have been deactivated due to insufficient funds. This function allows you to unsubscribe from inactive numbers that were deactivated because of reasons other than unsubscribing.

Request

  • URL: /api/v1/number-subscription/{number}/unsubscribe-inactive
  • Method: POST
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER, ROLE_FINANCE_ADMIN, ROLE_PRODUCT_ACCESS

Request Parameters:

Name Required Type Description
number X String The inactive fax number to unsubscribe

Response

  • Status: 200 OK
  • Body: None

Show Fax Number Settings

Description

Once you are subscribed to a fax number, you can view and change the settings for the number. The settings contain the details for which user will be able to receive faxes received for that number. It also contains details for which user will be able to send a fax using that number as the TSI (This is for outgoing fax functionality). By default, the user that subscribed to the number is added as a recipient for the fax number.

This function allows you to view the settings for a fax number.

Request

  • URL: /api/v1/incoming-fax/number-settings/${number}
  • Method: GET
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER

Request Parameters:

Name Required Type Description
number X String The fax number

Response

Sample Response Body:

{  
   "senders":[],
   "recipients":[  
      {  
         "id":"4ju553hd-ffu3-sgtt-fie8-ffew9efkiw93",
         "emailAddress":"sample-user@sample.com",
         "firstName":"Sample",
         "lastName":"User",
         "username":"sampleuser",
         "_entityType":"UserSimplified"
      }
   ],
   "_uuid":"fb890a4a-fd07-49f7-bcad-c98c54b2c648",
   "_entityType":"IncomingFaxNumberSettings"
}

Update Fax Number Settings

Description

This function allows you to update the senders and recipients assigned to your numbers.

Request

  • URL: /api/v1/incoming-fax/number-settings/${number}
  • Method: POST
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER

Request Parameters:

Name Required Type Description
number X String The fax number

Request Body:

Name Required Type Description
receiverIds X List of UUIDs The list of user IDs to be set as recipients; The list must NOT be empty
senderIds X List of UUIDs The list of user IDs to be set as senders

Note: See "Show Active Users" to get the user IDs for your account.

Sample Request Body:

{  
   "receiverIds":[  
      "9dj3uuy4-fi33-tiwq-otk9-0od98shy31h2"
   ],
   "senderIds":[]
}

Response

Sample Response Body:

{  
   "senders":[],
   "recipients":[  
      {  
         "id":"9dj3uuy4-fi33-tiwq-otk9-0od98shy31h2",
         "emailAddress":"another-user@sample.com",
         "firstName":"Another",
         "lastName":"User",
         "username":"anotheruser",
         "_entityType":"UserSimplified"
      }
   ],
   "_uuid":"fuu8isk3-f9ee-04uj-f8u4-bhyyeuf83j7f",
   "_entityType":"IncomingFaxNumberSettings"
}

Fax Number Settings:

Name Type Description
recipients List of Users (Simplified) The users that are able to receive fax from the number
senders List of Users (Simplified) The users that are able to send fax using the number as TSI

User (Simplified):

Name Type Description
id UUID The ID of the user
emailAddress String The email address of the user
username String The username of the user
firstName String The first name of the user
lastName String The last name of the user

Show Active Users

Description

This function allows you to list all the active users for your account.

Request

  • URL: /api/v1/user/active
  • Method: GET
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER

Request Parameters:

Name Required Type Description
offset Integer The starting index for the records to be fetched; Must be greater than -1; Default: 0
max Integer The maximum number of records to fetch; Must be greater than 0;

Response

  • Status: 200 OK
  • Body: Paginated Users Object

Paginated Users:

Name Type Description
paginatedUsers List of Users The list of active users
totalUsers Integer The total number of users

User: NOTE: Some fields that are not relevant have been omitted.

Name Type Description
id Long The ID of the user
emailAddress String The email address of the user
username String The username of the user
firstName String The first name of the user
lastName String The last name of the user
roles List of Strings The list of Roles of the user
team Long The account ID of the user
dateCreated String The date when the user was created
confirmed Boolean Indicates whether the user has verified their email
lastSeen Date The date when the user was last logged in
lastActivity Date The date of the last activity of the user

Sample Response Body:

{  
   "paginatedUsers":[  
      {  
         "id":"4ju553hd-ffu3-sgtt-fie8-ffew9efkiw93",
         "username":"sampleuser",
         "emailAddress":"sample-user@sample.com",
         "status":"ACTIVE",
         "enabled":true,
         "lastActivity":"2018-06-23T12:37:00.219Z",
         "customFieldValues":[],
         "roles":[  
            "ROLE_WHITELABEL_ACCESS",
            "ROLE_TEAM_OWNER",
            "ROLE_TEAM_MANAGER",
            "ROLE_FINANCE_ADMIN",
            "ROLE_PRODUCT_ACCESS"
         ],
         "firstName":"Sample",
         "lastName":"User",
         "team":5,
         "teamStatus":"ACTIVE",
         "confirmed":true,
         "dateCreated":"2018-03-11T15:17:08.690Z",
         "lastSeen":"2018-06-23T12:37:00.219Z",
         "imageUrl":null,
         "_entityType":"User"
      }
   ],
   "totalUsers":1,
   "_entityType":"PaginatedTeamMembers",
   "_uuid":"9a1c4030-2860-4555-99a4-cb3bb26f9928"
}

Show Incoming Fax Inbox Message

Description

This function allows users to view all inbox messages received.

Request

  • URL: /api/v1/fax/internet/inbox-message
  • Method: GET
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER, ROLE_PRODUCT_ACCESS

Request Body:

Name Required Type Description
max Integer The max number of broadcasts to be retrieved.
offset Integer The start index of the list of fax broadcasts to be returned.
dateFrom String Date started in UTC (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')
dateTo String Date end in UTC (yyyy-MM-dd'T'HH:mm:ss.SSS'Z').

Response

  • Status: 200 OK
  • Body: Incoming Fax Message Object
Name Type Description
id String The id of the incoming fax inbox message.
teamFaxNumber String The sender's fax number.
status String The status of the incoming fax inbox message.
tsi String The status of the inbound fax message; Possible Values: RELAYED, ON_HOLD
cli String The customer calling line identification; This will help the receiver to identify the caller.
dateReceived String The date when the fax was received in our system.
pages Integer The number of pages of the fax document.
tiffPreview String A url of the tiff document.
pdfPreview String A url of the pdf document.
pngDocumentPreviews List A list of urls of the png documents per page.

Sample Response Body:

{
    "content": [
        {
            "id": "1",
            "teamFaxNumber": "61234567890",
            "status": "RELAYED",
            "tsi": "123456789",
            "cli": "61000000000",
            "dateReceived": "2017-10-10T10:13:19.000Z",
            "pages": 1,
            "tiffPreview": "https://d312345abcdef.cloudfront.net/000/fax/incoming/internet/a123/xxxx.tiff",
            "pdfPreview": "https://d312345abcdef.cloudfront.net/000/fax/incoming/internet/a123/xxxx.pdf",
            "pngDocumentPreviews": [
                "https://d312345abcdef.cloudfront.net/000/fax/incoming/internet/png-preview/b123/xxxx.png",
                "https://d312345abcdef.cloudfront.net/000/fax/incoming/internet/png-preview/b123/xxxx.png"
            ]
        }
    ],
    "totalElements": 1,
    "_uuid": "InternetFaxInboxMessages-uuid"
}

Delete Incoming Fax Inbox Message Document

Description

This function allows users to delete the document attached to the inbox message.

Request

  • URL: /api/v1/incoming-fax/${incomingFaxId}/document
  • Method: DELETE
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER, ROLE_PRODUCT_ACCESS

Request Body:

Name Required Type Description
incomingFaxId X String The id of the incoming fax message on which it's document will be deleted.

Response

  • Status: 204 NO CONTENT
  • Body: No response body

Update Incoming Fax Settings

Description

This function allows users to set incoming fax specific settings, like the file format of the fax document to be forwarded to the account.

By default, if not set, the value of the file format is PDF.

Request

  • URL: /api/v1/fax/incoming/internet/settings
  • Method: POST
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER, ROLE_PRODUCT_ACCESS

Request Body:

Name Required Type Description
fileFormat X String The file format of the document for the fax that will be forwarded to the account; Possible Values: PDF, TIFF, PNG

Sample Request Body:

{  
   "fileFormat":"PDF"
}

Response

  • Status: 200 OK
  • Body: Incoming Fax Settings Object

Incoming Fax Settings:

Name Type Description
fileFormat String The file format of the document for the fax that will be forwarded to the account; Possible Values: PDF, TIFF, PNG

Sample Response Body:

{  
   "fileFormat":"PDF",
   "_entityType":"IncomingInternetFaxSettings"
}

Update Incoming Fax Callback Settings

Description

This function allows you to enable callback for incoming fax and set a callback URL.

Please see below for more details about incoming fax callback.

Request

  • URL: /api/v1/incoming-fax-callback/settings
  • Method: POST
  • Allowed Roles: ROLE_TEAM_OWNER, ROLE_TEAM_MANAGER

Request Body:

Name Required Type Description
enabled X Boolean Indicates whether incoming fax callback is enabled for the account
callbackUrl String The callback url where requests will be posted

Sample Request Body:

{
    "callbackUrl": "https://callback.com",
    "enabled": true
}

Response

  • Status: 200 OK
  • Body: Callback Settings Object

Callback Settings:

Name Type Description
teamId Long The account ID of the user
callbackUrl Long The callback url where requests will be posted
enabled Boolean Indicates whether incoming fax callback is enabled for the account

Sample Response Body:

{
    "teamId": 5,
    "callbackUrl": "https://callback.com",
    "enabled": true,
    "_entityType": "CallbackSettings"
}

III. Incoming Fax Callback Service

Description

The incoming fax callback service allows our platform to post fax messages to you whenever a fax is received for any of your fax numbers.

To take advantage of this, you are required to write a simple web service to accept requests from our system, parse them and process them accordingly. See below about the details for the request we send.

Once you have deployed the web service, you can configure the callback settings for your account. Please see the "Update Incoming Fax Callback Settings" function.

Request

Request Details

  • Method: POST
  • Request Body:
Name Type Description
messageRef Long The inbound fax message reference; The unique identifier for the fax messages sent.
faxNumber List of Strings The sender's fax number
status String The status of the inbound fax message; Possible Values: RELAYED, ON_HOLD
pages Integer The number of pages of the fax document
tsi String The transmitting subscriber identification, used to identify the sender of the fax
cli String The customer calling line identification; This will help the receiver to identify the caller
dateReceived Date The date when the fax was received in our system
tiffDocumentUrl String A url of the tiff document that will expire after 24 hours

Sample Request Body

{
  "messageRef": "1987665543",
  "faxNumber": "12345677",
  "status": "RELAYED",
  "pages": 2,
  "tsi": "tsi1234",
  "cli": "cli1234",
  "dateReceived": "2019-06-13T13:32:33.000Z",
  "tiffDocumentUrl": "http://testtoken.cloudfront.net/test/info/file/4c19aca717d3?Expires=1559033055&Signature"
}

IV. More Information

Pagination

Details

Some of the JSON response from our platform may be paginated. Here is the format for paginated responses:

Name Type Description
content List of Objects The list of objects
totalElements Integer The total number of records

Sample Paginated Response

{  
   "id":"0d598b60-52b1-4787-879d-0a501b8b60ff",
   "content":[  
      {  
         "id":1,
         "teamId":5,
         "status":"ACTIVE",
         "inactiveReason":"",
         "dateActivated":"2018-07-17T12:08:17.808Z",
         "dateDeactivated":null,
         "forRenewal":true,
         "number":"61290000001",
         "numberArea":{  
            "id":24,
            "name":"Sydney",
            "areaPrefix":"29",
            "areaGroup":null,
            "country":"Australia",
            "countryPrefix":"61",
            "_entityType":"NumberArea"
         },
         "_entityType":"TeamNumber"
      },
      {  
         "id":2,
         "teamId":5,
         "status":"INACTIVE",
         "inactiveReason":"UNSUBSCRIBED",
         "dateActivated":"2018-07-17T12:08:17.808Z",
         "dateDeactivated":"2018-08-17T16:00:00.000Z",
         "forRenewal":false,
         "number":"61290000002",
         "numberArea":{  
            "id":24,
            "name":"Sydney",
            "areaPrefix":"29",
            "areaGroup":null,
            "country":"Australia",
            "countryPrefix":"61",
            "_entityType":"NumberArea"
         },
         "_entityType":"TeamNumber"
      }
   ],
   "totalElements":2,
   "_entityType":"PageTeamNumber"
}

Data Format

Dates

Dates are always passed in ISO-8601 format with UTC Timezone. For example: 2019-06-13T16:25:32.000Z

Add a custom footer

Outgoing Fax SOAP API

API Access and General Usage

Function Definitions

Outbound Callback Service

More Information

API Examples

Incoming Fax REST API

API Access and General Usage

Function Definitions

Incoming Fax Callback Service

More Information

Clone this wiki locally