Quick Start Guide: Connecting to Redox

In this Quick Start Guide we’ll discuss some Redox basics and behaviors you’ll need to build your app to execute. We’ll walk through using the key and secret associated with your Source to initiate a query, and send a sample message to the endpoint you configure in your Destination.  The Redox DevTools and Postman collections will be used here for brevity and consistency.

Sending Requests To Redox

Authentication

Redox uses a token based authentication scheme. After making a request for an initial token, you will send this token in subsequent request headers until it expires. At this point you can refresh your token. In this example, the Postman collection handles all of this for you. Follow these steps to get going!

  1. Download the Postman collection and environment files for your source which can be found on the Overview page on the Source Credentials card.
  2. In Postman import your Source’s collection and environment files.
  3. Select the environment you just imported from the environments dropdown.
  4. Click the Manage Environments button to add the credentials specific to your source. The {{api_key}} will already be populated for you but you’ll need to add a  value for {{secret}} in the current value column. You can generate a new secret on the overview page if you haven’t already. Update this environment.
  5. Click on the folder labelled “Authorization” and then the request “Initial Login”. Send this request to complete authentication with Redox.

Search for a Patient

Now that we’re authenticated, we can make requests to Redox for data we’re interested in. All of the DataModel and Queries endpoints in this collection will now work and you can play around with all of them to get familiar. Redox uses standard JSON Data Models that represent a wide variety of patient-centric data that can be exchanged across our Network. Users connecting to the Redox API will process messages according to these models, whether receiving pushed data, initiating queries, or pushing data back to Redox as a writeback. In this Quick Start, we’ll send our Redox Sample EHR a Query for Patients.

  1. In Postman, click on the folder labelled “Queries” and then the request “Clinical Summary ^ PatientQuery”. The Patient Search query will use a subset of patient demographic information to find a patient record match. This is often useful to retrieve the specific identifiers required for subsequent calls on a patient chart.
  2. Click on “Body” to see the sample payload being sent to Redox.
  3. Send the request, Redox will respond with a record match.

Receiving Data From Redox

Authentication

Applications receiving requests from the Redox API should specify a Verification Token in their Destination record that Redox will then include in the header of messages sent to the customer’s endpoint.

  1. Find the Destination Credentials card on the overview page and click on “Settings”.
  2. Next, specify your Endpoint, which is your organization’s webhook endpoint where you want Redox HTTP requests sent. This URL will need to be accessible by Redox’s servers and an HTTPS endpoint is required for both Staging and Production destinations.
  3. Next, you’ll set a Verification Token. This is a token we will send in the verification-token field of the HTTP request header in every request Redox makes to your endpoint. This is how you will ensure the communication is coming from Redox and that no other entity is sending data to your endpoint.
  4. Finally, verify your endpoint by clicking “Verify and Save”. When you Verify and Save a request is made to your url with the Verification Token you set and a Challenge value. Your application needs to respond to this request with the Challenge value. You can read more about this process and other options here.

Send Data to your Webhook

  1. Go to your Destination’s DevTools. A link to this page can be found on the Destination Credentials card.
  2. Select any data model and fill out its required fields. You can edit the JSON in the editor however you like patient details of clinical code. This message will be marked as a test message.
  3. Once you’re ready to send the message, scroll to the bottom of the JSON payload and click the Send Data Model button. Once sent, a transmission will be created and you should see a link to its log appear.
  4. If everything has been set up properly you will receive a 200 Response from your endpoint. You can read more about common error responses here