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!
Enterprise Faxing has never been easier. Our quick start documentation will have you faxing in no time.
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!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.
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 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.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"
}
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"'
{
"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
}
]
}
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.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"
}
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).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.
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.
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
}
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.
