Faxpipe/Aircom Outbound Fax Submission API Details

V2.01
Abstract
This document describes the process of submitting an outbound fax for processing and delivery.

Legal Notices
The information contained herein is subject to change without notice and is not warranted to
be error-free. If errors are found, please report them to us in writing.
AirComUSA and Faxpipe are registered trademarks of AirCom LLC (AirCom), and shall not be
used without AirCom's express written authorization.
Use of this documentation is subject to the following terms: You may create a printed copy of
this documentation solely for your own personal use. Conversion to other formats is allowed as
long as the actual content is not altered or edited in any way. You shall not publish or distribute
this documentation in any form or on any media, except if you distribute the documentation in
a manner similar to how AirCom and Faxpipe disseminate it. Any other use, such as any
dissemination of printed copies or use of this documentation, in whole or in part, in another
publication, requires the prior written consent from an authorized representative of AirCom.
AirCom reserves any and all rights to this documentation not expressly granted above.

This document refers to version 2.01 of the outbound api.

Key Issuance:

Each account can be issued an api-key associated with the accountid. Both will be used for use in
verifying account-status and sending outbound faxes. This key is not issued by default in for accounts in
the retail channel. Customers can make a request to support@faxpipe.com for an account key.

Authentication:
These calls use HMAC authorization. An authorization token is generated as SHA256HMAC(api-key,
json-encoded-payload)

Once the value is calculated, then you POST the json payload, your accountid , and the calculated
authorization token

SHA256-HMAC Calculation / Authorization Header creation:

Key Expiry:
Individual accounts each have their own non-expiring api-key. The key will continue to work, but show
‘account inactive’ on a closed or suspended account. Individual keys can be reissued as needed by
contacting support@faxpipe.com.
Sending a fax:
https://www.faxpipe.com/api/sendfax-auth

INPUTS formatted in json

accountid – the customer’s accountid
fromadd – the sending email address we will send status responses to
subject – arbitrary text for the user to identify the email
list(faxnum(s)) – the faxnumber(s) to deliver to – 10 digits each
list(files) the base64-encoded files with filename

json-payload ={
"accountid": "00000",
"fromadd": "user@example.com",
"subject": "Sample Fax Subject",
"files": {"f1.txt": "b25lIAp0d28KdGhyZWUKZm91cgpBQUFBQQo=",
"f2.pdf": "JV……”}
"faxnums": ["5551234567",”……”]}
}

Auth-token = SHA256HMAC(api-key, json-payload)

account = copy of customer account id – for retail accounts identical
to above account id
Then you post to https://faxpipe.com/api/sendfax-auth with 3 form
elements:

json-payload -> apidata

auth-token -> authorization
accountid -> accountid

RESPONSE
Json-payload = { “response”:”<faxid>”}

Json-payload = { “error”: “an-error-message”}

All calls with valid inputs to sendfax-auth will attempt to send a

fax. Those that pass authorization check will automatically pass
outbound fax validation. Those that do not automatically pass will go
through fall-back authorization checks (e.g. valid fromadd). You can
submit a blank authorization and (outer) accountid if you wish to send
using fall-back authorization.

It is recommended that you allow the user to configure the api-key,

the from-add and the account id. For FC-referred customers, they will
authenticate and will pass authorization automatically, for non-fc-
refered customers, they will get normal ‘fromadd’ authentication based
on the account id and the from address given.
Finding Account Status
https://www.faxpipe.com/api/accountstatus-auth
INPUTS formmated in json
accountid: customer account id(e.g. 00000)

json-payload ={
"accountid": "00000",
}

Auth-token = SHA256HMAC(api-key, json-payload)

accountid = the accountid

Then you post to https://faxpipe.com/api/accountstatus-auth with 3

form elements:

json-payload -> apidata

auth-token -> authorization
account -> account (for retail accounts, identical to the payload-
accountid)

RESPONSE
Json-payload =
{
"accountid":<type – see below>,
"datecreated":"unix-timestamp”,
}

{“response”: json-payload}

type: (0=unknown, 1=closed, 2=trial, 3=paid )

datecreated: unix timestamp of creation time

This call will respond with 1/2/3 for all accounts made with your reseller ID. For accounts that fail to
authenticate, or for any unexpected error conditions, we will return 0 as a generic error condition.