FHIR API Documentation

1. Introduction

This document guides developers integrating with the CareLaunch FHIR API. The API provides read-only access to FHIR R4 (v4.0.1) resources with custom extensions for CareLaunch-specific data. Creating, updating, or deleting resources through this API is not supported.

Audience: Technical teams at organizations integrating with CareLaunch systems.

Scope: Read access to clinical and administrative FHIR resources via a proxy backed by the CareLaunch FHIR store.

2. Authentication and Authorization

This API uses OAuth 2.0 for secure access.

Authentication Process

Client Registration: CareLaunch creates your API client. Email support@carelaunch.health with the organizations and resource types the client should read. CareLaunch sends you the client ID and client secret.
Token Request: Use your client credentials to request an access token from the token endpoint CareLaunch gives you.
API Access: Include the access token in the Authorization header of your API requests.

Access Control

Access is controlled per API client, not per OAuth scope. Platform Admins can review and change a client on the API Clients page, which is not shown for solo practices. Each client has:

Resources: the resource types the client can read. Each resource can have an optional Query (for example status=active) that is added to every search for that type.
Organizations: the organizations whose data the client can read. Results are always limited to these organizations, even if a request asks for others.
An on/off switch. A client that is turned off gets 401 Unauthorized.

Token Management

Access tokens are valid for a limited time (typically 1 hour)
When a token expires, you must request a new one
Store tokens securely and never expose them in client-side code

Error Handling for Authentication

Common authentication errors include:

401 Unauthorized: The Authorization header is missing, the token is invalid or expired, the request was not sent to your organization's API URL, or the API client is turned off or belongs to another organization.

3. API Overview

Base URL

The base URL is the API Url set under Configure API on the API Clients page. The API works out your organization from the host name of each request, so send every request to that exact host over HTTPS. A request to any other host gets 401 Unauthorized.

API Versioning

The API currently implements FHIR R4 (v4.0.1).

Pagination

Searches return a Bundle resource with type "searchset". Use _count to set the page size:

If you omit _count, a page has up to 20 entries.
A _count above 100 is lowered to 100.
A _count that is not a number is replaced with 10.

To get the next page, request the URL in the Bundle's next link. The API rewrites paging links to use your API URL. The Bundle's total is the number of entries on the current page, not the size of the whole result. When a Bundle has no next link, it is the last page.

Example:

GET [base]/Patient?_count=20

Error Handling

The API returns these HTTP status codes:

200 OK: Request successful
400 Bad Request: The resource type is not supported, the _revinclude value is not Observation:patient, or the FHIR store rejected the search
401 Unauthorized: See Error Handling for Authentication
500 Internal Server Error: The request could not be processed. This is also returned when your API client is not set up for the resource type you requested.

A read by ID that finds nothing, or finds a resource outside your client's organizations, returns 200 OK with an OperationOutcome instead of the resource. Check resourceType in the response.

Request/Response Format

Successful responses are FHIR JSON, sent with Content-Type: application/json whatever Accept header you send. XML is not supported. Some error responses are a short plain-text message instead of JSON (see Error Codes and Handling).

4. Base FHIR Resources

This section describes the core FHIR resources available through the API. These resources follow the FHIR R4 standard with specific implementation details relevant to CareLaunch's case management system.

Supported Resource Types

Use these resource type names in the URL. They are not case-sensitive.

Patient
Observation
Task
Questionnaire
Immunization
Goal
Communication
Flag
Medication
Procedure
Encounter
Condition

Any other resource type returns 400 Bad Request, including Practitioner and Appointment.

These resource types are planned but not available yet. Requests for them return 400 Bad Request today: ServiceRequest, QuestionnaireResponse, DiagnosticReport, DocumentReference, AllergyIntolerance, CarePlan, CareTeam, MedicationRequest, MedicationStatement, MedicationAdministration, MedicationDispense, SupplyRequest, and SupplyDelivery.

Your API client can read only the types listed under its Resources. A request for a supported type that is not on your client returns 500 Internal Server Error.

