This article provides information on integrating with the Aware External API, including supported methods, security, rate, limits, data types, pagination, and compatibility details for managing hold requests and platforms.
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.
To obtain the access token, a user must be an Aware Administrator.
When ready, navigate to https://aware.work and select System Settings followed by Integrations.
Base URL
The API is exposed publicly as the following:
https://api.aware.work/gen2-public
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 maximum duration for a method. Ex: A method call cannot exceed 3 seconds.
- The maximum page size for a method. Ex: A method call cannot return more than 200 rows per page.
The values discussed in this context are not static. They are subject to adjustments over time as part of our ongoing system optimization process. This process takes into account patterns of API usage and the introduction of new APIs. These values may also differ depending on the method used.
Data Types
The following section details various types that can be format specific.
DateTime fields are required to be in ISO 8601UTC format for input and output.
Ex: 2018-12-01T15:30:30Z
Propriety 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 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, 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.
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. 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 ended and where the next page should begin.
- Sort: Supplies the field and direction to order the data. The field 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.
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 the 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: Provide 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.
Comments
Please sign in to leave a comment.