FHIR API Documentation

Draft Version 1.0 - April 2025

1. Introduction

This document guides developers integrating with the CareLaunch FHIR API to access case updates, including ServiceRequest, Task, and Patient resources. It follows FHIR R4 (v4.0.1) with custom extensions for CareLaunch-specific data.

2. Authentication and Authorization

This API uses OAuth 2.0 for secure access.

Authentication Process

Client Registration: Before accessing the API, your organization must be registered with to receive client credentials (client ID and client secret).
Token Request: Use your client credentials to request an access token from the authorization server.
API Access: Include the access token in the Authorization header of your API requests.

Authorization Scopes

The API uses scopes to control access to different resources. Common scopes include:

fhir/Patient.read: Read access to Patient resources
fhir/Task.read: Read access to Task resources
fhir/ServiceRequest.read: Read access to ServiceRequest resources

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: Invalid or expired token
403 Forbidden: Insufficient permissions for the requested resource
400 Bad Request: Malformed authentication request

3. API Overview

Base URL

The base URL for all API requests is determined by your CareLaunch account configuration.

API Versioning

The API currently implements FHIR R4 (v4.0.1). The version is included in the response headers and in the FHIR capability statement.

Rate Limits

[PLACEHOLDER: Rate limit information will be added in future versions of this documentation]

Pagination

[PLACEHOLDER: Pagination details will be added in future versions of this documentation]

Error Handling

The API returns standard HTTP status codes and FHIR OperationOutcome resources for errors:

200 OK: Request successful
400 Bad Request: Invalid request
401 Unauthorized: Authentication failure
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
500 Internal Server Error: Server error

Request/Response Formats

The API supports the following formats:

JSON (default): application/fhir+json or application/json+fhir or application/json
XML: application/fhir+xml

Specify your preferred format using the Accept header in your request.

4. Base FHIR Resources

This section describes the core FHIR resources used in the API for Payer organizations. These resources follow the FHIR R4 standard specifications with specific implementation details relevant to CareLaunch's case management system.

4.1 Service Requests

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 resources can be queried using 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)

6. Implementation Guide

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

6.1 Common Use Cases

6.1.1 Querying Service Requests Using Patient Identifiers

Payer organizations often need to retrieve service requests for a specific patient. This can be accomplished by querying the ServiceRequest resource using the patient's identifier.

Example: Retrieve all service requests for a patient

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

This request will return all ServiceRequest resources where the patient has the Medical Record Number (MRN) 12345.

6.1.2 Accessing Task Statuses and Updates

Tracking the status of tasks is a common requirement for Payer organizations 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.3 Viewing All Fields Associated with Tasks in Their Organization

Payer organizations need to access complete task information for their 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 will return all Patient resources that your organization has access to, based on your API key.

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() {
  const tokenEndpoint = 'https://auth.carelaunch.health/oauth2/token';
  
  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',
      'scope': 'fhir/Task.read fhir/Patient.read fhir/ServiceRequest.read'
    })
  });
  
  const tokenData = await response.json();
  return tokenData.access_token;
}

# Python example using requests
import requests

def get_access_token():
    token_endpoint = 'https://auth.carelaunch.health/oauth2/token'
    
    payload = {
        'grant_type': 'client_credentials',
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET',
        'scope': 'fhir/Task.read fhir/Patient.read fhir/ServiceRequest.read'
    }
    
    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();
  
  const response = await fetch(`https://api.carelaunch.health/fhir/Patient/${patientId}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/fhir+json'
    }
  });
  
  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}',
        'Accept': 'application/fhir+json'
    }
    
    response = requests.get(f'https://api.carelaunch.health/fhir/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();
  
  const response = await fetch(`https://api.carelaunch.health/fhir/Task/${taskId}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/fhir+json'
    }
  });
  
  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}',
        'Accept': 'application/fhir+json'
    }
    
    response = requests.get(f'https://api.carelaunch.health/fhir/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 Service Requests

Example: Search for service requests by patient and date range

// JavaScript example using fetch
async function searchServiceRequests(patientId, startDate, endDate) {
  const accessToken = await getAccessToken();
  
  const url = new URL('https://api.carelaunch.health/fhir/ServiceRequest');
  url.searchParams.append('patient', patientId);
  url.searchParams.append('authored', `ge${startDate}`);
  url.searchParams.append('authored', `le${endDate}`);
  
  const response = await fetch(url.toString(), {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Accept': 'application/fhir+json'
    }
  });
  
  const bundle = await response.json();
  
  console.log(`Found ${bundle.total || bundle.entry?.length || 0} service requests`);
  
  return bundle;
}

