ENTERPRISE FAX API

Enterprise Faxing has never been easier. Our quick start documentation will have you faxing in no time.

INTEGRATE TODAY!

Getting started with the fax API

It's easy to get started. Just register as a developer, we'll get you credentials and just one look at our intuitive and interactive API documentation will have you sending fax in less than an hour!

GET STARTED!
curl request

How-To Guides

These are a collection of How-To’s on getting yourself up and running using WestFax’s Secure Fax API. If you have any ideas for other articles or questions email us here.

GitHub Logo
Postman Logo

How to get started with the Fax API

Getting started requires knowledge of a programming language that is able to execute RESTful webservices and must support TLS 1.2+ for connections. We have provided several places to test your code. You can utilize the Postman platform or you can utilize SwaggerHub to execute code in the browser.
Caution: Do not use production credentials on a web-based documentation platform.

Let's get pinging!

Let's get started by doing a quick command to test that you are able to connect to the api. We are going to call the heartbeat service that we call Security_Ping. This call will essentially send you back a response of "pong" with your "ping" parameter. This ensures you can connect to our platform.

To Call this function just copy and paste this into a command prompt and hit enter:

curl -L -X POST 'https://api2.westfax.com/REST/Security_Ping/json' -F 'StringParams1="ping "'

The result should be:

{"Success":true,"Result":"Pong - ping "}
If you got something else please submit a helpdesk ticket to info@westfax.com with the contents of your error.

Authentication

You should have a username and password for your account. Your username is usually the email address. There are a few API calls here you can use to authenticate. Some just verify your access. Some return some meta-data about your fax line.

Let's verify you can log in. We are going to stick with Curl requests for this demonstration as they require nothing other than a command prompt. If you don't have Curl you should check it out here.

The first command is Security_Authenticate. It accepts Username, Password, Cookies. You can replace the placeholder text below with your login information and hit enter. Cookies will just be set to false.

curl -L -X POST 'https://api2.westfax.com/REST/Security_Authenticate/json' -F 'Username="username"' -F 'Password="password>"' -F 'Cookies="false"'

The result will look something like this:

                {
                "Success": true,
                "Result": "FFSKEV56GLMQUZKFM6EEPIBCZ7Y"
                }
        

You will see success = true or a success = false if your information is incorrect.

The next command will autheticate and return a list of available fax numbers you have on your account. You may have access to one or many numbers depending on your configuration.

This command is called Profile_GetF2EProductList. This command will authenticate your account information and return a json (or XML) array of the fax line(s) you have access to. In most cases it'll just be the line you signed up with. Here is the call and the output:

curl -L -X POST 'https://api2.westfax.com/REST/Profile_GetF2EProductList/json' -F 'Username="username"' -F 'Password="password"' -F 'Cookies="false"'

And the result should be something like this (data has been randomized):

            {
                "Success": true,
                "Result": [
                    {
                        "Id": "00000000-fds4-4551-9bda-0000000000",
                        "Name": "FF-SSO-TEST",
                        "PlanId": "00000000-5042-4f3a-b368-0000000000",
                        "ProductType": "FaxForward",
                        "InboundNumber": "5552223333",
                        "TimeZone": "Pacific",
                        "ProductState": "OK",
                        "CurrentBillingPeriodStart": "2022-04-01T00:00:00Z",
                        "CurrentBillingPeriodEnd": "2022-05-01T00:00:00Z",
                        "FreeTrialEnd": "2020-07-29T23:59:59Z",
                        "PeriodicQuantity": 0,
                        "QuantityInbound": 21,
                        "QuantityOutbound": 4939
                    }
                ]
            }
        

You can see there is a lot more data here. You can see the fax number in the InboundNumber field, the Billing period and the Quantity of Inbound and Outbound faxes on this account. If you had multiple fax numbers you'd see more listed here in an array. The fields you want to save here for later use are Id and InboundNumber. We will use those in different calls.

Let's see if we have a fax!

The Id field above that you saved is going to be used as the unique identifier for your fax line. We call it ProductId in a lot of our examples going forward. In this example we are going to call Fax_GetFaxIdentifiers. This call accepts Username, Password, ProductId (Id from above), a Date to start looking from and a Fax Direction (Inbound or Outbound).

Here is a call below. Again, replace this information with your values to get a real response.

