> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> One API for the full patient journey, from checkout through clinical review, fulfillment, and every refill after.

## Introduction

The OpenLoop Partners API is the clinical backend for consumer health. A single RESTful API carries a patient through the full journey: enrollment, intake, licensed clinical review, and every refill after. You keep your funnel, your design, and your customer relationship. We run the regulated clinical layer across weight management, sexual health and hair.

You do not orchestrate the workflow. You start it with a few calls and read what happened: a patient was approved, a subscription activated, a prescription was written, an order shipped. Webhook delivery is configured per customer today, so build the synchronous reads first — see [Events](https://openloop.mintlify.site/events.md).

## The patient journey

The same journey runs behind every program. You touch the stages that face your customer; the platform runs the clinical stages for you.

**1. Launch programs and products**

Define the programs you offer and the products and pricing behind them.

**2. Check availability**

Confirm a program can serve the patient before checkout.

**3. Collect intake**

Render the program questionnaire and submit the patient's responses.

**4. Clinical decision**

A licensed provider reviews the intake. The platform returns eligibility and, when cleared, a prescription.

**5. Enroll and subscribe**

Eligible patients enter the clinical relationship and a recurring plan.

**6. Fulfill and refill**

Orders ship, and the refill cycle keeps treatment flowing.

**7. Operate**

Notifications and audit history keep you and the patient informed; read order state from the API.

## Core Capabilities

> [card] Patient Management
>
> Create, retrieve, update, and manage patients and related persons, and manage consents

> [card] [Scheduling](https://openloop.mintlify.site/api-reference/scheduling-guide.md)
>
> Search provider availability, reserve a slot while the patient confirms, then book, reschedule, or cancel the appointment

> [card] Clinical Data
>
> Exchange encounters, observations, allergies, and clinical documents

> [card] Orders & Labs
>
> Submit lab requisitions, and track order status

## Integration Workflow

The happy path is a handful of API calls. Start the journey, then read what happened.

**1. Verify API Connection**

Test your credentials and confirm connectivity by listing patients.

> [!TIP]
>
> You should receive a 200 status code with a paginated response envelope.

**2. Enroll and collect intake**

Create the patient and submit the intake responses your funnel already gathered. We attach them to the clinical review.

> [!TIP]
>
> Ensure all required fields are properly formatted according to our [Data Standards](https://openloop.mintlify.site/api-reference/data-standards.md).

**3. Read status**

Read order state from the API. Webhook delivery is configured per customer today and is not self-serve.

## Data Standards

The API enforces strict data formatting and validation rules to ensure consistency and reliability. Review our comprehensive [Data Standards](https://openloop.mintlify.site/api-reference/data-standards.md) guide for:

* Field format requirements and validation patterns
* Date, phone, and email formatting rules
* Address and location data structures
* Complete examples for all field types

## Authentication

The Partners API uses the OAuth 2.0 **client credentials** flow (machine-to-machine). There is no static API key: you exchange your `client_id` and `client_secret` for a short-lived access token, then send that token as a Bearer token on every request.

### 1. Get your credentials

Your `client_id` and `client_secret` identify an **app client** that OpenLoop provisions for you during onboarding. Contact your OpenLoop partnership representative to have one issued.

> [!WARNING]
>
> Store credentials in environment variables. Never commit them to version control or expose them in client-side code.

### 2. Exchange credentials for a token

`audience` is a fixed identifier, not the host you call, and differs by environment — see [Obtain a service token](https://openloop.mintlify.site/auth/obtain-token.md) for more details.

```bash theme={null}
curl --request POST \
  --url https://api.openloophealth.com/v0.1/auth/token \
  --header 'content-type: application/json' \
  --data '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://api.openloophealth.com"
  }'
```

The token is returned in a `data` envelope and is short-lived (`expires_in` is in seconds):

```json theme={null}
{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiI...",
    "token_type": "Bearer",
    "expires_in": 300
  },
  "request_id": "1dc1fe12-f80f-408f-86a5-f5604d7568b1"
}
```

### 3. Call the API

Send the `access_token` as a Bearer token on every request. Cache it and refresh before it expires rather than requesting a new one per call.

```bash theme={null}
curl -H "Authorization: Bearer <access_token>" \
     https://api.openloophealth.com/v0.1/patients
```

> [!NOTE]
>
> The OpenLoop platform authenticates your credentials and routes each request for you.

This client-credentials flow issues a **service token** for your integration. To register and authenticate an individual user, see the [User Registration](https://openloop.mintlify.site/api-reference/user-registration-guide.md) guide.

## Response Format

All API responses follow a consistent JSON structure and include a `request_id` for traceability. List endpoints return a paginated envelope with `after`/`before` cursors:

**Walk until a response comes back with no `after`, not until a page comes back short.** A cursor field is omitted when there is no page that way, so the presence of `after` is what "there is more" means. A full page can still be the last one, and a short page can still be followed by another — stopping on a short page ends the walk early and silently drops rows, with no error to point at. `limit` is a page size, not part of the cursor: the same walk works if you change it mid-way.

```json List Response theme={null}
{
  "items": [
    {
      "id": "1a2b3c4d5e6f",
      "active": true,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    }
  ],
  "after": "eyJvZmZzZXQiOjEwMH0",
  "request_id": "3f2c9a1e-8b4d-4f6a-9c2e-1d5b7a8e4f3c"
}
```

```json Single Resource theme={null}
{
  "data": {
    "id": "1a2b3c4d5e6f",
    "active": true,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "request_id": "3f2c9a1e-8b4d-4f6a-9c2e-1d5b7a8e4f3c"
}
```

```json Error Response theme={null}
{
  "error": {
    "message": "Invalid input data",
    "error_code": "VALIDATION_ERROR"
  },
  "request_id": "3f2c9a1e-8b4d-4f6a-9c2e-1d5b7a8e4f3c"
}
```

## Need Help?

> [card] [Quick Start](https://openloop.mintlify.site/quickstart.md)
>
> Token, first call, first patient

> [card] [Best Practices](https://openloop.mintlify.site/best-practices.md)
>
> Error handling and optimization techniques

> [card] [Contact Support](mailto:developer-support@openloophealth.com)
>
> Reach the developer support team


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.