Reverse Includes

Add _revinclude=Observation:patient to a Patient search to also return the Observation resources that reference each patient. Any other _revinclude value returns 400 Bad Request.

4.1 Service Requests

note

ServiceRequest is planned but not available yet. Requests for it return 400 Bad Request today. This section describes the resource for reference.

Overview

Service Requests represent client referrals and are used to track outreach activities. They contain essential information about the referral and outreach process.

Resource Structure

The ServiceRequest resource follows the FHIR R4 ServiceRequest specification with the following key elements:

Element	Cardinality	Type	Description
id	0..1	id	Logical id of this artifact
identifier	0..*	Identifier	Business identifiers assigned to this service request
status	1..1	code	draft \| active \| on-hold \| revoked \| completed \| entered-in-error \| unknown
intent	1..1	code	order \| original-order \| reflex-order \| filler-order \| instance-order \| option
priority	0..1	code	routine \| urgent \| asap \| stat
subject	1..1	Reference(Patient)	Individual the service is ordered for
authoredOn	0..1	dateTime	Date request signed
requester	0..1	Reference	Who/what is requesting service
performer	0..*	Reference	Requested performer
reasonCode	0..*	CodeableConcept	Explanation/justification for service
note	0..*	Annotation	Comments

Search Parameters

ServiceRequest defines the following search parameters:

Name	Type	Description
_id	token	The logical resource id associated with the resource
identifier	token	Identifiers assigned to this order
patient	reference	Search by subject - a patient
status	token	draft \| active \| on-hold \| revoked \| completed \| entered-in-error \| unknown
authored	date	Date request signed

4.2 Tasks

Overview

Tasks represent activities that need to be performed as part of case management. All tasks will be exposed in the API and will include basic status updates in version 1.

Task State Machine

Tasks in FHIR follow a state machine with the following states:

Created: Initial state when a task is first created
Ready: Task has been assigned to an owner and is ready to be performed
In Progress: Work is being performed on the task
Completed: Task has been successfully completed
Failed: Task could not be completed due to an error
Cancelled: Task was terminated before completion due to external factors

Tasks can also be tracked using the business status field which can support a wide range of statuses.

Resource Structure

The Task resource follows the FHIR R4 Task specification with the following key elements:

Element	Cardinality	Type	Description
id	0..1	id	Logical id of this artifact
identifier	0..*	Identifier	Task Instance Identifier
instantiatesCanonical	0..1	canonical	Formal definition of task
basedOn	0..*	Reference	Request fulfilled by this task
code	0..1	CodeableConcept	Task Type
status	1..1	code	draft \| requested \| received \| accepted \| rejected \| ready \| cancelled \| in-progress \| on-hold \| failed \| completed \| entered-in-error
businessStatus	0..1	CodeableConcept	E.g. "Record Collection", "Case Complete"
intent	1..1	code	unknown \| proposal \| plan \| order \| original-order \| reflex-order \| filler-order \| instance-order \| option
priority	0..1	code	routine \| urgent \| asap \| stat
description	0..1	string	Human-readable explanation of task
focus	0..1	Reference	What task is acting on
for	0..1	Reference	Beneficiary of the Task
authoredOn	0..1	dateTime	Task Creation Date
lastModified	0..1	dateTime	Task Last Modified Date
requester	0..1	Reference	Who is asking for task to be done
owner	0..1	Reference	Responsible individual
note	0..*	Annotation	Comments made about the task
input	0..*	BackboneElement	Information used to perform task
output	0..*	BackboneElement	Information produced as part of task

Search Parameters

Task resources can be queried using the following search parameters:

Name	Type	Description
_id	token	The logical resource id associated with the resource
identifier	token	Search for a task instance by its identifier
status	token	Search for tasks with a specific status
patient	reference	Search by patient
owner	reference	Search by task owner
requester	reference	Search by task requester
focus	reference	Search by task focus
authored-on	date	Search by creation date
modified	date	Search by last update date

4.3 Patient Resources

Overview

