ANI and CSID Decoded and why it’s important.

,

The ANI is Automatic Number Identification. It is used by the phone carriers to determine the originating fax or telephone number for any call. ANI is different, conceptually and technically, from caller ID service. A caller’s telephone number and line type are captured by ANI service even if caller ID blocking is activated.

When you set your ANI in an API call please set the number to your fax number with no spaces or punctuation.

Example: 3335551212

If you set it to an invalid number, the receiver may block it as invalid or spam. If you are testing your API, and you can’t get the receiving fax line to accept the call, it could be because their carrier is blocking invalid ANI.

CSID is Called Subscriber Identification (abbreviated CSID), and is a fax number that identifies the specific fax machine sending the fax. A CSID is not required in all cases, but it is a good practice to set so that your fax machine will not get blocked for being spam or unknown.

In some cases, one would want to set the CSID to another number if you want to have the receiver send responses to another number. Think of it as a REPLY TO field on email.  If one has many outbound fax lines, but one wants people to fax back to a specific return fax number, one could set the CSID to the primary inbound line so it appears the fax came from that number.

CSID is a string that identifies a sending fax machine.  This data is transmitted as part of the fax protocol when the fax transmission is negotiated.  This identifier can contain numbers, letters and punctuation.  Often it will contain the sending fax number along with a company name.  “Acme Inc.  (303) 555-1212” for instance.  Again this is part of the fax protocol and is completely separate from ANI.

In summary, when sending faxes with the API it is important to set these values correctly and not just mash numbers in or use placeholders. Many failed test faxes fail because of invalid ANIs.

API How-to: Save your fax document from a BASE64 object to a pdf

This article assumes the following:

Sending a fax is easy as you may have already discovered, but what about retrieving a fax document for an inbound fax?

In this article we’ll detail the process for converting your inbound faxes into actual documents.

Step 1: Get a list of inbound faxes

We are going to call Fax_GetFaxIdentifiers to grab an inbound fax we want to save.

It requires the Username/Password/ProdID as well as a StartDate and FaxDirection. We’ll set the StartDate to ‘1/1/2020’ and the FaxDirection to ‘Inbound’. This will get us all inbound faxes that came in after 1/1/2020.

If you have any inbound faxes, you’ll see something like this:

{
  "Success": true,
  "Result": [
    {
      "Id": "00000000-0ebd-47d8-9afc-000000000fcf",
      "Direction": "Inbound",
      "Date": "2020-03-12T15:28:03Z",
      "Tag": "None"
    },
    {
      "Id": "0000000-8360-4083-be78-c70000008570",
      "Direction": "Inbound",
      "Date": "2020-03-12T15:13:35Z",
      "Tag": "None"
    }
  ]
}

We see two results are returned. Each has an Id, Direction, Date timestamp and a Tag. We are interested in the Id field.

Step 2: Retrieving the Fax data using the Id.

In order to retrieve the actual fax document we need to take that Id, and pass it to Fax_GetFaxDocuments.

The Fax_GetFaxDocuments call requires the standard authentication and two additional parameters:  FaxIds1 and Format. The FaxIds1 field requires an Id from the previous call, which identifies the fax document you want to download. The Format field should be one of the following [pdf, tiff, jpeg, png, gif]. We will use pdf.

Side note: The FaxIds1 field is for the first Fax. You can specify several FaxIds fields. So if you had 4 faxes you would populate FaxIds1, FaxIds2, FaxIds3, FaxIds4. You can retrieve multiple fax documents at the same time to save calls to the API.

After you call Fax_GetFaxDocuments, you will see a response similar to this:

{
    "Success": true,
    "Result": [
        {
            "FaxFiles": [
                {
                    "ContentType": "application/pdf",
                    "ContentLength": 55344,
                    "FileContents": "JVBERi0xLjINCg0KNCAwIG9iag0KPDwNCi9FIDU1MDA5DQovSCBbIDk2MyAxMzkgXQ0KL0wgNTUzNDQNCi9MaW5lYXJpemVkIDENCi9OIDENCi9PIDcNCi9UIDU1MjE0DQo+PiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgDQplbmRvYmoNCg0KeHJlZg0KNCA2DQowMDAwMDAwMDEyIDAwMDAwIG4NCjAwMDAwMDA4NjkgMDAwMDAgbg0KMDAwMDAwMDk2MyAwMDAwMCBuDQowMDAwMDAxMTAzIDAwMDAwIG4NCjAwMDAwMDEzMDk...<truncate for this article>"
                }
            ],
            "Id": "0000000-7722-42d9-b55f-00000000000",
            "Direction": "Outbound",
            "Date": "2020-03-12T15:28:42Z",
            "Status": "Ok",
            "Format": "pdf",
            "PageCount": 1
        }
    ]
}

Let’s examine this result in detail.  First we have the Format which is PDF. The ContentLength is also important as it gives you an indication of the size of the document. In this case it looks like a small one page document at 55,344 bytes. Now we want to proceed with decoding this document, so the important field here is the FileContents.

FileContents is base64 encoded so it returns a very long string of random-looking characters. You can read more about base64 encoding here.

In almost every programming language there are built in functions to take base64 encoded data and decode it into a usable document.

Below are a few examples.

PHP:

<?php
$str = 'SGVsbG8gV29ybGQg8J+Yig==';
echo base64_decode($str);

//Outputs "Hello World"

?>

Here is the PHPfiddle to try on your own.

 

Here is a Python example (python 3+):

# Fax Base64 data

fax_data = b'iVBORw0KGgoAAAANSUhEUgAABoIAAAaCCAYAAAABZu+EAAAqOElEQVR42uzBAQEAAACAkP6v7ggK\nAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\nAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\nAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIcAeHkAAeLqlDIAAAAASUVORK5CYII='

# For both Python 2.7 and Python 3.x
import base64
with open("faxdoc.pdf", "wb") as fh:
    fh.write(base64.decodebytes(img_data))

Examples for C#.NET:

# C# is the easiest of all. One line of code!
File.WriteAllBytes(@"c:\directory\yourfile.pdf", Convert.FromBase64String(yourBase64String));

So as one can see, converting to a usable file from base64 data is relatively simple and easy to implement. Please contact us if you have any questions.

Will FAX ever die?

In 2014 WestFax celebrated the 50th anniversary of the fax machine. In 1964 at the height of the British pop invasion while America was still reeling from the Kennedy assassination, Xerox invented the modern office fax machine. While this office equipment staple has lost much respect over the past several years, it still remains essential to most businesses. Particularly businesses that require secure document transport to maintain HIPAA compliance. Marketing departments in every industry are also rediscovering the power of fax advertising to avoid spam filters and present a unified communication approach to reinforce their digital marketing efforts.

Most faxes today are received via e-mail. Dozens of service providers including WestFax offer an inexpensive easy to use electronic fax option to enable businesses to cut the phone cord and send and receive faxes via their e-mail account or mobile device. The WestFax service is $8.99 per month for individual users with lower cost options for multiple fax lines.

With a continued focus on patient confidentiality via HIPAA and the major marketing benefits large volume fax broadcasting offers, the fax mode of communication remains an essential business tool for years to come.

Barry Clark

Barry Clart