# Python example using requests
import requests

def search_service_requests(patient_id, start_date, end_date):
    access_token = get_access_token()
    
    headers = {
        'Authorization': f'Bearer {access_token}',
        'Accept': 'application/fhir+json'
    }
    
    params = {
        'patient': patient_id,
        'authored': [f'ge{start_date}', f'le{end_date}']
    }
    
    response = requests.get('https://api.carelaunch.health/fhir/ServiceRequest', headers=headers, params=params)
    bundle = response.json()
    
    print(f"Found {bundle.get('total', len(bundle.get('entry', [])))} service requests")
    
    return bundle

7. API Reference

7.1 Endpoints

The FHIR API provides the following endpoints:

Patient Endpoints

Endpoint	Method	Description
`/Patient`	GET	Search for patients
`/Patient/{id}`	GET	Retrieve a specific patient by ID

Task Endpoints

Endpoint	Method	Description
`/Task`	GET	Search for tasks
`/Task/{id}`	GET	Retrieve a specific task by ID

ServiceRequest Endpoints

Endpoint	Method	Description
`/ServiceRequest`	GET	Search for service requests
`/ServiceRequest/{id}`	GET	Retrieve a specific service request by ID

Metadata Endpoint

Endpoint	Method	Description
`/metadata`	GET	Retrieve the FHIR capability statement

7.2 Error Codes and Handling

The API uses standard HTTP status codes and FHIR OperationOutcome resources to communicate errors:

Common HTTP Status Codes

Code	Description	Handling Strategy
200	OK	Process the returned resource
400	Bad Request	Check request parameters and format
401	Unauthorized	Refresh authentication token
403	Forbidden	Verify permissions and scopes
404	Not Found	Verify resource ID or search parameters
500	Internal Server Error	Retry with exponential backoff

Error Response Format

Error responses follow the FHIR OperationOutcome format:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "processing",
      "details": {
        "text": "Error description"
      }
    }
  ]
}

Troubleshooting Guidance

Authentication Issues: Ensure your client credentials are correct and your token is valid
Resource Not Found: Verify the resource ID or search parameters
Permission Issues: Check that your API key has the necessary scopes
Rate Limiting: Implement retry logic with exponential backoff
Data Format Issues: Ensure your request follows the FHIR R4 specification

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
XML	Extensible Markup Language, a markup language for encoding documents
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.0	April 2025	Initial release of the API documentation

8.3 Additional Resources

Support Contacts

For technical support with the FHIR API, please contact:

Email: api-support@carelaunch.health
Documentation Portal: https://docs.carelaunch.health/
Hours: Monday-Friday, 9:00 AM - 5:00 PM Eastern Time

1. Introduction​

2. Authentication and Authorization​

Authentication Process​

Authorization Scopes​

Token Management​

Error Handling for Authentication​

3. API Overview​

Base URL​

API Versioning​

Rate Limits​

Pagination​

Error Handling​

Request/Response Formats​

4. Base FHIR Resources

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 Querying Service Requests Using Patient Identifiers​

Example: Retrieve all service requests for a patient​

6.1.2 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.3 Viewing All Fields Associated with Tasks in Their 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 Service Requests​

Example: Search for service requests by patient and date range​

7. API Reference

7.1 Endpoints​

Patient Endpoints​

Task Endpoints​

ServiceRequest Endpoints​

Metadata Endpoint​

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

Authorization Scopes

Token Management

Error Handling for Authentication

3. API Overview

Base URL

API Versioning

Rate Limits

Pagination

Error Handling

Request/Response Formats

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

Extension Structure

6.1 Common Use Cases

6.1.1 Querying Service Requests Using Patient Identifiers

Example: Retrieve all service requests for a patient

6.1.2 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.3 Viewing All Fields Associated with Tasks in Their 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 Service Requests

Example: Search for service requests by patient and date range

7.1 Endpoints

Patient Endpoints

Task Endpoints

ServiceRequest Endpoints

Metadata Endpoint

7.2 Error Codes and Handling

Common HTTP Status Codes

Error Response Format

Troubleshooting Guidance

8.1 Glossary

8.2 Change Log

8.3 Additional Resources

Support Contacts