Patient resources contain demographics and identifiers for individuals receiving care or services. Patient identifiers can be used for querying.

Resource Structure

The Patient resource follows the FHIR R4 Patient specification with the following key elements:

Element	Cardinality	Type	Description
id	0..1	id	Logical id of this artifact
identifier	0..*	Identifier	An identifier for this patient
active	0..1	boolean	Whether this patient's record is in active use
name	0..*	HumanName	A name associated with the patient
telecom	0..*	ContactPoint	A contact detail for the individual
gender	0..1	code	male \| female \| other \| unknown
birthDate	0..1	date	The date of birth for the individual
address	0..*	Address	An address for the individual
contact	0..*	BackboneElement	A contact party (e.g. guardian, partner, friend) for the patient
communication	0..*	BackboneElement	A language which may be used to communicate with the patient about his or her health
generalPractitioner	0..*	Reference	Patient's nominated primary care provider
managingOrganization	0..1	Reference	Organization that is the custodian of the patient record

Search Parameters

Patient resources can be queried using the following search parameters:

Name	Type	Description
_id	token	The logical resource id associated with the resource
identifier	token	A patient identifier
name	string	A portion of either family or given name of the patient
gender	token	Gender of the patient
birthdate	date	The patient's date of birth
address	string	A server defined search that may include any of the string fields in the Address, including city, state, etc.
telecom	token	The value in any kind of telecom details of the patient
organization	reference	The organization that is the custodian of the patient record

5. Custom Extensions

FHIR extensions provide a standardized mechanism to add new elements to resources beyond what is defined in the core specification. Extensions are a fundamental part of the FHIR design, allowing implementations to include additional valid requirements without making the base specification overly complex.

Key characteristics of FHIR extensions:

Every element in a resource can have extension child elements
Extensions have a required URL that identifies the extension definition
Extensions can be either simple (with a value) or complex (with nested extensions)
Extensions cannot have both a value and nested extensions

Extension Structure

A basic extension in FHIR R4 has the following structure:

{
  "extension": [
    {
      "url": "http://example.org/fhir/StructureDefinition/some-extension",
      "valueType": "value"
    }
  ]
}

Where:

url: A URI that uniquely identifies the extension
valueType: The value of the extension, where "Type" is replaced by the actual data type (e.g., valueString, valueDateTime, valueCode)

Which CareLaunch extensions a resource carries, and their URLs, depend on how your organization's data is set up. The extension URLs in the examples below are placeholders. Check a response from your own API to find yours.

6. Implementation Guide

This section provides practical examples and guidance for implementing the FHIR API in common use cases.

6.1 Common Use Cases

6.1.1 Accessing Task Statuses and Updates

Tracking the status of tasks is a common way to monitor case progress.

Example: Retrieve all tasks for a specific patient with their current status

GET [base]/Task?patient.identifier=MRN|12345

This request will return all Task resources associated with the patient who has the Medical Record Number (MRN) 12345.

Example: Retrieve all completed tasks for a specific patient

GET [base]/Task?patient.identifier=MRN|12345&status=completed

This request will return all completed Task resources for the specified patient.

6.1.2 Viewing All Fields Associated with Tasks in Your Organization

You can retrieve complete task information for your patients.

Example: Retrieve a specific task with all its fields

GET [base]/Task/task-id

This request will return the complete Task resource with the specified ID, including all standard fields and extensions.

Example: Retrieve all patients in your organization

GET [base]/Patient

This request returns the Patient resources in the organizations your API client can read, one page at a time (see Pagination).

6.2 Implementation Examples

6.2.1 Authentication Example

Before making any API calls, you need to authenticate using OAuth 2.0. You will work with your CareLaunch representative to obtain your client credentials and authentication endpoint.

Example: Obtaining an access token

// JavaScript example using fetch
async function getAccessToken() {
  // Use the token endpoint provided by your CareLaunch representative
  const tokenEndpoint = 'YOUR_TOKEN_ENDPOINT';
  
  const response = await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      'grant_type': 'client_credentials',
      'client_id': 'YOUR_CLIENT_ID',
      'client_secret': 'YOUR_CLIENT_SECRET'
    })
  });
  
  const tokenData = await response.json();
  return tokenData.access_token;
}

