Engagement Rx API

Modified on Thu, Sep 12 at 1:13 PM

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.




Environment



Host



Stage



https://apistage.engagementrx.com



Production



https://api.engagementrx.com




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:



Status Code



Description



2xx



A successful API call.



3xx



Caching related response codes.



4xx



The API request resulted in an error due to incorrect information provided (e.g. a required parameter was missing; a parameter was outside its valid range; etc.).



5xx



An unknown error occurred processing your request.  These errors are logged and reported to Avidon Health's DevOps team.




Caching


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




Direction



HTTP Header



Description



Response



ETag



A hash value representing the data returned by the API call.



Request



If-None-Match



The hash value provided by the ETag header.



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:



Direction



HTTP Header



Description



Response



RateLimit-Limit



The number of allowed requests in the current period.



Response



RateLimit-Remaining



The number of remaining requests in the current period.



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:




Attribute



Description



Message



A general message describing the error condition.



MessageDetail



More detailed information regarding what caused the error condition.




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


 

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article