Initiating Requests

As described in Data Exchange via Redox, a system or application can initiate a synchronous or asynchronus request via Redox. In either case, the requirements to initiate a request via the Redox JSON API 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 can be done using an API Key. Most users will choose to create a single key for all requests made to Redox API from their system or application.

Generating an access token for use with the API requires utilizing and API Key and Secret value that can be configured within the Redox Dashboard.

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 the “Developer” page within the main navigation menu. On the “API Key” section of this page, select “Create API Key”.

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

On the edit screen for your API Key, copy the 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 system(s) you are sending data to or the system 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 Exchange via Redox 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 Exchange via Redox for more details.