# Python example using requests
import requests

def get_access_token():
    # Use the token endpoint provided by your CareLaunch representative
    token_endpoint = 'YOUR_TOKEN_ENDPOINT'
    
    payload = {
        'grant_type': 'client_credentials',
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET'
    }
    
    response = requests.post(token_endpoint, data=payload)
    token_data = response.json()
    return token_data['access_token']

6.2.2 Retrieving Patient Information

Example: Get patient details with custom extensions

// JavaScript example using fetch
async function getPatientWithExtensions(patientId) {
  const accessToken = await getAccessToken();
  
  // Use the API URL shown on your organization's API Clients page
  const response = await fetch(`YOUR_API_URL/Patient/${patientId}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });
  
  const patient = await response.json();
  
  // Extract custom extensions
  const subClientID = patient.extension?.find(ext => 
    ext.url === 'http://carelaunch.health/fhir/StructureDefinition/Patient-subClientID'
  )?.valueString;
  
  const subClientName = patient.extension?.find(ext => 
    ext.url === 'http://carelaunch.health/fhir/StructureDefinition/Patient-subClientName'
  )?.valueString;
  
  console.log(`Patient: ${patient.name[0].given.join(' ')} ${patient.name[0].family}`);
  console.log(`Sub-Client ID: ${subClientID || 'Not specified'}`);
  console.log(`Sub-Client Name: ${subClientName || 'Not specified'}`);
  
  return patient;
}

# Python example using requests
import requests

def get_patient_with_extensions(patient_id):
    access_token = get_access_token()
    
    headers = {
        'Authorization': f'Bearer {access_token}'
    }
    
    # Use the API URL shown on your organization's API Clients page
    response = requests.get(f'YOUR_API_URL/Patient/{patient_id}', headers=headers)
    patient = response.json()
    
    # Extract custom extensions
    sub_client_id = next((ext['valueString'] for ext in patient.get('extension', []) 
                         if ext['url'] == 'http://carelaunch.health/fhir/StructureDefinition/Patient-subClientID'), None)
    
    sub_client_name = next((ext['valueString'] for ext in patient.get('extension', []) 
                           if ext['url'] == 'http://carelaunch.health/fhir/StructureDefinition/Patient-subClientName'), None)
    
    print(f"Patient: {' '.join(patient['name'][0]['given'])} {patient['name'][0]['family']}")
    print(f"Sub-Client ID: {sub_client_id or 'Not specified'}")
    print(f"Sub-Client Name: {sub_client_name or 'Not specified'}")
    
    return patient

6.2.3 Retrieving Tasks with Custom Extensions

Example: Get task details with custom extensions

// JavaScript example using fetch
async function getTaskWithExtensions(taskId) {
  const accessToken = await getAccessToken();
  
  // Use the API URL shown on your organization's API Clients page
  const response = await fetch(`YOUR_API_URL/Task/${taskId}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });
  
  const task = await response.json();
  
  // Extract custom extensions
  const taskCompleteDate = task.extension?.find(ext => 
    ext.url === 'http://carelaunch.health/fhir/StructureDefinition/Task-TaskCompleteDate'
  )?.valueDateTime;
  
  const referDate = task.extension?.find(ext => 
    ext.url === 'http://carelaunch.health/fhir/StructureDefinition/Task-ReferDate'
  )?.valueDateTime;
  
  console.log(`Task: ${task.description || task.id}`);
  console.log(`Status: ${task.status}`);
  console.log(`Task Complete Date: ${taskCompleteDate || 'Not specified'}`);
  console.log(`Refer Date: ${referDate || 'Not specified'}`);
  
  return task;
}

# Python example using requests
import requests

