The Aware External API is intended to provide customers with the means to automate certain interactions.
The supported capabilities are tailored to allow customers to construct integrations with other systems that they own or have built. This API is targeted toward back-end integrations. It is not designed to support building alternative user interfaces.
Security
All API methods are protected by a customer specific access token. This token is provided through the HTTP X-Aware-Api-Key header.
In order to obtain the access token, a user must be an Aware Administrator. When ready, navigate to https://aware.work and select System Settings > Integrations.
Base URL
The API is exposed publicly at the following:
This value must be combined with the path for a specific method.
Limits
All API methods are subject to rate limits. This protects a customer from being adversely impacted by others. The rate limits will take multiple forms. These forms include:
-
The frequency of which an API method can be called. Ex: 25 Method calls/second
-
The max duration for a method. Ex: A method call cannot exceed 3 seconds
-
The max page size for a method. Ex: A method call cannot return more than 200 rows per page
These values will be adjusted over time as the system is tuned, based on API usage patterns and when new APIs are exposed. Finally, these values may vary per method.
DataTypes
This section details various types that can be format specific.
DateTime fields are required to be in ISO 8601 UTC format for input and output.
Ex: 2018-12-01T15:30:30Z
Proprietary Fields
The API will use Aware specific fields in certain API calls. These fields are typically used to uniquely identify objects within the Aware system. These values are being called out in order to alert the customer that they should not be used, and that no assumptions should be made. Aware reserves the right to change the format and/or content of these fields at any time.
When backwards compatibility is introduced (future), these fields will still be excluded from compatibility. As such, Aware strongly recommends that you treat these fields as simple strings. Aware will ensure that these fields contain no special characters.
In order to identify Aware specific fields for the customer, the Aware API will always name these fields as xxxModelId.
Query Strings
The API supports several standard options that apply across multiple APIs. Please see the documentation for a particular API to determine if it supports a particular query string option.
-
filter - Supplies one or more search fields. The field set is documented with each API.
-
limit - Supplies a page size or number of values to return.
-
more - Supplies context around where the previous page left off and where the next page should begin.
-
sort - Supplies the field and direction to order the data. The field set is documented with each API.
Pagination
Pagination is provided to assist with returning lists of data rows. This is important when there are a large number of rows to return. API methods have a max execution time. Pagination provides a mechanism for splitting a long running API method into multiples.
The API supports a forward only, seek pagination model. Under this model, an API method that returns a list of data rows will have a subset of size X along with a pagination token. This pagination token will be passed onto the next call to resume obtaining data from the next page.
Compatibility
During the initial phases of building the Aware API, it is expected that changes may occur often. These changes will likely be due to flaws, shortcomings and customer feedback. In general, API methods will be versioned. However, backward compatibility within API methods will not be supported initially.
Note: Specifics about how breaking changes are rolled out and customers are notified
Methods
Status - GET
Description: Retrieve API Status
| Resource Part | |
|---|---|
| Verb | GET |
| Path | status |
| Headers | X-Aware-Api-Key: {token} |
Body:
Response:
{
"status": "active",
"version": "{string}"
}
Comments:
This method can be used to determine the status of the Aware API. This method will never be versioned. The status values can be:
-
active - The API is operating normally
-
maint - The API is currently undergoing planned maintenance. This may be a software upgrade or emergency change.
-
inactive - The API is currently down due to an unexpected issue. The version will contain current API version
Hold Request - List
Description: Retrieve a list of hold requests.
| Resource Part | |
|---|---|
| Verb | GET |
| Path | holdrequest |
| Headers | X-Aware-Api-Key: {token} |
| QueryStr | limit=&filter=&more= |
| filter fields | isstopped:{true/false} |
| sort fields | {future} |
Body:
Response:
{
"more": "{string}",
"results": [
{
"holdRequestModelId": "{string}",
"holdKey": "{string}",
"holdKeyType": "Email",
"name": "{string}",
"startedOn": "{ISO Date/Time}",
"stoppedOn": null,
"platforms": [ "{string}", "{string}" ]
},
{
"holdRequestModelId": "{string}",
"holdKey": "{string}",
"holdKeyType": "Email",
"name": "{string}",
"startedOn": "{ISO Date/Time}",
"stoppedOn": null,
"platforms": [ "{string}" ]
}
],
"totalResults": {int}
}
Comments:
This method will provide a paged list of hold requests. The isstopped filter will allow the caller to request active/inactive/all hold requests.
Hold Request - Retrieve details
Description: Retrieve the details for a specific hold request.
| Resource Part | |
|---|---|
| Verb | GET |
| Path | holdrequest/{holdRequestModelId} |
| Headers | X-Aware-Api-Key: {token} |
Body:
Response:
{
"holdRequestModelId": "{string}",
"holdKey": "{string}",
"holdKeyType": "Email",
"name": "{string}",
"platforms": [
"{string}",
"{string}"
]
}
Comments:
This method will retrieve details about a specific hold request.
Hold Request - Create
Description: Create a new hold request.
| Resource Part | |
|---|---|
| Verb | POST |
| Path | holdrequest |
| Headers | X-Aware-Api-Key: {token} |
Body:
{
"holdKey": "{string}",
"holdKeyType": "Email",
"name": "{string}",
"startedOn": "{ISO Date/Time}"
"stoppedOn": null,
"platforms": [ {string}, {string}]
}
Response:
{
"holdRequestModelId": "{string}",
"holdKey": "{string}",
"holdKeyType": "Email",
"name": "{string}",
"startedOn": "{ISO Date/Time}",
"stoppedOn": null,
"platforms": [ "{string}", "{string}" ]
}
Comments:
This method will create and immediately enable a new hold request. The only holdKeyType that is currently supported is 'Email'. If you pass null for platforms, then the hold request will be assigned to all enabled platforms.
Hold Request - Update
Description: Update an existing hold request.
| Resource Part | |
|---|---|
| Verb | PUT |
| Path | holdrequest/{holdRequestModelId} |
| Headers | X-Aware-Api-Key: {token} |
Body:
{
"name": "",
"release": true
}
Response:
{
"holdRequestModelId": "{string}",
"holdKey": "{string}",
"holdKeyType": "Email",
"name": "{string}",
"startedOn": "{ISO Date/Time}",
"stoppedOn": null,
"platforms": [ "{string}", "{string}" ]
}
Comments:
This method allows the hold request to be changed. Any combination of these parameters may be supplied. If a parameter is null or not supplied, it will not be modified. If the hold request is already marked as stopped, an error will be generated.
Platform - List
Description: Provides the list of platforms.
| Resource Part | |
|---|---|
| Verb | GET |
| Path | platform |
| Headers | X-Aware-Api-Key: {token} |
| QueryStr | |
| filter fields | |
| sort fields | {future} |
Body:
Response:
{
"more": "{string}",
"results": [
{
"platformModelId": "{string}",
"isEnabled": {true/false},
"name": "{string}"
},
{
"platformModelId": "{string}",
"isEnabled": {true/false},
"name": "{string}"
}
],
"totalResults": {int}
}
Comments:
This method will provide a paged list of platforms. The more value in this response is not currently used.
Appendix
History: |Doc Ver |Api Ver |Date |Comment |--------|----------|------------|------- |v1 | 20190101 | 2018-12-01 | Initial Alpha; Support data holds |
References: