{ "openapi": "3.1.0", "info": { "title": "AVANSER User API reference", "version": "202610", "description": "AVANSER User API allows third party applications to initiate phone calls, and send and receive SMS messages." }, "servers": [ { "url": "https://p3.avanser.com/app/", "description": "Avanser Production" } ], "security": [ { "accessToken": [] } ], "tags": [ { "name": "Authentication", "description": "AVANSER User API requires users to login with their AVANSER username and password before making any further API calls.\n\nWhen an application makes a login request, the API returns an access token that must be included with all API calls to identify the user. This access token is persistent and non-expiring.\n\nIf a user decides to logout of their AVANSER account, the application should make a logout request to remove the access token.\n" }, { "name": "Calls" }, { "name": "SMS" }, { "name": "User Information" }, { "name": "Validate Phone Numbers" }, { "name": "Data Caching", "description": "The [Call Log](#reference/0/calls/call-log) and [List Messages](#reference/0/sms/list-messages) API calls will usually return the same data on each call, along with any new calls or messages that have been received.\nAs such, each of these provides a parameter that allows an application to retrieve only new records by specifying the ID of the most recently retrieved record.\nThis allows applications to use the API more efficiently, by caching the data locally instead of continually requesting the same data.\n\nHowever, there are cases where the locally cached data may need to be discarded.\nThe user specifies settings in the AVANSER portal that determine what data is returned by the API.\nThese settings include which client to view data for, as well as any filters to apply to call log data.\n\nThe results of the Call Log and List Messages API calls each include an **options** key that indicates whether locally cached data should be discarded.\nIf no data needs to be discarded, the value of this key will be *null* or an empty array.\nHowever, when the user updates their API settings, causing the data that is returned by the API to change, this key will contain an object in the following format:\n\n```\n{\"flush_calls\": true, \"flush_messages\": true}\n```\n\nIf the *flush_calls* key exists in this object, cached call log data should be discarded.\nSimilarly, if the *flush_messages* key exists in this object, cached messages should be discarded.\n\nNote: These flags will continue to be returned in all API results until the application makes an API call to disable them, as outlined below:\n" } ], "paths": { "/login": { "post": { "tags": [ "Authentication" ], "summary": "Login", "operationId": "login", "security": [], "description": "Request an access token to use in API calls. The access token is returned as a string in the **data** key.\n\n**Errors**\n\n| Error Code | Error Type | Error Message |\n|:---|:---|:---|\n| -1004 | ALREADY-LOGGED-IN | You are already logged in |\n| -1005 | MISSING-USERNAME | username field missing |\n| -1006 | MISSING-PASSWORD | password field missing |\n| -1008 | MISSING-DEVICEID | deviceId field missing |\n| -1030 | ERR_INVALID_USER | Invalid username |\n| -1028 | ERR_INVALID_PASSWORD | Password is not valid |\n| -1029 | ERR_USER_LOCKOUT | This account has been locked due to too many incorrect login attempts |\n| -1031 | ERR_PASSWORD_90EXPIRY | Password expired, please reset your password |\n| -1032 | ERR_USER_6MEXPIRY | User has not been active in the last six month, please reset your password |\n| -1020 | LOGIN-FAILED | Invalid username or password |\n\n**ERR_INVALID_USER** and **ERR_INVALID_PASSWORD** and the standard errors returned if the login credentials entered are incorrect.\n**LOGIN-FAILED** is a generic error returned if the login attempt fails for an unspecified reason. This may include an invalid username or password depending on the client that the user belongs to.\n", "x-apiary-uri-template": "/login?username={username}&password={password}&deviceId={deviceId}&device={device}", "parameters": [ { "name": "username", "in": "query", "required": true, "description": "The user's AVANSER username.", "schema": { "type": "string" } }, { "name": "password", "in": "query", "required": true, "description": "The user's AVANSER password.", "schema": { "type": "string" } }, { "name": "deviceId", "in": "query", "required": true, "description": "A string to uniquely identify the application requesting the access token. If a user could feasibility login to two instances of the same application (eg. two organisations in the same CRM), each of these should provide a unique deviceId (eg. by appending the organisation ID to the name of the application). This ensures that separate access tokens are generated for each instance, so that, for example, logging out of one instance doesn't remove access from the other.", "schema": { "type": "string" } }, { "name": "device", "in": "query", "required": true, "description": "Identifier of the mobile handset, \"ios\" for APPLE and \"adt\" for ANDROID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Access token in data.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "string" } } } ] }, "example": { "timestamp": 1508903167, "exection": 0.00041531896591187, "error": false, "data": "13beb532cc997f2066d60eff65ea9d30" } } } } } } }, "/logout": { "post": { "tags": [ "Authentication" ], "summary": "Logout", "operationId": "logout", "description": "Remove the user's API token.\n\n**Errors**\n\n| Error Code | Error Type | Error Message |\n|:---|:---|:---|\n| -1003 | NOT-LOGGED-IN | You are not logged in |\n", "x-apiary-uri-template": "/logout?token={token}", "responses": { "200": { "description": "Successful logout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringDataResponse" }, "example": { "timestamp": 1508903336, "exection": 0.000087486028671265, "error": false, "data": "OK" } } } } } } }, "/forgotpassword": { "post": { "tags": [ "Authentication" ], "summary": "Forgot Password", "operationId": "forgotPassword", "security": [], "description": "Request to change the user's password. An email will be sent to the user containing a verification code.\n\n**Errors**\n\n| Error Code | Error Type | Error Message |\n|:---|:---|:---|\n| -1004 | ALREADY-LOGGED-IN | You are already logged in |\n| -1005 | MISSING-USERNAME | username field missing |\n| -1030 | ERR_INVALID_USER | Invalid username |\n| -1032 | ERR_RESET_PASSWORD | We have experienced some technical difficulties resetting your password. Please contact support@avanser.com |\n", "x-apiary-uri-template": "/forgotpassword?username={username}", "parameters": [ { "name": "username", "in": "query", "required": true, "description": "The user's AVANSER username, or the email address associated with their account.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Password change requested.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringDataResponse" }, "example": { "timestamp": 1508903167, "exection": 0.00041531896591187, "error": false, "data": "OK" } } } } } } }, "/resetpassword": { "post": { "tags": [ "Authentication" ], "summary": "Reset Password", "operationId": "resetPassword", "security": [], "description": "Change the user's password using the verification code sent to the user's email address.\n\n**Errors**\n\n| Error Code | Error Type | Error Message |\n|:---|:---|:---|\n| -1004 | ALREADY-LOGGED-IN | You are already logged in |\n| -1033 | MISSING-VERIFICATION-CODE | Verification Code field missing |\n| -1034 | ERR_INVALID_VERIFICATION | Invalid Verification Code |\n| -1006 | MISSING-PASSWORD | password field missing |\n| -1027 | ERR_PASSWORD_SAME | Password must be different from current password |\n| -1024 | ERR_PASSWORD_HISTORY | Please provide a password that has not been used already |\n| -1025 | ERR_PASSWORD_8 | Password must be at least 8 characters and include at least 1 UPPERCASE, 1 lowercase and 1 number |\n| -1026 | ERR_PASSWORD_ULN | Password must be at least 8 characters and include at least 1 UPPERCASE, 1 lowercase and 1 number |\n| -1032 | ERR_RESET_PASSWORD | We have experienced some technical difficulties resetting your password. Please contact support@avanser.com |\n", "x-apiary-uri-template": "/resetpassword?verification_code={verification_code}&password={password}", "parameters": [ { "name": "verification_code", "in": "query", "required": true, "description": "The verification code sent to the user's email address.", "schema": { "type": "string" } }, { "name": "password", "in": "query", "required": true, "description": "The new password for the user.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Password reset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringDataResponse" }, "example": { "timestamp": 1508903167, "exection": 0.00041531896591187, "error": false, "data": "OK" } } } } } } }, "/setregistrationtoken": { "post": { "tags": [ "Authentication" ], "summary": "Set Registration Token", "operationId": "setRegistrationToken", "description": "Set Registration Token for the device.\n\n**Errors**\n\n| Error Code | Error Type | Error Message |\n|:---|:---|:---|\n| -1008 | MISSING-DEVICEID | deviceId field missing |\n| -1035 | ERR_REG_TOKEN | Invalid deviceId or deviceType, RegistrationToken not updated |\n", "x-apiary-uri-template": "/setregistrationtoken?token={token}&deviceId={deviceId}®istrationToken={registrationToken}&device={device}&fcmProjectId={fcmProjectId}", "parameters": [ { "name": "deviceId", "in": "query", "required": true, "description": "A string to uniquely identify the application requesting the access token. If a user could feasibility login to two instances of the same application (eg. two organisations in the same CRM), each of these should provide a unique deviceId (eg. by appending the organisation ID to the name of the application). This ensures that separate access tokens are generated for each instance, so that, for example, logging out of one instance doesn't remove access from the other.", "schema": { "type": "string" } }, { "name": "device", "in": "query", "required": true, "description": "Identifier of the mobile handset, \"ios\" for APPLE and \"adt\" for ANDROID", "schema": { "type": "string" } }, { "name": "registrationToken", "in": "query", "required": true, "description": "A string to uniquely identify the registration token.", "schema": { "type": "string" } }, { "name": "fcmProjectId", "in": "query", "required": false, "description": "A string idendifying the fcmProjectId.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Registration token set.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringDataResponse" }, "example": { "timestamp": 1508903167, "exection": 0.00041531896591187, "error": false, "data": "OK" } } } } } } }, "/calls": { "get": { "tags": [ "Calls" ], "summary": "Call Log", "operationId": "callLog", "description": "Retrieve a list of call records for the current day.\n\n#### Explanation of Return Value\n\nThe **data** object in the return result contains the following keys:\n\n| Key | Description |\n|-------------|----------------------------------------------------------------------------------------------------------------------------------------|\n| cdr | An array of call records. Each call is represented by an object. The format of this object is discussed below. |\n| tot / calls | The total number of calls returned in the **cdr** array. |\n| options | Inidicates if any cached data should be cleared. See the [Data Caching documentation](#reference/0/data-caching) for more information. |\n\n##### Call Objects\n\nEach object in the **cdr** array represents a single call record, and includes the following keys:\n\n| Key | Description |\n|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| id | The ID of the call. This is the ID that should be passed to the **lastcdr** parameter in subsequent API calls to retrieve only newer calls. |\n| date | The time that the call started, represented as the number of seconds since the UNIX epoch. |\n| external | An object representing the non-AVANSER phone number involved in the call. **avanser** is the phone number in AVANSER format, and **cutamper** is a unique identifier for this phone number. |\n| adSource | The AdSource name of the AVANSER BNUM. |\n| status | An integer representing the call status. The meaning of each possible value is listed in the table below. |\n| duration | The duration of the call in seconds. |\n| internal | An object representing the answerpoint for inbound calls, or the from number for outbound calls. **avanser** is the phone number in AVANSER format, and **name** is the answerpoint name. |\n| country | The country that the call originated from. |\n| state | The state that the call originated from. |\n| location | The location that the call originated from. |\n| audio | An object representing an audio file associated with a call. **url** is the URL to access the audio file (or an empty string if there is no audio file associated with the call), and **type** is a string representing the type of audio, either *recording* or *message*. |\n| direction | The direction of the call. Possible values are *call-in* and *call-out*. |\n\nNote: Calls in the **cdr** array are returned in reverse-chronological order, with the newest call appearing first in the array.\n\nWhen making a subsequent API call to retrieve newer calls, the application should pass the **highest** ID value in the **lastcdr** parameter.\n\n###### Call Statuses\n\nThe table below lists the meaning of each of the possible integer values returned in the **status** key:\n\n| Status Code | Description |\n|-------------|-------------|\n| 0 | Abandoned |\n| 1 | Answered |\n| 2 | Busy |\n| 3 | Unanswered |\n| 4, 5 | Reserved |\n| 6 | Fax |\n", "x-apiary-uri-template": "/calls?token={token}&lastcdr={lastcdr}", "parameters": [ { "name": "lastcdr", "in": "query", "required": false, "description": "The ID of the most recently retrieved call. If provided, only newer calls will be retrieved. If omitted, all calls for the logged in user will be retrieved.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "Call records for the current day.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallLogResponse" }, "example": { "timestamp": 1510092008, "exection": 0.0013340220451355, "error": false, "data": { "tot": 5, "cdr": [ { "id": "38338110", "date": "1510091607", "external": { "avanser": "+61-0412345678", "cutamper": "61686422126" }, "adSource": "Example AdSource", "status": "1", "duration": "10", "internal": { "avanser": "+61-0498765432", "name": "Example Answerpoint" }, "country": "AU", "state": "MOB", "location": "Mobile", "label": "", "audio": { "url": "http://portal.avanser.com/audio/6999/69990134/in/rec.6999-2017-11-08-085327-460360.wav", "type": "recording" }, "direction": "call-in" }, { "id": "38338118", "date": "1510091539", "external": { "avanser": "+61-0412354687", "cutamper": "61686422126" }, "adSource": "Example AdSource", "status": "1", "duration": "99", "internal": { "avanser": "+61-0498765432", "name": "Dial out" }, "country": "AU", "state": "MOB", "location": "Mobile", "label": "", "audio": { "url": "", "type": "recording" }, "direction": "call-out" } ], "calls": 5, "options": null } } } } } } } }, "/dial": { "post": { "tags": [ "Calls" ], "summary": "Make Call", "operationId": "makeCall", "description": "Initiate an outgoing phone call that will be tracked by the AVANSER call tracking service. The process is as follows:\n\n1. The person making the call will be called on the *from*.\n2. Once this person answers, the call will be connected to the *to*.\n\n#### Caller ID\n\nThe possible values for the **callerId** parameter are outlined below:\n\n| Option | Description |\n|:-----------------|-----------------------------------------------------------------------------------------------|\n| auto | Use the default Caller ID that is configured for the user's AVANSER account. |\n| hidden | Hide the Caller ID (private call). |\n| *(phone number)* | A phone number to use for the Caller ID, in AVANSER format, or local or international format. |\n\n#### Errors\n\n| Error Code | Error Type | Error Message |\n|:---|:---|:---|\n| -1009 | INVALID-FROM-NUMBER | Invalid caller number |\n| -1010 | INVALID-TO-NUMBER | Invalid called number |\n| -1011 | INVALID-CALLERID | Invalid CallerID |\n| -1013 | FROM-NUMBER-NOTALLOWED | Caller number denied by configuration |\n| -1012 | TO-NUMBER-NOTALLOWED | Called number denied by configuration |\n| -1014 | MAKE-CALL-FAILED | Unable to queue your call |\n\n**FROM-NUMBER-NOTALLOWED** and **TO-NUMBER-NOTALLOWED** are returned if the logged in user doesn't have access to make calls to/from the given phone number. See the **Dialer Access** section in the [User Information documentation](#reference/0/user-information/get-user-information).\n\n**MAKE-CALL-FAILED** is a generic error returned if the call cannot be initialised for an unspecified reason.\n", "x-apiary-uri-template": "/dial?token={token}&from={from}&to={to}&callerId={callerId}&record={record}&label={label}", "parameters": [ { "name": "from", "in": "query", "required": true, "description": "The phone number of the person making the call, in AVANSER format.", "schema": { "type": "string" }, "example": "+61-0212345678" }, { "name": "to", "in": "query", "required": true, "description": "The phone number to call, in local or international format.", "schema": { "type": "string" }, "example": "0212345678" }, { "name": "callerId", "in": "query", "required": false, "description": "Whether to show or hide the default Caller ID, or a custom Caller ID to use.", "schema": { "type": "string", "default": "auto" }, "x-apiary-members": [ "auto", "hidden", "(phone number)" ] }, { "name": "record", "in": "query", "required": false, "description": "Whether to record the phone call (boolean). This option is ignored if the user's AVANSER account is configured to force recording.", "schema": { "type": "number", "enum": [ 0, 1 ], "default": 0 } }, { "name": "label", "in": "query", "required": false, "description": "a label to be assigned to the Call Record, can be set in the http callbacks to match the call record to your request.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Outgoing call request result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MakeCallResponse" }, "example": { "timestamp": 1508908351, "exection": 0.000072510957717896, "error": false, "data": { "from": "+61-0412345678", "to": "+61-0298765432", "callerId": "+61-0412345678", "recording": "no", "label": "" } } } } } } } }, "/messages": { "get": { "tags": [ "SMS" ], "summary": "List Messages", "operationId": "listMessages", "description": "Retrieve a list of SMS messages for the logged in user.\n\n#### Explanation of Return Value\n\nThe **data** object in the return result contains the following keys:\n\n| Key | Description |\n|:---------|----------------------------------------------------------------------------------------------------------------------------------------|\n| messages | An array of messages. Each message is represented by an object. The format of this object is discussed below. |\n| tot | The total number of messages returned in the **messages** array. |\n| options | Inidicates if any cached data should be cleared. See the [Data Caching documentation](#reference/0/data-caching) for more information. |\n\n##### Message Objects\n\nEach object in the **messages** array represents a single message, and includes the following keys that an application may be interested in:\n\n| Key | Description |\n|:----------|--------------------------------------------------------------------------------------------------------------------------------------------------|\n| id | The ID of the message. This is the ID that should be passed to the **lastId** parameter in subsequent API calls to retrieve only newer messages. |\n| date | The time that the message was sent, represented as the number of seconds since the UNIX epoch. |\n| bnum | The AVANSER phone number that the message was sent from/to, in AVANSER format (this is always the phone number of the API user). |\n| external | The non-AVANSER phone number involved in the conversation, in AVANSER format. |\n| text | The content of the message. |\n| direction | The direction of the message (**in** or **out**). **in** indicates that the message was sent from the *external* number to the *bnum* number. **out** indicates that the message was sent from the *bnum* number to the *external* number. |\n\nNote: Messages in the **messages** array are returned in reverse-chronological order, with the newest messages appearing first in the array. The logged in user may have messages for multiple BNUMS, and each BNUM may have messages for mutliple external numbers.\nThe messages from a single conversation aren't necessarily grouped together in the array, and it is the responsibility of the application to parse the array and display the messages in the desired format.\nAlso note that when subsequent API calls are made to retrieve new messages, the new return result may include BNUMs or external numbers that didn't appear in the previous result.\n\nWhen making a subsequent API call to retrieve newer messages, the application should pass the **highest** ID value in the **lastId** parameter.\n\n#### Errors\n\n| Error Code | Error Type | Error Message |\n|:---|:---|:---|\n| -1021 | GET-MESSAGES-FAILED | Unable to retreive the message list |\n\nThis is a generic error returned if the messages cannot be retrieved for an unspecified reason.\n", "x-apiary-uri-template": "/messages?token={token}&lastId={last_message}", "parameters": [ { "name": "lastId", "in": "query", "required": false, "description": "The ID of the most recently retrieved message. If provided, only newer messages will be retrieved. If omitted, all messages for the logged in user will be retrieved.", "schema": { "type": "number" }, "x-apiary-parameter-name": "last_message" } ], "responses": { "200": { "description": "SMS messages for the logged in user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageListResponse" }, "example": { "timestamp": 1508970922, "exection": 0.00095471692085266, "error": false, "data": { "messages": [ { "id": "27894", "clientId": "6999", "date": 1506401365, "bnum": "+61-0412345678", "external": "+61-0498765432", "internal": "example@avanser.com.au", "to": null, "text": "Example Message", "direction": "out", "echo": "0", "source": "msgQ", "sourceId": "3120757", "country": null, ".DB": "envox" }, { "id": "27892", "clientId": "6999", "date": 1506401344, "bnum": "+61-0412345678", "external": "+61-0498765432", "internal": "", "to": null, "text": "Another Example Message", "direction": "in", "echo": "0", "source": "sms", "sourceId": "51830", "country": null, ".DB": "envox" } ], "tot": 2, "options": null } } } } } } } }, "/sendmessage": { "post": { "tags": [ "SMS" ], "summary": "Send Message", "operationId": "sendMessage", "description": "Send an SMS message. The **bnum** needs to be an AVANSER BNUM that the logged in user has access to send messages from. For more information about checking this, see the **Mobile BNUMs** section in the [User Information documentation](#reference/0/user-information/get-user-information)\n\n**Errors**\n\n| Error Code | Error Type | Error Message |\n|:---|:---|:---|\n| -1015 | MISSING-BNUM | bnum field missing |\n| -1016 | MISSING-EXTERNAL | external field missing |\n| -1017 | MISSING-MESSAGE | message field missing |\n| -1023 | INVALID-BNUM | Unable to parse BNUM number |\n| -1022 | INVALID-EXTERNAL | Unable to parse EXTERNAL number |\n| -1018 | SEND-MESSAGE-FAILED | Unable to send your message |\n\n**SEND-MESSAGE-FAILED** is a generic error returned if the message cannot be sent for an unspecified reason.\n", "x-apiary-uri-template": "/sendmessage?token={token}&bnum={bnum}&external={external}&message={message_content}", "parameters": [ { "name": "bnum", "in": "query", "required": true, "description": "The AVANSER BNUM to send the message from, in AVANSER phone number format. The logged in user must have access to send messages from this BNUM.", "schema": { "type": "string" }, "example": "+61-0412345678" }, { "name": "external", "in": "query", "required": true, "description": "The phone number to send the message to, in AVANSER format, or local or international format.", "schema": { "type": "string" }, "example": "0498765432" }, { "name": "message", "in": "query", "required": true, "description": "The content to send in the message.", "schema": { "type": "string" }, "x-apiary-parameter-name": "message_content" } ], "responses": { "200": { "description": "SMS submission result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringDataResponse" }, "example": { "timestamp": 1510101887, "exection": 0.00018191409111023, "error": false, "data": "+61-0412345678;+61-04987654321;12345" } } } } } } }, "/deliverystatus": { "post": { "tags": [ "SMS" ], "summary": "Message delivery status", "operationId": "messageDeliveryStatus", "description": "Retrieve the delivery status for a specific SMS using its Message ID. The Message ID is provided in the Send Message API response as the third parameter in the data string.\n\nThe API returns an object with a data field containing the message ID and delivery status in the following format:\n\n```\n{\n \"timestamp\": 1782969745,\n \"exection\": 0.0013545999526978,\n \"error\": false,\n \"data\": {\n \"message_id\": \"12345\",\n \"status\": \"sent\"\n }\n}\n```\n\n#### Errors\n\n| Error Code | Error Type | Error Message |\n|:---|:---|:---|\n| -1000 | ACCESS-DENIED | Access Denied |\n| -1040 | MISSING-MESSAGE-ID | ID field missing |\n| -1041 | INVALID-MESSAGE-ID | ID field has invalid value or not found |\n| -1042 | NOT-AVAILABLE-STATUS | The message status is not available |\n| -1043 | ACCESS-DENIED-TO-MESSAGE-ID | Access denied to the message ID |\n\n#### Supported Statuses\n\n| Type | Status | Description |\n|:---|:---|:---|\n| Processing States | `not_sent` | The message is in the sending queue. |\n| Processing States | `sent` | The message has been sent successfully. Delivery confirmation pending. |\n| Terminal States | `delivered` | The message was successfully delivered. |\n| Terminal States | `failed` | The message failed to send. |\n| Terminal States | `undelivered` | The message was sent but not delivered. |\n", "x-apiary-uri-template": "/deliverystatus?token={token}&id={id}", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "The message ID that you have received in the `Send Message` API.", "schema": { "type": "integer" }, "example": 12345 } ], "responses": { "200": { "description": "Delivery status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryStatusResponse" }, "examples": { "sent": { "summary": "sent", "value": { "timestamp": 1782969745, "exection": 0.0013545999526978, "error": false, "data": { "message_id": "12345", "status": "sent" } } }, "delivered": { "summary": "delivered", "value": { "timestamp": 1782969745, "exection": 0.0013545999526978, "error": false, "data": { "message_id": "12345", "status": "delivered" } } } } } } } } } }, "/profile": { "get": { "tags": [ "User Information" ], "summary": "Get User Information", "operationId": "getUserInformation", "description": "Retrieve profile information about the currently logged in user. The return result in the example has been condensed to include only the data that an application may be interested in.\n\nThe data returned in the **data** key is outlined below:\n\n| Key | Description |\n|:-----------------------------|-------------------------------------------------------------------------------------------------------------|\n| preferences.dialerAccessFrom | An array of countries that the logged in user has access to use for the **from** when making a call. |\n| preferences.dialerAccessTo | An array of countries that the logged in user has access to use for the **to** when making a call. |\n| mobileBnums | An array of phone numbers that the logged in user has access to send SMS messages from. |\n\n#### Dialer Access\n\nThe **dialerAccessFrom** and **dialerAccessTo** keys are each provided as an array of objects. Each object represents a country that the user has access to in the following format:\n\n| Key | Description |\n|:-------|-----------------------------------------------------------------------------------------------------------------|\n| name | The name of the country. |\n| prefix | The dial prefix for the country. |\n| allow | The type of phone numbers that the user has access to for this country (examples: *all*, *landline*, *mobile*). |\n\nNote: If the user has access to all countries, then instead of an array, the value of the **dialerAccessFrom** or **dialerAccessTo** will be a string with a single asterisk (*).\n\nIf an API call is made to make a call to a country that the user doesn't have access to, it will simply fail and return an appropriate error message. However, downloading and caching these country lists allows the application to validate the call without making an API call.\nAdditionally, this allows the application to provide a configuration form for the user to select the phone number to use for their **from** for all calls. The application can use the **dialerAccessFrom** list to display a list of countries, and the user can simply select a country and type their phone number in local format, which the application can then convert into AVANSER format appropriately.\n\nNote that these settings may change, so the values should only be cached for a single session.\n\n#### Mobile BNUMS\n\nThe **mobileBnums** key is an object containing a list of phone numbers that the logged in user has access to send SMS messages from. The object key is the name used to represent the phone number in the AVANSER portal, and the value is the phone number itself. As this list is limited, it is often useful to display a list of phone numbers for the user to select from, rather than having them enter a phone number manually.\n\nNote that a user may have access to *view* messages for BNUMs that they can't *send* messages from. Also, this list may change, so the values should only be cached for a single session.\n", "x-apiary-uri-template": "/profile?token={token}", "responses": { "200": { "description": "Profile information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" }, "examples": { "countryAccess": { "summary": "Access to a country", "value": { "timestamp": 1508975327, "exection": 0.000060782909393311, "error": false, "data": { "preferences": { "dialerAccessFrom": { "AU": { "name": "Australia", "prefix": "61", "allow": "all" } }, "dialerAccessTo": { "AU": { "name": "Australia", "prefix": "61", "allow": "all" } } }, "mobileBnums": { "Example VMN": "+61-0412345678" } } } }, "allCountries": { "summary": "Access to all countries", "value": { "timestamp": 1508975327, "exection": 0.000060782909393311, "error": false, "data": { "preferences": { "dialerAccessFrom": "*", "dialerAccessTo": "*" }, "mobileBnums": { "Example VMN": "+61-0412345678" } } } } } } } } } } }, "/checknumber": { "get": { "tags": [ "Validate Phone Numbers" ], "summary": "Validate Phone Number", "operationId": "validatePhoneNumber", "description": "Checks that the phone number provided is in a valid format within the country for the dial prefix provided. Note that this doesn't actually check that the phone number exists, just that it is in a valid format. If the **error** key returns *false*, it means that the phone number is valid.\n\nNote: The return value includes the provided phone number, re-formatted correctly in local format, in the **data.num** key. Additionally, the dial prefix is also returned in the **data.cc** key. Therefore, it is simple to re-build this into AVANSER format as follows: **+{cc}-{num}**.\n\n#### Errors\n\n| Error Code | Error Type | Error Message |\n|:---|:---|:---|\n| -1019 | INVALID-PHONE-NUMBER | Invalid phone number |\n", "x-apiary-uri-template": "/checknumber?token={token}&cc={cc}&phone={phone}", "parameters": [ { "name": "cc", "in": "query", "required": true, "description": "The dial prefix of the country that the phone number is for.", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "required": true, "description": "The phone number to validate, in local format.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Phone number format validation result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidatedNumberResponse" }, "example": { "timestamp": 1508979483, "exection": 0.00013305497169495, "error": false, "data": { "country": "AU", "cc": 61, "num": "0412345678", "type": "mobile" } } } } } } } }, "/options": { "get": { "tags": [ "Data Caching" ], "summary": "Disable Cache Flags", "operationId": "disableCacheFlags", "description": "When an application discards locally cached data as a result of receiving a *flush_calls* or *flush_messages* flag in an API result, it should call this method to inform the API to stop returning the corresponding flag in future API results.\n", "x-apiary-uri-template": "/options?token={token}&options[{option}]=false", "x-apiary-parameter": { "name": "option", "in": "query-key-placeholder", "required": true, "type": "string", "members": [ "flush_calls", "flush_messages" ] }, "parameters": [ { "name": "options", "in": "query", "required": true, "description": "The flag to disable. Note: Multiple flags can be disabled in a single call by passing this parameter multiple times, eg. ```options[flush_calls]=false&options[flush_messages]=false```", "style": "deepObject", "explode": true, "schema": { "type": "object", "minProperties": 1, "properties": { "flush_calls": { "type": "boolean", "const": false }, "flush_messages": { "type": "boolean", "const": false } } } } ], "responses": { "200": { "description": "Cache flags disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringDataResponse" }, "example": { "timestamp": 1510101397, "exection": 0.00035298299789429, "error": false, "data": "OK" } } } } } } } }, "components": { "securitySchemes": { "accessToken": { "type": "apiKey", "in": "query", "name": "token", "description": "Access token retrieved from a previous login call." } }, "schemas": { "ApiResponse": { "type": "object", "required": [ "timestamp", "error", "data" ], "properties": { "timestamp": { "type": "integer", "description": "The time that the API response left the server, represented as the number of seconds since the UNIX epoch.", "example": 1508903167 }, "exection": { "type": "number", "description": "The number of seconds that it took to process the API request.", "example": 0.00041531896591187 }, "error": { "type": "boolean", "description": "Boolean indicating whether there was an error returned by the API request.", "example": false }, "data": { "description": "The data returned by the API. The format varies depending on the API function that was called." } } }, "StringDataResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "string" } } } ] }, "CallRecord": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the call. This is the ID that should be passed to the **lastcdr** parameter in subsequent API calls to retrieve only newer calls.", "example": "38338110" }, "date": { "type": "string", "description": "The time that the call started, represented as the number of seconds since the UNIX epoch.", "example": "1510091607" }, "external": { "type": "object", "description": "An object representing the non-AVANSER phone number involved in the call.", "properties": { "avanser": { "type": "string", "description": "The phone number in AVANSER format.", "example": "+61-0412345678" }, "cutamper": { "type": "string", "description": "A unique identifier for this phone number.", "example": "61686422126" } } }, "adSource": { "type": "string", "description": "AdSource name of the AVANSER BNUM.", "example": "Example AdSource" }, "status": { "type": [ "integer", "string" ], "description": "An integer representing the call status. The meaning of each possible value is listed in the table below.", "enum": [ 0, 1, 2, 3, 4, 5, 6, "0", "1", "2", "3", "4", "5", "6" ], "example": "1" }, "duration": { "type": [ "integer", "string" ], "description": "The duration of the call in seconds.", "example": "10" }, "internal": { "type": "object", "description": "An object representing the answerpoint for inbound calls, or the from number for outbound calls.", "properties": { "avanser": { "type": "string", "description": "Phone number in AVANSER format.", "example": "+61-0498765432" }, "name": { "type": "string", "description": "Answerpoint name.", "example": "Example Answerpoint" } } }, "country": { "type": "string", "description": "The country that the call originated from.", "example": "AU" }, "state": { "type": "string", "description": "The state that the call originated from.", "example": "MOB" }, "location": { "type": "string", "description": "The location that the call originated from.", "example": "Mobile" }, "label": { "type": "string", "example": "" }, "audio": { "type": "object", "description": "An object representing an audio file associated with a call.", "properties": { "url": { "type": "string", "description": "The URL to access the audio file (or an empty string if there is no audio file associated with the call)." }, "type": { "type": "string", "enum": [ "recording", "message" ], "description": "A string representing the type of audio, either *recording* or *message*.", "example": "recording" } } }, "direction": { "type": "string", "enum": [ "call-in", "call-out" ], "description": "The direction of the call. Possible values are *call-in* and *call-out*.", "example": "call-in" } } }, "CacheOptions": { "description": "If no data needs to be discarded, the value of this key will be *null* or an empty array.", "oneOf": [ { "type": "null" }, { "type": "array", "items": {} }, { "type": "object", "properties": { "flush_calls": { "type": "boolean", "description": "If the *flush_calls* key exists in this object, cached call log data should be discarded." }, "flush_messages": { "type": "boolean", "description": "Similarly, if the *flush_messages* key exists in this object, cached messages should be discarded." } } } ] }, "CallLogResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "tot": { "type": "integer", "description": "The total number of calls returned in the **cdr** array.", "example": 5 }, "cdr": { "type": "array", "description": "An array of call records. Each call is represented by an object. The format of this object is discussed below.", "items": { "$ref": "#/components/schemas/CallRecord" } }, "calls": { "type": "integer", "description": "The total number of calls returned in the **cdr** array.", "example": 5 }, "options": { "$ref": "#/components/schemas/CacheOptions" } } } } } ] }, "MakeCallResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "from": { "type": "string", "example": "+61-0412345678" }, "to": { "type": "string", "example": "+61-0298765432" }, "callerId": { "type": "string", "example": "+61-0412345678" }, "recording": { "type": "string", "example": "no" }, "label": { "type": "string", "example": "" } } } } } ] }, "MessageRecord": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the message. This is the ID that should be passed to the **lastId** parameter in subsequent API calls to retrieve only newer messages.", "example": "27894" }, "clientId": { "type": "string", "example": "6999" }, "date": { "type": "integer", "description": "The time that the message was sent, represented as the number of seconds since the UNIX epoch.", "example": 1506401365 }, "bnum": { "type": "string", "description": "The AVANSER phone number that the message was sent from/to, in AVANSER format (this is always the phone number of the API user).", "example": "+61-0412345678" }, "external": { "type": "string", "description": "The non-AVANSER phone number involved in the conversation, in AVANSER format.", "example": "+61-0498765432" }, "internal": { "type": "string", "example": "example@avanser.com.au" }, "to": { "type": "null" }, "text": { "type": "string", "description": "The content of the message.", "example": "Example Message" }, "direction": { "type": "string", "enum": [ "in", "out" ], "description": "The direction of the message (**in** or **out**). **in** indicates that the message was sent from the *external* number to the *bnum* number. **out** indicates that the message was sent from the *bnum* number to the *external* number.", "example": "out" }, "echo": { "type": "string", "example": "0" }, "source": { "type": "string", "example": "msgQ" }, "sourceId": { "type": "string", "example": "3120757" }, "country": { "type": "null" }, ".DB": { "type": "string", "example": "envox" } } }, "MessageListResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "messages": { "type": "array", "description": "An array of messages. Each message is represented by an object. The format of this object is discussed below.", "items": { "$ref": "#/components/schemas/MessageRecord" } }, "tot": { "type": "integer", "description": "The total number of messages returned in the **messages** array.", "example": 2 }, "options": { "$ref": "#/components/schemas/CacheOptions" } } } } } ] }, "DeliveryStatusResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "message_id": { "type": "string", "example": "12345" }, "status": { "type": "string", "enum": [ "not_sent", "sent", "delivered", "failed", "undelivered" ], "example": "delivered" } } } } } ] }, "CountryAccess": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the country.", "example": "Australia" }, "prefix": { "type": "string", "description": "The dial prefix for the country.", "example": "61" }, "allow": { "type": "string", "description": "The type of phone numbers that the user has access to for this country (examples: *all*, *landline*, *mobile*).", "example": "all" } } }, "DialerAccess": { "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/CountryAccess" } }, { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CountryAccess" } }, { "type": "string", "enum": [ "*" ] } ] }, "MobileBnums": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "ProfileResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "preferences": { "type": "object", "properties": { "dialerAccessFrom": { "$ref": "#/components/schemas/DialerAccess" }, "dialerAccessTo": { "$ref": "#/components/schemas/DialerAccess" } } }, "mobileBnums": { "$ref": "#/components/schemas/MobileBnums" } } } } } ] }, "ValidatedNumberResponse": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "type": "object", "properties": { "data": { "type": "object", "properties": { "country": { "type": "string", "example": "AU" }, "cc": { "type": "integer", "description": "The dial prefix is also returned in the **data.cc** key.", "example": 61 }, "num": { "type": "string", "description": "The return value includes the provided phone number, re-formatted correctly in local format, in the **data.num** key.", "example": "0412345678" }, "type": { "type": "string", "example": "mobile" } } } } } ] } } } }