Engagement Rx API

The Engagement Rx API provides support for data integration with the Engagement Rx system. The API follows the REST model of exposing resources and includes API interface versioning to avoid breaking changes with existing integrations.

API Keys

In order to access the Engagement Rx API, you will need an API key.  API keys can be requested through Platform Support. API keys are directly linked to individual portals within your account.  If you have multiple portals within your account, you will need to request an API key for each of your portals.

Hosts

For convenience, Avidon Health provides a staging environment for integration development and testing. The following environments are available.  The Stage environment is for integration development and testing, including UAT testing related to new releases when relevant.  Development should never be performed against the production environment.

Transmission
Authentication

Access to the Engagement Rx API uses the following authentication method:

HTTP Basic Authentication – The username and password can be requested through the Engagement Rx support desk. All requests require authentication and must be made over HTTPS.

Authorization

Available resources and data are restricted based on your account configuration.  If an unauthorized resource is accessed, an HTTP 403 forbidden error is returned.

Responses

All responses use the JSON format.

HTTP Status Codes

The API uses the following standard HTTP status codes:

Caching

The API supports caching of resources for up to 5 minutes using the following response and request headers:

Each API response will include an ETag HTTP Header which contains a hash value representing the data returned by the API call. The next time the client application makes the same API call, include the If-None-Match request header with the ETag value from the first step.  If the data has not changed, the API will return HTTP Status Code 304 and no data will be returned.   If the data has changed, a new ETag hash value will be returned along with the updated data.

Note, a request for data which returns an HTTP Status Code 304 still counts against the Rate Limiting described below.

Rate Limiting

In order to provide a fast response time, the API limits the amount of requests which can be made to 1000 requests every 15 minutes for each partner application. When the rate limit is hit for your account, the API will return the HTTP status code 429 (Too Many Requests) for all requests until the rate limited period expires.

The following rate limiting http headers are included with each response to help manage your calls:

If you expect to hit the rate limit, we recommend that your implementation use these headers for managing calls and use an exponential backoff retry algorithm when a 429 status code is returned.

Error Handling

Engagement Rx uses conventional HTTP status codes to indicate an API request failed. In general, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with the Engagement Rx system.

The HTTP status code 503 (Service Unavailable) is returned if the API is temporarily unavailable due to site restarts that may occur as part of our self-healing services or new releases. We recommend that your implementation use an exponential backoff retry algorithm when a 503 status code is returned. 

In addition to the status code, the body of the response will contain details for the error and will contain the following attributes:

Example Error Response

{
    Message: "Parameter out of range",
    MessageDetail: "The startDate cannot be greater than the endDate"
}

API Methods

All API methods and objects are described on the Engagement Rx API website located at:

https://api.engagementrx.com