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:
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:
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:
request and response (MMS) postman example:
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 |
messageStatus | Optional message status to filter response. Available statuses are SENT/ |
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 |
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 | |
time | Message time | |
media | An array of media files (MMS). Optional field not | |
status | Message status (SENT/RECEIVED/ | |
userUuid | user id (corresponds to web or api user sent the | |
associatedNumber | the associated number in E.164 format | |
request and response postman example:
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):
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:
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:
Error List
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 different 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”