Getting Started with the Brellium API

Prerequisites - how to enable API access for your clinic
Common Use Case - Our recommended flow for sending and retrieving audits from Brellium
Example Implementations - How to integrate with the API in practice

Prerequisites

Please reach out to your account manager or support@brellium.com to enable API access for your clinic.

You will be provided with a client id and client secret that can be used to access the API.

Common Use Case

Here is a example use case for “Clinic X” using the Brellium API:

Once a day, Clinic X uploads all new documents from the past 24 hours to Brellium via API to be audited.

Clinic X then pulls in all audits that have been created or updated in the past 24 hours and updates their internal records.

Example Implementations

Here’s example code for important endpoints:

Authentication

https://brellium-ai.readme.io/reference/post_auth

Any request to the Brellium API must include an access token in the headers.

Use the following to obtain the token:

import requests

url = "https://api.brellium.com/v1/auth"

payload = {
    "client_id": "MY-CLIENT-ID",
    "client_secret": "MY-CLIENT-SECRET"
}
headers = {
    "accept": "application/json",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

const axios = require('axios');

const url = 'https://api.brellium.com/v1/auth';

const payload = {
  client_id: 'MY-CLIENT-ID',
  client_secret: 'MY-CLIENT-SECRET'
};

const headers = {
  accept: 'application/json',
  'content-type': 'application/json'
};

axios.post(url, payload, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

curl -X POST https://api.brellium.com/v1/auth \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -d '{
    "client_id": "MY-CLIENT-ID",
    "client_secret": "MY-CLIENT-SECRET"
}'

By default, tokens have an expiry time of 24 hours. We recommend implementing a authentication flow where any 400 response will trigger a token refresh and retry.

Audit Creation

https://brellium-ai.readme.io/reference/post_documents

https://brellium-ai.readme.io/reference/post_documents-multiple

Use the /documents endpoint to send notes to Brellium or the /documents-multiple endpoint if a note contains information from multiple files.

NOTE: /documents-multiple is NOT used to send multiple separate session notes at the same time.

In the example use case, once a day, Clinic X would iterate through their new notes and make a post request to the Brellium API for each.

If there’s information available internally that’s not present on the note, send it using the metadata field.

Here is an example of how to send documents to Brellium, including a internal provider id.

url = "https://api.brellium.com/v1/documents"

files = { "file": ("172372-23456-SESSION-04-08-25.pdf", open("172372-23456-SESSION-04-08-25.pdf", "rb"), "application/pdf") }
payload = { "clinic_x_provider_id": "172372" }
headers = {
    "accept": "application/json",
    "authorization": "Bearer MY-GENERATED-JWT-TOKEN"
}

response = requests.post(url, data=payload, files=files, headers=headers)

const FormData = require('form-data');
const fs = require('fs');

const url = 'https://api.brellium.com/v1/documents';

const form = new FormData();
form.append('clinic_x_provider_id', '172372');
form.append('file', fs.createReadStream('172372-23456-SESSION-04-08-25.pdf'), {
  contentType: 'application/pdf',
  filename: '172372-23456-SESSION-04-08-25.pdf'
});

const headers = {
  ...form.getHeaders(),
  accept: 'application/json',
  authorization: 'Bearer MY-GENERATED-JWT-TOKEN'
};

axios.post(url, form, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

curl -X POST https://api.brellium.com/v1/documents \
  -H "accept: application/json" \
  -H "authorization: Bearer MY-GENERATED-JWT-TOKEN" \
  -F "clinic_x_provider_id=172372" \
  -F "file=@172372-23456-SESSION-04-08-25.pdf;type=application/pdf"

Audits will be created shortly after the upload.

Pulling in Data

https://brellium-ai.readme.io/reference/post_audits

https://brellium-ai.readme.io/reference/get_question-sets

You can pull information about audits using the /audits endpoint and question-sets using the /question-sets endpoint.

Here is how Clinic X can maintain up to date information on audit results the with the service code 23456:

Use the /question-sets endpoint to find the set id for a given note type:

url = "https://api.brellium.com/v1/question-sets"

headers = {
    "accept": "application/json",
    "authorization": "Bearer MY-GENERATED-JWT-TOKEN"
}

response = requests.get(url, headers=headers)

const url = 'https://api.brellium.com/v1/question-sets';

const headers = {
  accept: 'application/json',
  authorization: 'Bearer MY-GENERATED-JWT-TOKEN'
};

axios.get(url, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

curl -X GET https://api.brellium.com/v1/question-sets \
  -H "accept: application/json" \
  -H "authorization: Bearer MY-GENERATED-JWT-TOKEN"

[
  {
    "set_id": "e14b9f1a-1234-4a10-9a4f-1fd4c0dc1234",
    "name": "23456",
    "questions": [
      {
        "question_id": "a1b2c3d4-5678-4e9f-a123-9f4cde0a1111",
        "query": "Does the session narrative only contain information relevant to the session?",
        "question_type": "default",
        "severity": "Critical"
      },
      {
        "question_id": "b2c3d4e5-6789-4f01-b234-0a1b2c3d2222",
        "query": "Are patient symptoms clearly documented with time of onset?",
        "question_type": "default",
        "severity": "Normal"
      },
      {
        "question_id": "c3d4e5f6-7890-4a12-c345-1b2c3d4e3333",
        "query": "Is there a note of any medication administered during the session?",
        "question_type": "default",
        "severity": "Normal"
      }
    ]
  },
  {
    "set_id": "f25c0e4b-2345-4b20-9c6d-2de0ba9c2345",
    "name": "23457",
    "questions": [
      {
        "question_id": "d4e5f6g7-8901-4b23-d456-2c3d4e5f4444",
        "query": "Is the provider's name and credential listed at the end of the note?",
        "question_type": "default",
        "severity": "Normal"
      },
      {
        "question_id": "e5f6g7h8-9012-4c34-e567-3d4e5f6g5555",
        "query": "Are follow-up care recommendations included, if applicable?",
        "question_type": "default",
        "severity": "Normal"
      },
      {
        "question_id": "f6g7h8i9-0123-4d45-f678-4e5f6g7h6666",
        "query": "Does the session narrative mention if the patient had any adverse reactions?",
        "question_type": "default",
        "severity": "Normal"
      }
    ]
  }
]

Here we can see the 23456 question set has the set_id e14b9f1a-1234-4a10-9a4f-1fd4c0dc1234.

To pull in audits with service code 23456 that have been created or updated in the past day we can use the /audits endpoint.

/audits is a paginated endpoint with a page size of up to 1000. If you plan to pull in more than 1000 audits at a time use the page parameter and iterate until no more audits are found.

url = "https://api.brellium.com/v1/audits"

payload = {
    "verbose": "true",
    "set_id": "e14b9f1a-1234-4a10-9a4f-1fd4c0dc1234",
    "pageSize": 10,
    "includeQuestionIds": "true",
    "includePeople": "true",
    "includeDisplayInfo": "true",
    "lastUpdatedStartDate": "2025-04-08T00:00:00.000Z",
    "lastUpdatedEndDate": "2025-04-09T00:00:00.000Z",
    "scoreLowerBound": 0,
    "scoreUpperBound": 1
}
headers = {
    "accept": "application/json",
    "content-type": "application/json",
    "authorization": "Bearer MY-GENERATED-JWT-TOKEN"
}

response = requests.post(url, data=payload, headers=headers)

const url = 'https://api.brellium.com/v1/audits';

const payload = {
  verbose: 'true',
  set_id: 'e14b9f1a-1234-4a10-9a4f-1fd4c0dc1234',
  pageSize: 10,
  includeQuestionIds: 'true',
  includePeople: 'true',
  includeDisplayInfo: 'true',
  lastUpdatedStartDate: '2025-04-08T00:00:00.000Z',
  lastUpdatedEndDate: '2025-04-09T00:00:00.000Z',
  scoreLowerBound: 0,
  scoreUpperBound: 1
};

const headers = {
  accept: 'application/json',
  'content-type': 'application/json',
  authorization: 'Bearer MY-GENERATED-JWT-TOKEN'
};

axios.post(url, payload, { headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });

curl -X POST https://api.brellium.com/v1/audits \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -H "authorization: Bearer MY-GENERATED-JWT-TOKEN" \
  -d '{
    "verbose": "true",
    "set_id": "e14b9f1a-1234-4a10-9a4f-1fd4c0dc1234",
    "pageSize": 10,
    "includeQuestionIds": "true",
    "includePeople": "true",
    "includeDisplayInfo": "true",
    "lastUpdatedStartDate": "2025-04-08T00:00:00.000Z",
    "lastUpdatedEndDate": "2025-04-09T00:00:00.000Z",
    "scoreLowerBound": 0,
    "scoreUpperBound": 1
}'

Here is a breakdown of the included fields:

verbose: include information on specific questions in the response
set_id: the question set to which the audit belongs
includeQuestionIds: include question ids in the response objects
includePeople: include information on people involved in the session
includeDisplayInfo: includes important information about the audit (service code, provider id, session id)
lastUpdatedStartDate and lastUpdatedEndDate: date range based on the last made update in Brellium. You can also use date of service (sessionStartDate, sessionEndDate) or audit date (auditStartDate, auditEndDate)
scoreLowerBound and scoreUpperBound: score range of audits to pull from

Full information on all available parameters is available in the documentation for this endpoint.

Here is an example response from this endpoint:

{
    "audit_id": "3f1d3fc1-6c9a-4e68-9af1-7dc1c6467e10",
    "status": "complete",
    "score": 0.4856,
    "display_info": [
      {
        "key": "code",
        "order": 0,
        "title": "Code",
        "value": "23456",
        "format": "text",
        "filter_type": "boxes"
      },
      {
        "key": "provider_id",
        "order": 1,
        "title": "Provider ID",
        "value": "172372",
        "format": "text",
        "filter_type": "boxes"
      },
      {
        "key": "session_id",
        "order": 2,
        "title": "Session ID",
        "value": "M23283749",
        "format": "text",
        "filter_type": "boxes"
      }
    ],
    "flags": [
      "Failed",
      "Critical Error"
    ],
    "reviewed_by": "",
    "set_id": "e14b9f1a-1234-4a10-9a4f-1fd4c0dc1234",
    "timestamp": "2025-04-08T00:02:26.372Z",
    "last_updated": "2025-04-08T00:03:10.867Z",
    "people": [
      {
        "key": "patient",
        "order": 0,
        "title": "Patient",
        "value": "John Doe",
        "format": "text",
        "filter_type": "people"
      },
      {
        "key": "provider",
        "order": 1,
        "title": "Provider",
        "value": "Sam Jones",
        "format": "text",
        "filter_type": "people"
      },
    ],
    "responses": [
      {
        "response_id": "2a4d8a2d-d541-4b65-948e-6b5419f81a5c",
        "query": "Does the session narrative only contain information relevant to the session?",
        "answer": "No",
        "context": "The session narrative mentions a patient who is not marked as present during the session.",
        "question_id": "a1b2c3d4-5678-4e9f-a123-9f4cde0a1111"
      },
      {
        "response_id": "aaeeb230-91d0-4a0b-9497-86a5c4c41b2e",
        "query": "Are patient symptoms clearly documented with time of onset?",
        "answer": "Yes",
        "context": "The session narrative indicates the patient experienced fatigue at 2:13 pm.",
        "question_id": "b2c3d4e5-6789-4f01-b234-0a1b2c3d2222"
      },
      {
        "response_id": "7b92a9ac-71aa-41c6-b5d1-332cb8d03d94",
        "query": "Is there a note of any medication administered during the session?",
        "answer": "Yes",
        "context": "Ibuprofen was given to the patient at 2:24 pm.",
        "question_id": "c3d4e5f6-7890-4a12-c345-1b2c3d4e3333"
      }
    ],
    "documents": [
      "cce6b5a3-8e10-4a8b-bc53-0198055eb5f7"
    ],
    "people_emails": [
      {
        "title": "Provider",
        "name": "Sam Jones",
        "email": "sjones@clinicx.com"
      },
    ]
  }

At this point the Clinic X can upsert the most up to date audit information to the session with session_id M23283749 or they can maintain an internal linking from the session_id to the audit_id 3f1d3fc1-6c9a-4e68-9af1-7dc1c6467e10 and manage upserts using this.

It is also valid to send notes to Brellium one at a time as part of your internal upload flow.

Webhooks

In special cases, we can trigger a clinic’s internal endpoints immediately following audit creation. If you need live updates, please reach out to your account manager.

Table of Contents