Fax REST API Quick Start Guide

Ramv_OT
Ramv_OT E Community Moderator
edited October 28, 2021 in Articles #1

Faxing remains a universal method of secure document delivery with billions of faxes sent every year. While it’s the foundation of secure communications for healthcare, government, manufacturing and other industries, traditional faxing has limitations, such as maintaining fax hardware, telephony infrastructure, lack of security etc.

OpenText provides a REST API to automate faxing from your backend applications that will reduce costs and securely track faxes, both inbound and outbound. For example, healthcare applications can be integrated with cloud fax to send and receive patient referrals, insurance claims, and prescriptions. Outside healthcare, another common example is trading applications requiring sending trade confirmations via fax to clients.

This article describes how to use the OpenText Messaging Fax REST API to submit a request to send a fax, check fax status and receive faxes.

Step 1:

Get a Fax2Mail test account and credentials from your sales engineer contact.

Step 2:

API authentication. One can use HTTP Basic authentication or OAUTH 2.0 (tentative availability date is October 2021). Basic authentication requires username and password. Examples in this article use basic authentication.

Step 3:

Following is an example of curl command to submit a request to send a fax with a text file.

curl -H "Content-Type: application/json" \
     -u <userid:password> \ 
     --data-binary "{
    \"destinations\": [
        {
            \"fax\": \"9999999999\"
        }
    ],
    \"documents\": [
        {
            \"name\": \"temp.txt\",
            \"type\": \"text\",
            \"data\": \"SGkgVGhlcmUsIFRoaXMgaXMgYSB0ZXN0IERvY3VtZW50Lg==\"
        }
    ]
}"  \
https://t2api.us.cloudmessaging.opentext.com/mra/v1/outbound/faxes 

Successful submission of requests will result in HTTP 200 response code along with a job id. Here is a sample response:

{
    "job_id": "xsi-1111111111"
}

Step 4:

Check the status of fax send requests. Status can be checked either by status API or webhook. Webhook is highly recommended. Fax status schema is the same for both webhook and API. For this example, we will provide a curl sample for checking status via status API.

curl -u <userid:password> \

'https://t2api.us.cloudmessaging.opentext.com/mra/v1/outbound/faxes/status?job_id=xsi-1111111111'

Successful submission of status API call will result in HTTP 200 response code along with a detailed JSON status as below. Job state and delivery attempt state confirm that the fax is indeed sent successfully to the destination. 

{
    "job_id": "xsi-1111111111",
    "entry_time": "2020-05-08T03:35:05.000Z",
    "job_state": [
        "Complete",
        "Posted"
    ],
    "deliveries": [
        {
            "fax": "1234567890",
            "delivery_attempts": [
                {
                    "state": "Sent",
                    "first_attempt": "2020-05-08T03:35:07.000Z",
                    "delivery_time": "2020-05-08T03:35:34.000Z",
                    "delivery_sec": 8,
                    "pages_delivered": 1,
                    "baud_rate": 31200,
                    "rcsid": "011919164813456"
                }
            ]
        }
    ]
}

Next, we will describe how to retrieve fax documents received to your fax number using the API. Note that fax documents can be delivered using webhook which is highly recommended. Schema is the same for both webhook and status API response.

Here is a sample curl command to retrieve fax document.

curl -u <userid:password> \ 'https://t2api.us.cloudmessaging.opentext.com/mra/v1/inbound/documents/next'

Successful document retrieve request will result in HTTP 200 response code along with detailed JSON description of received fax as below.

{
    "doc_id": "eHNpcWEzfTh8MjM4f2MC0xMDQ5NDg3",
    "document_class": "Inbound Fax",
    "job_id": "xsi-2222222222",
    "user_id": "your id",
    "customer_reference_base64": "Y3VzdF9yZWZfZjJt",
    "billing_code_base64": "YmNfdGVzdF9h",
    "transaction_info": {
        "fax_mode": "STANDARD",
        "tsid": "011919164813456     ",
        "ani": "1234567890",
        "dnis": "1234567890",
        "call_date": "2020-05-08T03:48:22.000Z",
        "connect_time": 8,
        "baud_rate": 31200,
        "page_count": 1,
        "internal_fax_id": "fax1-005000421-20200507"
    },
    "document": {
        "type": "PDF",
        "name_base64": "ZmF4LTyMC0yMzQ4LnBkZg==",
        "data": "JVBERi0xLjIGyZWYKMTE2MAolJUVPRgo="
    }
}

Successful document retrieve should be followed by document delete to delete documents. Here is a sample curl command to delete documents which will result in HTTP response code of 204.

curl -X DELETE \ 
     -u <userid:password> \
'https://t2api.us.cloudmessaging.opentext.com/mra/v1/inbound/documents/eHNpcWEzfDIwMDQ0NDcyMTh8MjM4fHFkb2MtcHVsbC0xMDQ5NDg3'

 Detailed documentation on the Fax REST API is available at

https://developer.opentext.com/apis/99b857ce-b749-4061-bc63-8a077e3a0818/Cloud%20Fax

@Akash Venugopal contributed to this post.

Tagged:

Comments

Categories