def get_task_with_extensions(task_id):
    access_token = get_access_token()
    
    headers = {
        'Authorization': f'Bearer {access_token}'
    }
    
    response = requests.get(f'YOUR_API_URL/Task/{task_id}', headers=headers)
    task = response.json()
    
    # Extract custom extensions
    task_complete_date = next((ext['valueDateTime'] for ext in task.get('extension', []) 
                              if ext['url'] == 'http://carelaunch.health/fhir/StructureDefinition/Task-TaskCompleteDate'), None)
    
    refer_date = next((ext['valueDateTime'] for ext in task.get('extension', []) 
                      if ext['url'] == 'http://carelaunch.health/fhir/StructureDefinition/Task-ReferDate'), None)
    
    print(f"Task: {task.get('description', task['id'])}")
    print(f"Status: {task['status']}")
    print(f"Task Complete Date: {task_complete_date or 'Not specified'}")
    print(f"Refer Date: {refer_date or 'Not specified'}")
    
    return task

6.2.4 Searching for Tasks

Example: Search for a patient's tasks by status

// JavaScript example using fetch
async function searchTasks(patientId, status) {
  const accessToken = await getAccessToken();
  
  const url = new URL('YOUR_API_URL/Task');
  url.searchParams.append('patient', patientId);
  url.searchParams.append('status', status);
  
  const response = await fetch(url.toString(), {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });
  
  const bundle = await response.json();
  
  console.log(`Found ${bundle.entry?.length || 0} tasks on this page`);
  
  return bundle;
}

# Python example using requests
import requests

def search_tasks(patient_id, status):
    access_token = get_access_token()
    
    headers = {
        'Authorization': f'Bearer {access_token}'
    }
    
    params = {
        'patient': patient_id,
        'status': status
    }
    
    response = requests.get('YOUR_API_URL/Task', headers=headers, params=params)
    bundle = response.json()
    
    print(f"Found {len(bundle.get('entry', []))} tasks on this page")
    
    return bundle

7. API Reference

7.1 Endpoints

The FHIR API provides the following endpoints:

For every supported resource type (see Supported Resource Types), the API exposes two read-only endpoints:

Endpoint	Method	Description
`/{ResourceType}`	GET	Search for resources of this type
`/{ResourceType}/{id}`	GET	Retrieve a specific resource by ID

For example: /Patient, /Patient/{id}, /Task, /Task/{id}, /Observation, etc.

7.2 Error Codes and Handling

The API uses standard HTTP status codes. Some errors come with a FHIR OperationOutcome and some with a short plain-text message:

Common HTTP Status Codes

Code	Description	Handling Strategy
200	OK	Process the returned resource
400	Bad Request	Check the resource type, the `_revinclude` value, and the query parameters
401	Unauthorized	Request a new token, check that you are calling your API URL, and check that the API client is turned on
500	Internal Server Error	Check that your API client is set up for the resource type; otherwise retry with exponential backoff

Error Response Format

When the FHIR store rejects a search, and when a read by ID finds nothing, the response is an OperationOutcome:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "Error description"
    }
  ]
}

A 401, a 500, and a 400 for an unsupported resource type or _revinclude value return a short plain-text message, such as Unauthorized.

Troubleshooting Guidance

Authentication Issues: Ensure your client credentials are correct, your token is valid, and you are calling your organization's API URL
400 Bad Request: Verify the resource type is on the supported list and that query parameters are valid
500 errors or missing results: Check on the API Clients page that your client is turned on, lists the resource type under Resources, and has the right Organizations
A read by ID returns an OperationOutcome: The resource does not exist, or it belongs to an organization your client cannot read

8. Appendices

8.1 Glossary

Term	Definition
FHIR	Fast Healthcare Interoperability Resources, a standard for healthcare data exchange
R4	Release 4 of the FHIR standard (v4.0.1)
Extension	A mechanism in FHIR to add custom data elements to resources
Resource	A FHIR data structure representing a healthcare concept (e.g., Patient, Task)
OAuth 2.0	An authorization framework that enables third-party applications to obtain limited access to a service
API	Application Programming Interface
JSON	JavaScript Object Notation, a lightweight data-interchange format
REST	Representational State Transfer, an architectural style for distributed systems
URI	Uniform Resource Identifier, a string of characters used to identify a resource
URL	Uniform Resource Locator, a reference to a web resource

