Initiating Requests (Source)

As described in Sources, Destinations, & Subscriptions, a system configured as a source can send or request data from destination system via the Redox API. In either case, the requirements to initiate a request are nearly the same, though details on error modes and response handling differ.

The process of initiating requests to the Redox API is broken down into three sections:

  1. Authenticating a Request
  2. Making a Request
  3. Handling the Response
    1. SEND (Asynchronous)
    2. REQUEST (Synchronous)

Authenticating a Request

Authenticating to the Redox API for sending or requesting data is done via a source configuration. Most users will choose to create a single source record for all requests made to Redox API from their system or application.

Each source has a distinct API Key and Secret valuethat are used to generate access credentials.

Secret values are how your system proves its identity to Redox. This value should be kept secure and should never be exposed to a client for production data.

If lost or exposed, secret values can be invalidated and regenerated via the Redox Dashboard.

Authentication Steps

1) Generate an API Key and Secret from the Redox Dashboard

Within the Redox Dashboard, navigate to an existing source record (or create a new one) with communication method “Redox API” and data format “JSON”.

All new users to the Redox dashboard will find a “Redox API Endpoint” source that can be used for development and test requests to the Redox API. See for Getting Started a tutorial.

On the settings tab of a source record, copy your API key and Secret values for use during authentication.

2) Request an Access Token

You can utilize your API Key and Secret values to request an access token for authenticating Redox API requests. Specifically, to request an access token, POST each of these values to the Redox API authentication endpoint like so:

POST https://api.redoxengine.com/auth/authenticate

Sample Request

curl -X POST https://api.redoxengine.com/auth/authenticate \
 -H '{"Content-Type": "application/json"}' \
 -d '{"apiKey": "not-a-real-api-key", "secret": "super-secret-client-secret"}'

Sample Response

The object returned for a successful request will contain an access token:

{
   "accessToken": "13d5faa8-aacd-4a0d-a666-51455b1b2ced",
   "expires": "2015-03-25T20:52:35.000Z",
   "refreshToken": "4ed7b234-9bde-4a9c-9c86-e1bc6e535321"
 }
PropertyDescription
accessTokenAccess token to authenticate Redox API requests
expiresExpiration date time in YYYY-MM-DDThh:mm:ss.sssZ format
refreshTokenRefresh token to retrieve a new access token after it expires
Token Expiration & Refresh Tokens

Access tokens for Redox API expire 24 hours after retrieval. The exact time the token expires is included in the expires property. If you attempt to use an expired access token with a Redox API request, the API will return a 401 Unauthorized error.

After expiry, you can utilize the refresh token returned from the most recent authentication request to retrieve a new access token via the refresh token endpoint:

POST https://api.redoxengine.com/auth/refreshToken

Sample Request

curl -X POST https://api.redoxengine.com/auth/refreshToken \
 -H '{"Content-Type": "application/json"}' \
 -d '{"apiKey": "not-a-real-api-key", "refreshToken": "4ed7b234-9bde-4a9c-9c86-e1bc6e535321"}'

The object returned for a successful response will be the same as that for the original access token retrieval request noted above.

3) Authenticate your Redox API Requests

The Redox API utilizes an Oauth 2.0 Bearer authentication scheme to authenticate API requests. All requests to the Redox API must contain an Authorization header with a valid access token in the following format: Authorization: Bearer <your-accessToken>

Example Usage

curl -X POST https://api.redoxengine.com/endpoint \
 -H '{"Authorization": "Bearer f81eeac9-7cb0-4a82-951b-724f592723ae"}'

Making a Request

All requests to the Redox API are performed against the same endpoint:

https://api.redoxengine.com/endpoint

Required Parameters

Every request must contain the following headers and body parameters:

Header

HeaderValueDescription
AuthenticationBearer <your-accessToken>Required for authenticating your request.
(See ”Authenticating a Request” above)
Content-Typeapplication/jsonAll Redox API endpoints expect JSON format

Body

PropertyTypeDescription
Meta.DataModelStringData Model corresponding to the type of data you are sending or requesting.
Meta.EventTypeStringEvent Type of the data model that you are sending or requesting.
Meta.Destinations[].IDArray[String]Objects with ID value(s) of the destination(s) you are sending data to or the destination your are requesting data from.
Data Model Requirements

Some Data Models require additional parameters. A full list of required parameters for each Data Model is included in our data model reference. See Data Models & Event Types for details.

Example Request

Putting all of this information together, an example request looks like this:

curl \
 -X POST https://api.redoxengine.com/endpoint \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer <access-token-here>" \
 -d '{
   "Meta": {
     "DataModel": "PatientAdmin",
     "EventType": "Arrival",
     "Destinations": [
       {
         "ID": "af394f14-b34a-464f-8d24-895f370af4c9",
         "Name": "Redox EMR"
       }
     ]
   },
   "Patient": {
      // … payload omitted
   }
 }'

You can generate more example requests via the Redox Dev Tools, which are described in further detail here: Getting Started


Handling the Response

Finally, depending on the request made, your system or application will need to understand how to handle the response returned.

Response characteristics differ based on the type of request made and whether or not your request requires a response from a destination system. To complete your workflow and appropriately handle errors that may occur, see the following documentation pages:

ActionData FlowLog Type
SENDAsynchronous (one-way)SEND
REQUESTSynchronous (two-way)REQUEST

SEND or REQUEST is usually determined by the event type and workflow set up for your integration. See Data Models & Event Types for more details.