Login

BlueStep API

This document provides details on connecting to and using the BlueStep System API endpoints.

Introduction

The BlueStep System operates on an Event Driven Architecture. All API calls are synchronous HTTPS transactions between the BlueStep System and the entity making the call. The system provides data based on the specified packs. The "pack" is a required element when making the request. The system can also create new records or entries if a “-1” is passed as the ID of the record. 

Example: 

  • If the package is set to “ADT”, demographic data will be provided. 

  • If package is set to “OMP”, a medication message will be provided. 

Entry point

All calls to our API must be done to the following URL:

https://{unitDefaultTaskDomain}.bluestep.net/b/APIData

Where {UnitDefaultTaskDomain} is the client’s main domain.

Authentication

The BlueStep System API uses an access token for authentication given for security purposes, therefore, keep it as safe as possible. Include the access token in the Authorization header for all your requests.

H-Authorization: bearer <your_API_key>

Warning: The access token grants permission to any holder to update sensitive information, including your own credentials. Be cautious about entrusting it to a third party. 

Request Content

All requests to BlueStep System endpoints must be made via HTTPS. Include the required headers and parameters in your request. 

 

Headers: 

  • `Content-Type`: Specify `application/json` for the request body. 

  • `Authorization`: `bearer <your_API_key>` 

Body: 

The request body must be a JSON stringified object. These are the possible properties to attach to it: 

Property 

Type 

POST 

PUT 

pack 

string 

Required 

N/A 

queryFid 

string 

Required 

N/A 

filters 

Object<filter> 

Optional 

N/A 

recordData 

Object<recordData> 

N/A 

Required 

 

Body properties explanation: 

  `pack`: The pack property is a string that determines the type of data to be retrieved. Examples of values include: 

  • ADT (Admission, Discharge, Transfer): Retrieve demographic data related to Admission, Discharge, or Transfer events. 

  • OMP (Medication Centric Message): Retrieve data formatted in the OMP style message format. 

  • ORM (Doctor’s Order Message): Retrieve Order Message data. 

  • MKG (Marketing): Retrieve data related to marketing activities. 

  • BIL (Billing): Retrieve data related to billing processes. 


Example of the "pack”property: "pack": "ADT" 


 `queryFid`:  The queryFid is a string that determines the main report being used to get the required data. It will impact the forms being available to get data and to filter data from. 
  Example of the "queryFid” property: "queryFid": "allRes" 


 `filters`:  POST requests can be filtered based on a “recordId” and/or a list of “formFields”. To achieve this, add a filters property to your request body following this structure:
Example:
  “filters”: {
    “recordId”: “{recordId}”,
    “formFids”: [
      “{formFid1}”,
      “{formFid2}”,
    ]
  }

Explanation: 

  • {recordId}: Unique identifier of a record within the report that is being required. 
  • {formFid}: Unique identifier for the form you want to filter results on. For example, it could be "name" for the "Name and Email" form if this form is available in the pack you’re requesting. 

Request Format

POST - Read Records

Example #1 - Get All Records within a “pack”:

POST /b/APIData HTTP/1.1 
Host: {unitDefaultTaskDomain}.bluestep.net 
H-Content-Type: application/json 
H-Authorization: bearer <your_API_key> 
 
Body: 
 
{ 
  "pack": "MKG", 
  "queryFid": "allRes" 
} 

Warning: requesting large amounts of data such as the package "ORM" for all or multiple residents might result in a timeout.

Example #2 – Get a specific record within a “pack” by “recordId”:

POST /b/APIData HTTP/1.1 
Host: {unitDefaultTaskDomain}.bluestep.net 
H-Content-Type: application/json 
H-Authorization: bearer <your_API_key> 
 
Body: 
{ 
  "pack": "ADT", 
  "queryFid": "allRes", 
  "filters": { 
    "recordId": "1158589" 
  }
}

Example #3 - Get a specific record and data within a “pack” by “recordId” and “formFids”:

POST /b/APIData HTTP/1.1 
Host: {unitDefaultTaskDomain}.bluestep.net 
H-Content-Type: application/json 
H-Authorization: bearer <your_API_key> 
 
Body: 
{ 
  "pack": "ADT", 
  "queryFid": "allRes", 
  "filters": { 
    "recordId":"1160210", 
    "formFids"["clientBio","name"] 
  } 
} 

PUT - Update Existing Record

Example #1 

PUT /b/APIData HTTP/1.1 
Host: {unitDefaultTaskDomain}.bluestep.net 
H-Content-Type: application/json 
H-Authorization: bearer <your_API_key>

Body: 
{ 
  "allRes": { 
    `${record_id}`: { 
      "name": { 
        "firstName": "firstName Test", 
        "lastName": "lastName Test" 
      }
    }
  }
}

 

Example #2 

PUT /b/APIData HTTP/1.1  
Host: {unitDefaultTaskDomain}.bluestep.net  
H-Content-Type: application/json  
H-Authorization: bearer <your_API_key>

Body:
{ 
  "allRes": {   
    `${recordId}`: { 
      "name": { 
        "email": "test@gmail.com", 
        "midName": "Potter" 
      } 
    } 
  } 
}

PUT - Create New Record

Example #1 

PUT /b/APIData HTTP/1.1  
Host: {unitDefaultTaskDomain}.bluestep.net  
H-Content-Type: application/json  
H-Authorization: bearer <your_API_key>

Body:
{ 
  "allRes": { 
    "-1": { 
      "name": { 
        "email": "test@gmail.com", 
        "midName": "MiddleName test", 
        "firstName": "firstName Test",
        "lastName": "lastName Test" 
      } 
    } 
  }
}

Response Format

Getting files from a request

Documents retrieved in a request will be sent by their URLs with the following structure:
{ "fileName": "{fileName}", "url": "{internalUrl}", "id": "{internalId}" }

To access the file in question, you must build the complete URL by attaching the {internalUrl} to the base domain of the unit {unitDefaultTaskDomain}.bluestep.net

Example: Document received: { "fileName": "Test Document", "url": "/files/xxx/Documents/Test_document.pdf", "id": "123456" } Unit base domain: https://fakeunit.bluestep.net Final document URL: https://fakeunit.bluestep.net/files/xxx/Documents/Test_document.pdf



Response Status

In the BlueStep System API, various errors may occur during the processing of requests. Errors are communicated through appropriate HTTPS status codes and error response bodies. Below are some common error scenarios and how they are handled:  

Common HTTP Status Codes: 

  • 200 OK: The request was successful. 
  • 400 Bad Request: The request was malformed or invalid. 
  • 401 Unauthorized: Authentication failed, or the provided access token is either invalid or expired. 
  • 403 Forbidden: The authenticated user does not have permission to access content. 
  • 429 Too many requests: Many requests were made in a short period of time.  
  • 404 Not Found: The requested resource does not exist. 
  • 500 Internal Server Error: An unexpected error occurred. 
  • 504 Gateway Timeout: The processed data is too large, resulting in a timeout.

Rate Limiting

The API enforces a rate limit with a timeout of 5 seconds between requests. This means that any subsequent request made within 5 seconds of the previous one will not be processed and a 429-response error will be thrown.

Contact information

For further assistance or inquiries, please contact: 

 

BlueStep 2024, System API Documentation © All rights reserved.