8.2 Change Log

Version	Date	Changes
1.1	October 2026	Updated to match the API: read-only access, API client access control, supported resource types, paging, and errors. Removed rate limits, XML, OAuth scopes, and the metadata endpoint, which the API does not support
1.0	May 2024	Initial release of the API documentation

8.3 Additional Resources

Support Contacts

For technical support with the FHIR API, please contact:

Email: support@carelaunch.health
Documentation Portal: https://docs.carelaunch.health/

For general inquiries, please contact your account manager or email sales@carelaunch.health.

1. Introduction​

2. Authentication and Authorization​

Authentication Process​

Access Control​

Token Management​

Error Handling for Authentication​

3. API Overview​

Base URL​

API Versioning​

Pagination​

Error Handling​

Request/Response Format​

4. Base FHIR Resources​

Supported Resource Types​

Reverse Includes​

4.1 Service Requests​

Overview​

Resource Structure​

Search Parameters​

4.2 Tasks​

Overview​

Task State Machine​

Resource Structure​

Search Parameters​

4.3 Patient Resources​

Overview​

Resource Structure​

Search Parameters​

5. Custom Extensions​

Extension Structure​

6. Implementation Guide​

6.1 Common Use Cases​

6.1.1 Accessing Task Statuses and Updates​

Example: Retrieve all tasks for a specific patient with their current status​

Example: Retrieve all completed tasks for a specific patient​

6.1.2 Viewing All Fields Associated with Tasks in Your Organization​

Example: Retrieve a specific task with all its fields​

Example: Retrieve all patients in your organization​

6.2 Implementation Examples​

6.2.1 Authentication Example​

Example: Obtaining an access token​

6.2.2 Retrieving Patient Information​

Example: Get patient details with custom extensions​

6.2.3 Retrieving Tasks with Custom Extensions​

Example: Get task details with custom extensions​

6.2.4 Searching for Tasks​

Example: Search for a patient's tasks by status​

7. API Reference​

7.1 Endpoints​

7.2 Error Codes and Handling​

Common HTTP Status Codes​

Error Response Format​

Troubleshooting Guidance​

8. Appendices​

8.1 Glossary​

8.2 Change Log​

8.3 Additional Resources​

Support Contacts​

1. Introduction

2. Authentication and Authorization

Authentication Process

Access Control

Token Management

Error Handling for Authentication

3. API Overview

Base URL

API Versioning

Pagination

Error Handling

Request/Response Format

4. Base FHIR Resources

Supported Resource Types

Reverse Includes

4.1 Service Requests

Overview

Resource Structure

Search Parameters

4.2 Tasks

Overview

Task State Machine

Resource Structure

Search Parameters

4.3 Patient Resources

Overview

Resource Structure

Search Parameters

5. Custom Extensions

Extension Structure

6. Implementation Guide

6.1 Common Use Cases

6.1.1 Accessing Task Statuses and Updates

Example: Retrieve all tasks for a specific patient with their current status

Example: Retrieve all completed tasks for a specific patient

6.1.2 Viewing All Fields Associated with Tasks in Your Organization

Example: Retrieve a specific task with all its fields

Example: Retrieve all patients in your organization

6.2 Implementation Examples

6.2.1 Authentication Example

Example: Obtaining an access token

6.2.2 Retrieving Patient Information

Example: Get patient details with custom extensions

6.2.3 Retrieving Tasks with Custom Extensions

Example: Get task details with custom extensions

6.2.4 Searching for Tasks

Example: Search for a patient's tasks by status

7. API Reference

7.1 Endpoints

7.2 Error Codes and Handling

Common HTTP Status Codes

Error Response Format

Troubleshooting Guidance

8. Appendices

8.1 Glossary

8.2 Change Log

8.3 Additional Resources

Support Contacts