curl -L -X POST 'https://api2.westfax.com/REST/Fax_GetFaxIdentifiers/json' -F 'Username="Username"' -F 'Password="Password"' -F 'ProductId="00000000-fds4-4551-9bda-0000000000"' -F 'StartDate="1/1/2022"' -F 'FaxDirection="Inbound"'

At this point you probably only have one fax in your inbox. The one you recieved when you signed up. If you have no faxes go send yourself a fax.

Here is what you should get:

            "Success": true,
            "Result": [
                {
                    "Id": "11111111-fe13-47b2-9db7-22222222222",
                    "Direction": "Inbound",
                    "Date": "2022-03-04T06:02:33Z",
                    "Tag": "None"
                }
        

This data represents a fax document. The Id will be used later to download the fax document in BASE64. The Direction tells you that it's inbound and the Date gives you an indication of of when the fax arrived (Time is in UTC). The Tag field can be (None, Retrieved, Removed) which means (Unread, Read, Deleted).

Let's download your fax!

Now that we have a fax document we can go ahead and download it and we'll mark it as read. The first step is downloading the fax and then we'll go and mark it as read (you can skip the second step if you don't care if it is marked as read). You can also mark the fax for deletion too if you wanted.

Downloading your fax

The command to download a fax is Fax_GetFaxDocuments. This call accepts a few parameters. Your standard authentication parameters Username, Password, ProductId (or Id from the Profile_GetF2EProductList call. This is the unique identifier for the Fax number. Now you need to use the Id of the fax you got from Fax_GetFaxIdentifiers. In this call we use FaxIds1 where you have to pass in a nested json object (see example below). The Format field can be pdf or tiff. In the

Here is the call:

curl -L -X POST 'https://api2.westfax.com/REST/Fax_GetFaxDocuments/json' -F 'Username="username"' -F 'Password="password"' -F 'Cookies="false"' -F 'ProductId="00000000-fds4-4551-9bda-0000000000"' -F 'FaxIds1="{\"Id\":\"11111111-fe13-47b2-9db7-22222222222\",\"Direction\":\"Inbound\"}"' -F 'Format="pdf"'

The result will be look similar to this: (truncated for length).

            {
            "Success": true,
            "Result": [
                {
                    "FaxFiles": [
                        {
                            "ContentType": "application/pdf",
                            "ContentLength": 2862,
                            "FileContents": "JVBERi0xLjQKJdP0zOEKJSBQREZ....truncated"
                                            }
                                ],
                            "Id": "11111111-fe13-47b2-9db7-22222222222",
                            "Direction": "Inbound",
                            "Date": "2022-04-01T23:10:29Z",
                            "Status": "Ok",
                            "Format": "pdf",
                            "PageCount": 1
                        }
                    ]
                }
            }

        

The FileContents field is in BASE64 encoded format. There are plenty of ways to decode a BASE64 document. If you want to test it just go to this site and copy and paste your FileContents data (between the quotes) and let it convert to a pdf for you.

Mark your fax as read (or delete).

Now let's mark the fax as read so users know it's downloaded. The call we will use is Fax_ChangeFaxFilterValue. The call is very similar to the call above. Your standard authentication parameters Username, Password, ProductId (or Id from the Profile_GetF2EProductList call. This is the unique identifier for the Fax number. Now you need to use the Id of the fax you got from Fax_GetFaxIdentifiers. In this call we use FaxIds1 where you have to pass in a nested json object (see example below). The Filter field can be Retrieved (mark as read) or Removed (Marked for deletion).

Here is the call:

curl -L -X POST 'https://api2.westfax.com/REST/Fax_ChangeFaxFilterValue/json' -F 'Username="username"' -F 'Password="password"' -F 'Cookies="false"' -F 'ProductId="00000000-fds4-4551-9bda-0000000000"' -F 'FaxIds1="{\"Id\":\"11111111-fe13-47b2-9db7-22222222222\"}"' -F 'Filter="Retrieved"'

The result should be:

                {
                    "Success": true,
                    "Result": true
                }
            

In conclusion

You can see here that utilizing our powerful fax api is very straightforward and the calls are all clearly documented in the Postman tool or the SwaggerHub site. If you have any issues or questions please reach out to us.

HIPAA Compliant