Greenlight RESTful API Basics

This section covers some basic concepts used in the Greenlight RESTful API. If you are already comfortable with tokens, path params, headers, bodies, etc., then you can skip this.

You should think about API requests to Greenlight in two categories:

1. The API request to get a token.
This is the only API request which doesn't require a token - instead, you send it three secret codes (customerId, clientSecret, and x-api-key), in order to get a token for use in all other API requests.

2. All other API requests
All other API requests require that you already have a valid, unexpired bearer token in addition to the customerId and x-api-key.

API request concepts - used in the API Reference

When your system makes an API request, it populates different parts of the request structure. All of these are standard RESTful API concepts; the descriptions below use Greenlight specific examples. These concepts (and API request sections) are used throughout the API Reference.

1. Path - the URL for the request, which includes the correct API endpoint (the Internet address for that task). API URLs often include additional information, called Path Parameters. A commonly used path param in the Greenlight API is your unique customerId. Requests often have multiple path params - for example, customerId, patientId, requestId, and documentId are path params to GET a particular document within Greenlight.

2. Authentication - this section contains the bearer token. Tokens are issued by the Greenlight API when you use the Get Token endpoint and verify your identity (customerId, clientSecret, and x-api-path). The token is a long random string of characters, like a password, which expires. You must include an unexpired token in the Authentication portion of every API request (except the API request to get a token).

3. Query Parameters - additional limits or instructions for the API. An example is when you fetch a document from Greenlight you can specify whether you want it in XML or PDF format.

4. Headers - Portions of the API request that contain other values. For example, your unique x-api-key will need to be passed in a header.

5. Body - most of the data being exchanged. When you send Greenlight a new patient, the patient's demographic data is carried in the body, with Body Params being the individual values you send (firstName, lastName, dateOfBirth, etc.). Responses (the answers Greenlight sends back in answer to your requests) also have bodies, containing ids (like a documentId, or a requestId), or containing the document you fetched.

For each request you make to Greenlight's API you will need:

1. Authentication (the token), required for all API requests (except the API request to get the token).

2. The headers, params, and body needed, described in detail in the API Reference for each of the different available Greenlight API requests (Get authorization token, Create Patient, Create Order, Add Requests, Find Changes, Fetch a document).