API

VFAX Status Query API

Version 3

Please contact Axion tech support to get api url and credentials

User Authentication

Before being able to query the API, user authentication must be completed using an API key, a username and a password. If correct authentication is completed, API will include in response a unique SESSION_TOKEN that must be used in every subsequent query.
The session token is valid for 30 days. User authentication could be done at any time without waiting for token expiration, in which case a new token will be generated.

API key is provided to customer.
Username and password are the vfax web credentials (the ones used in https://cp.hivepbx.com).

API accepts only POST method requests and all variables must be sent in JSON format. API sends responses in JSON format as well.

In order to complete authentication, client must send a POST request to API URL all variables encoded in JSON format.

API Method to Authenticate User

JSON Request

 

METHOD

User_Login

API_KEY

The provided API key (never changes)

USERNAME

Username used in web

PASSWORD

Password used in web

example JSON POST request: {“API_KEY”:”3d51aab5ddb453c4c9ed6c31936f17a930aab5e68ecb5ba6ef45837f45b193f6″,”METHOD”:”Us er_Login”,”USERNAME”:”john_doe”,”PASSWORD”:”my_secret_pass”}

example successful JSON response: {“RESULT”:”OK”,”SESSION_TOKEN”:”eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MTA5NTU3 ODksImF1ZCI6ImJiMGJmMjI4YmU3MWZiOWRkZmNlYjY5NzM4NmI2MmZhYjEwNzNmYzciLCJkYXRhIjp7In VzZXJfdW5pcXVlX2lkIjoiMTgzNDc3IiwidXNlcl9sZXZlbCI6bnVsbCwiZnVsbF9uYW1lIjoiSnVhbiBNb3JyYSJ9f Q.ybky_Zp17Fjqm0qnk9bKVbwPuPLTQfzkjuUuIkqHK0s”}

JSON Successful Response

 

RESULT

OK / ERROR

SESSION_TOKEN

A Temporary Session token to be used in subsequent api calls

API Method to Fetch Fax Data

JSON Request

 

METHOD

Fax_Status

API_KEY

The provided API key (never changes)

SESSION_TOKEN

A valid session token obtained from User_Login method call

CUSTOMER_PROVIDED_FAX_FIELD

The customer provided data field as sent in fax submission request

Example JSON POST request: {“API_KEY”:”3d51aab5ddbdd3c4c9ed6c31936f17a930aab5e68ecb5ba6ef45837f45b193f6″,”METHOD”:”Fa x_Status”,”SESSION_TOKEN”:”eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MTM1NTA3MTMsI mRhdGEiOnsidXNlcl91bmlxdWVfaWQiOiIxODM0NzciLCJ1c2VyX2xldmVsIjoiNTEiLCJmdWxsX25hbWUiOiJ KdWFuIE1vcnJhIiwiYWNjb3VudG51bWJlciI6IjE5MzEyMzk2OTQzMCJ9fQ.RiBAvO6fXYXG5UUpM0BV_ETJX NJzfSL5Gh1AOlnCy_M”,”CUSTOMER_PROVIDED_FAX_FIELD”:”test 1″}

JSON Succesful Response

   

RESULT

Can be OK (if matching faxes found) or ERROR

CUSTOMER_PROVIDED_FAX_FIEL D

The customer provided data field as sent in fax submission request

FAXES

An Array of faxes that matches the search field

SOURCE_NUMBER

Origination fax number

DESTINATION_NUMBER

Destination fax number

TIME

Timestamp

PAGES

Number of fax pages

STATUS

QUEUED / PROGRESS / SENT / FAILED

 

TRY_COUNT

Retry counter (0 -3)

Example JSON Response (2 faxes match the data field): {“RESULT”:”OK”,”CUSTOMER_PROVIDED_FAX_FIELD”:”test 1″,”FAXES”: [{“SOURCE_NUMBER”:”18056421414″,”DESTINATION_NUMBER”:”18002255288″,”TIME”:”2016-12-12 12:43:59″,”PAGES”:”2″,”STATUS”:”SENT”,”TRY_COUNT”:”1″}, {“SOURCE_NUMBER”:”18056421415″,”DESTINATION_NUMBER”:”18002255211″,”TIME”:”2016-12-12 12:44:38″,”PAGES”:”2″,”STATUS”:”SENT”,”TRY_COUNT”:”3″}]}

API Method to Fetch ALL Faxes Data

JSON Request

 

METHOD

All_Faxes_Status

API_KEY

The provided API key (never changes)

JSON Request

 

SESSION_TOKEN

A valid session token obtained from User_Login method call

DATE

The date in format YYYY-MM-DD

Example JSON POST request: {“API_KEY”:”3d51aab5ddbdd3c4c9ed6c31936f17a930aab5e68ecb5ba6ef45837f45b193f6″,”METHOD”:”Fa x_Status”,”SESSION_TOKEN”:”eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MTM1NTA3MTMsI mRhdGEiOnsidXNlcl91bmlxdWVfaWQiOiIxODM0NzciLCJ1c2VyX2xldmVsIjoiNTEiLCJmdWxsX25hbWUiOiJ KdWFuIE1vcnJhIiwiYWNjb3VudG51bWJlciI6IjE5MzEyMzk2OTQzMCJ9fQ.RiBAvO6fXYXG5UUpM0BV_ETJX NJzfSL5Gh1AOlnCy_M”,”DATE”:”2017-11-29″}

JSON Succesful Response

 

RESULT

Can be OK (if matching faxes found) or ERROR

DATE

The Date as sent in fax submission request

FAXES

An Array of faxes that matches the search field

CUSTOMER_PROVIDED_FAX_FIELD

The Customer provided data field when fax was sent

SOURCE_NUMBER

Origination fax number

DESTINATION_NUMBER

Destination fax number

TIME

Timestamp

PAGES

Number of fax pages

STATUS

QUEUED / PROGRESS / SENT / FAILED

 

TRY_COUNT

Retry counter (0 -3)

Example JSON Response (4 faxes match the data field): {“RESULT”:”OK”,”DATE”:”2017-11-29″,”FAXES”:[{“CUSTOMER_PROVIDED_FAX_FIELD”:”test 1″,”SOURCE_NUMBER”:”18059731214″,”DESTINATION_NUMBER”:”18058522606″,”TIME”:”2017-11-29 12:43:59″,”PAGES”:”2″,”STATUS”:”SENT”,”TRY_COUNT”:”1″}, {“CUSTOMER_PROVIDED_FAX_FIELD”:”test 1″,”SOURCE_NUMBER”:”18059731214″,”DESTINATION_NUMBER”:”18058522606″,”TIME”:”2017-11-29 12:44:38″,”PAGES”:”2″,”STATUS”:”SENT”,”TRY_COUNT”:”1″}, {“CUSTOMER_PROVIDED_FAX_FIELD”:null,”SOURCE_NUMBER”:”13103560491″,”DESTINATION_NUMBE R”:”1234″,”TIME”:”2017-11-29 13:36:42″,”PAGES”:”2″,”STATUS”:”FAILED”,”TRY_COUNT”:”1″}, {“CUSTOMER_PROVIDED_FAX_FIELD”:”test 2″,”SOURCE_NUMBER”:”18059731214″,”DESTINATION_NUMBER”:”18058522606″,”TIME”:”2017-11-29 12:45:27″,”PAGES”:”2″,”STATUS”:”SENT”,”TRY_COUNT”:”1″}]}

API Method to Fetch a Group of Faxes Data

JSON Request

 

METHOD

Fax_Group_Status

API_KEY

The provided API key (never changes)

JSON Request

 

SESSION_TOKEN

A valid session token obtained from User_Login method call

CUSTOMER_PROVIDED_FAX_FIELDS

an array of customer provided data values

Example JSON POST request: {“SESSION_TOKEN”:”eyJ0eXAiOiJCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE1MjA3MDI5MDcsImRhdGEiOnsidXNl cl91bmlxdWVfaWQiOiIxMDAwMDEiLCJ1c2VyX2xldmVsIjoiNTEiLCJmdWxsX25hbWUiOiJKdWFuIE1vcnJhIi wiYWNjb3VudG51bWJlciI6IjE5MzEyMzk2OTQzMCJ9fQ.0ObSNkQf_l2a5f6rPt_kdGKYIjHCVrkDIvTiwjxYMUI”, “METHOD”:”Fax_Group_Status”,”API_KEY”:”3d51aab5ddbf43c4c9ed6c31936f17a930aecb5ba6ef45837f45 b193f6″,”CUSTOMER_PROVIDED_FAX_FIELDS”:[“test 1″,”test 2”]}

JSON Succesful Response

 

RESULT

Can be OK (if matching faxes found) or ERROR

FAXES

An Array of faxes that matches the search field

CUSTOMER_PROVIDED_FAX_FI ELD

The Customer provided data field when fax was sent

SOURCE_NUMBER

Origination fax number

DESTINATION_NUMBER

Destination fax number

TIME

Timestamp

PAGES

Number of fax pages

STATUS

QUEUED / PROGRESS / SENT / FAILED

 

TRY_COUNT

Retry counter (0 -3)

Example JSON Response (2 faxes match the data field): {“RESULT”:”OK”,”FAXES”:[{“CUSTOMER_PROVIDED_FAX_FIELD”:”test 1″,”SOURCE_NUMBER”:”18059731214″,”DESTINATION_NUMBER”:”18058522606″,”TIME”:”2016-12-12 12:43:59″,”PAGES”:”2″,”STATUS”:”SENT”,”TRY_COUNT”:”1″}, {“CUSTOMER_PROVIDED_FAX_FIELD”:”test 1″,”SOURCE_NUMBER”:”18059731214″,”DESTINATION_NUMBER”:”18058522606″,”TIME”:”2016-12-12 12:44:38″,”PAGES”:”2″,”STATUS”:”SENT”,”TRY_COUNT”:”1″}, {“CUSTOMER_PROVIDED_FAX_FIELD”:”test 2″,”SOURCE_NUMBER”:”18059731214″,”DESTINATION_NUMBER”:”18058522606″,”TIME”:”2016-12-12 12:45:27″,”PAGES”:”2″,”STATUS”:”SENT”,”TRY_COUNT”:”1″}]}

Error List

Error Description

NOT ALLOWED

Invalid API or Session Token submitted

INVALID JSON

Invalid JSON submitted

MISSING PARAMETERS

Valid JSON submitted with incomplete/missing/wrong variables

WRONG CREDENTIALS

Invalid Username/Password

Error Description

INVALID METHOD

Method not implemented

NOT FOUND

No faxes found with matching criteria


SMS API

Version 9

Please contact Axion tech support to get url and connection credentials.

User Authentication

Before being able to send API requests, user authentication must be completed using an API key, a username and a password. If correct authentication is completed, API will include in response a unique SESSION_TOKEN that must be used in every subsequent api request.
The session token is valid for 30 days. User authentication could be done at any time without waiting for token expiration, in which case a new token will be generated.

API key, user and password are provided by our support team.

API accepts only POST method requests and all variables must be sent in JSON format. API sends responses in JSON format as well.

In order to complete authentication, client must send a POST request to API URL all variables en- coded in JSON format.

API Method to check api version

JSON Request

method

userLogin

apiKey

The provided API key (never changes)

JSON Successful Response

RESULT

OK / ERROR

version

API version number

hash

api source image hash

buildTime

image build time

request and response postman example: 

 

Screen-Shot

API Method to Authenticate User

JSON Request

method

userLogin

apiKey

The provided API key (never changes)

username

Username used in web

password

Password used in web

JSON Successful Response

RESULT

OK / ERROR

sessionToken

A Temporary Session token to be used in subsequent api calls

request and response postman example: 

Screen-Shot
 

API Method to send SMS

This method allows user to send SMS or MMS to a single destination or multiple destina-
tions. Only USA destinations are currently supported. When request is received, the mes-
sage is flagged as QUEUED. Once the message is delivered to destination carrier, it will
be updated to SENT. A notification trigger could be set up to receive asynchronous notif-
ication when this happens.

 

JSON Request

method

sendSMS

apiKey

The provided API key (never changes)

sessionToken

A valid session token obtained from User_Login method call

sourceNumber

Origin number en E.164 format

destinationNumbers

Array of destination numbers in E.164 format

text

Message text

file

Optional file base64 encoded (jpg, png, gif, mp3 files supported up to 3.5MB)

customerProvidedId

Optional customer provided value that will be returned in response

JSON Succesful Response

RESULT

Can be OK (if sms is successfully sent) or ERROR

customerProvidedId

Optional customer provided data field sent in request

time

Message timestamp (UTC)

uuid

Unique message id

 

request and response (SMS text) postman example:

 

 

Screen-Shot 2022

 

request and response (MMS) postman example:

Screen-Shot

 

API Method to read SMS

This method allows user to read messages using any combination of filters. Api supports
full pagination so complete message history matching the supplied filters could be fet-
ched in small chunks. The maximum message count returned is 100.

JSON Request

method

getSMS

apiKey

The provided API key (never changes)

sessionToken

A valid session token obtained from User_Login method call

uuid

Optional to read single message

messagingNumber

Optional messaging number (own number).

number

Optional number in E.164 format to fetch all messages to/from specified
number. Messages returned are limited to 100 per query (pagination can be
used to read full message history). This can be internal or external number. If
number field is used, messagingNumber field should also be used.

messageStatus

Optional message status to filter response. Available statuses are SENT/
RECEIVED/RECEIVED_NOT_NOTIFIED/FAILED

fromTime

Optional from time filter (UTC)

toTime

Optional to time filter (UTC)

limit

Optional limit for pagination. (api will return up to this number of messages)

offset

Optional offset for pagination (api will skip this number of messages from
response)

sort

Optional time sorting. Can be set ASC or DESC (default)

customerProvidedId

Optional customer provided value that will be returned in response

JSON Succesful Response

RESULT

Can be OK (if matching sms found) or ERROR

customerProvidedId

The customer provided data field as sent in request

messages

Array of matching messages

uuid

Message id

src

Origin number in E.164 format

dst

Array of destination numbers

text

message text (can be empty or missing in case
of MMS)

time

Message time

media

An array of media files (MMS). Optional field not
present in text SMS messages.

status

Message status (SENT/RECEIVED/
RECEIVED_NOT_NOTIFIED/FAILED)

userUuid

user id (corresponds to web or api user sent the
message)

associatedNumber

the associated number in E.164 format

request and response postman example:
 

 

 
Screen Shot

 

API Method to read MMS Media

The media url(s) in messages are not publicly available. This method allows user to fetch single media file. The response is direct binary content inside body. Please note that me- dia files are deleted after 30 days from message time.

JSON Request

method

getMMSMedia

apiKey

The provided API key (never changes)

sessionToken

A valid session token obtained from User_Login method call

mediaUrl

Media url

request and response postman example (response is the binary png): 

 

 
Screen Shot

API Method to delete SMS

This method allows user to delete SMS . This action is permanent.

JSON Request

method

deleteSMS

apiKey

The provided API key (never changes)

sessionToken

A valid session token obtained from User_Login method call

uuid

Origin number in E.164 format

customerProvidedId

Optional customer provided value that will be returned in response

JSON Succesful Response

RESULT

Can be OK (if sms is successfully deleted) or ERROR

customerProvidedId

The customer provided data field as sent in request

request and response postman example: 

Screen Shot code

API Method to update Messaging Number

This method allows user to update messaging number settings.

JSON Request

method

updateNumber

apiKey

The provided API key (never changes)

sessionToken

A valid session token obtained from User_Login method call

number

Messaging number in E.164 format

callbackUrl

callback url used to send notifications when sms is received or sent sms status changes

JSON Succesful Response

RESULT Can be OK or ERROR

 

request and response postman example: 

Coding Screen Shot

 

Error List

 
Screen Shot

EVENT NOTIFICATIONS

Upon request, the system can send new message and message status change alerts to a
https customer provided url. Each customer number could be assigned a di
fferent url if
needed.

Once the alerting feature is enabled, the system will send a POST http request every time
a new message (inbound) is received including message uuid, message time, source
number and destination numbers.

example POST:
{

“event”: “newSMS”,

“uuid”: “ffadb6a1-752e-11e8-a2fe-323630393164”,

“time”: “2021-05-02T15:22:18Z”,
“number”: “+18056421414”,
“sourceNumber”: “+18056421415”,
“destinationNumbers”: [“+18056421414”],
“text”: “message text”,

“media”: ‘’
}

Message update notifications are also sent whenever an outbound message changes sta-
tus from QUEUED to SENT or FAILED. The notification includes the message uuid as well
as the new message status.

example POST:
{

“event”: “updatedSMS”,

}

“uuid”: “ffadb6a1-752e-11e8-a2fe-323630393164”,

“time”: “2021-05-02T15:22:18Z”,
“status”: “SENT”,
“messagingNumber”: “13109549528”,
“accountNumber”: “123456789012” 



Grow Your Business And Save On Cloud Communications

Find The Plan That Works For You.
Questions? Email us at customercare@axionco.com