AVANSER User API reference (202610)
AVANSER User API allows third party applications to initiate phone calls, and send and receive SMS messages.
All responses returned by the API are represented by a JSON object with the following keys:
| Key | Example Value | Description |
|---|---|---|
| timestamp | 1508903167 | The time that the API response left the server, represented as the number of seconds since the UNIX epoch. |
| exection | 0.00041531896591187 | The number of seconds that it took to process the API request. |
| error | false | Boolean indicating whether there was an error returned by the API request. |
| data | (mixed) | The data returned by the API. The format varies depending on the API function that was called. |
If an API request is unsuccessful, the response will be returned with the error key set to false, and the data key set to an object with the following format:
| Key | Example | Error Message |
|---|---|---|
| code | -1000 | A numerical code to identify the error type. |
| type | ACCESS-DENIED | A string code to represent the error type. |
| message | Access Denied | A human readable error message, suitable to be displayed to the user. |
| details (if applicable) | (string) | A string with additional details about the error. Note: This key only exists if there are additional details to display, so the application should check if it exists before attempting to access it. |
Specific error types that can be returned by each API function are detailed throughout this document. Below is a generic error type that can be returned by any API call:
| Error Code | Error Type | Description |
|---|---|---|
| -1000 | ACCESS-DENIED | Access Denied |
This error is returned if the access token is missing, invalid, or has been removed (via a call to the logout function).
Most phone numbers that are sent to the API need to be provided in AVANSER phone number format. This is a phone number format that includes a plus symbol, followed by the country code, followed by a dash, followed by the local phone number format with any non-digit characters removed.
Examples:
These examples use Australian phone numbers, where the country prefix is 61. For phone numbers for other countries, simply substitute the correct country prefix.
| Local Format | AVANSER Format |
|---|---|
| (02) 1234 5678 | +61-0212345678 |
| 0412 345 678 | +61-0412345678 |
When making a call or sending an SMS, where a user may enter a phone number manually, they can be provided in local format for phone numbers within the same country as the from number, or in international format for phone numbers in a different country. This allows the user to enter a phone number as they usually would, without needing to know the AVANSER format.
This document always specifies which formats a phone number can be provided in. All API calls require at least one of the phone numbers to be provided in AVANSER format - This is the phone number that determines what country the local format refers to for the other phone number.
Note: All non-numeric characters should be removed from local and international phone numbers. Also, the area code is always required, even for local calls. For example, the Australian phone number (02) 1234 5678 should be sent as 0212345678.
International phone numbers shouldn't include any dial out prefix. Therefore, calling the above phone number from outside of Australia would look like this: 61212345678.
All phone numbers returned by the API are in AVANSER format.