> ## 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.

# Quickstart

> Exchange client credentials for a bearer token, verify the connection, and create your first patient.

## Your first integration

This guide takes you from credentials to your first patient: get an access token, verify your connection, and create a patient.

## Prerequisites

Before you begin, ensure you have:

* **Client credentials** - a `client_id` and `client_secret` for an app client, issued by your OpenLoop partnership team
* **HTTP Client** - curl, Postman, or your preferred API testing tool
* **Basic API Knowledge** - Familiarity with RESTful APIs and JSON

> [!WARNING]
>
> Never commit your credentials to version control or share them publicly. Store the `client_id` and `client_secret` in environment variables.

**1. Get an Access Token**

The API uses the OAuth 2.0 client-credentials flow. Exchange your `client_id` and `client_secret` for a short-lived access token.

```bash cURL 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"
  }'
```

```javascript Node.js theme={null}
const res = await fetch('https://api.openloophealth.com/v0.1/auth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    grant_type: 'client_credentials',
    client_id: process.env.OPENLOOP_CLIENT_ID,
    client_secret: process.env.OPENLOOP_CLIENT_SECRET,
    audience: 'https://api.openloophealth.com',
  }),
});
const { data } = await res.json();
const accessToken = data.access_token;
```

```python Python theme={null}
import os, requests

res = requests.post(
    'https://api.openloophealth.com/v0.1/auth/token',
    json={
        'grant_type': 'client_credentials',
        'client_id': os.environ['OPENLOOP_CLIENT_ID'],
        'client_secret': os.environ['OPENLOOP_CLIENT_SECRET'],
        'audience': 'https://api.openloophealth.com',
    },
)
access_token = res.json()['data']['access_token']
```

**Response:**

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

> [!TIP]
>
> Tokens are short-lived (`expires_in` is in seconds). Cache the `access_token` and refresh it before it expires rather than requesting a new one per call.

**2. Verify Your Connection**

Confirm the token works with a simple authenticated read. Send the `access_token` as a Bearer token.

```bash cURL theme={null}
curl -H "Authorization: Bearer <access_token>" \
     "https://api.openloophealth.com/v0.1/questionnaires?status=active&limit=1"
```

```javascript Node.js theme={null}
const response = await fetch('https://api.openloophealth.com/v0.1/questionnaires?status=active&limit=1', {
  headers: { Authorization: `Bearer ${accessToken}` }
});

const data = await response.json();
console.log(data);
```

```python Python theme={null}
import requests

response = requests.get(
    'https://api.openloophealth.com/v0.1/questionnaires?status=active&limit=1',
    headers={'Authorization': f'Bearer {access_token}'}
)

print(response.json())
```

**Expected Response:** a `200` with the standard list envelope.

```json theme={null}
{
  "items": [
    { "id": "b1a7c1e2-3f4d-4a5b-8c9d-0e1f2a3b4c5d", "status": "active" }
  ],
  "request_id": "1dc1fe12-f80f-408f-86a5-f5604d7568b1"
}
```

> [!TIP]
>
> If you receive this response, your credentials are configured correctly and you're ready to proceed.

**3. Create Your First Patient**

Create a patient record with all required demographic and contact information.

```bash cURL theme={null}
curl -X POST https://api.openloophealth.com/v0.1/patients \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+14155552671",
    "birth_date": "1990-05-15",
    "gender": "male",
    "sex": "male",
    "locations": [{
      "address_line_1": "123 Main Street",
      "address_line_2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "zip_code": "10001",
      "default": true,
      "type": "home"
    }]
  }'
```

```json Success theme={null}
{
  "data": {
    "id": "3f2a9c14-8e7b-4d1a-9b2c-1e5f6a7d8c90",
    "email": "john.doe@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+14155552671",
    "birth_date": "1990-05-15",
    "created_at": "2024-12-02T10:30:00Z"
  },
  "request_id": "1dc1fe12-f80f-408f-86a5-f5604d7568b1"
}
```

> [!TIP]
>
> Save the `data.id` from the response. You'll need it for subsequent operations like updates.

## How Authentication Works

The Partners API authenticates every request with an OAuth 2.0 access token obtained through the client-credentials flow. There is no static API key.

1. **Exchange** your `client_id` / `client_secret` at `POST /v0.1/auth/token` for an `access_token`.
2. **Send** that token on every request in the `Authorization` header as `Bearer <access_token>`.
3. **Refresh** the token before it expires (`expires_in` seconds) and reuse it across requests in the meantime.

> [!NOTE]
>
> Your credentials map to an app client provisioned by OpenLoop, which determines what your integration can access. The platform authenticates and routes each request for you.

The patient record you just created is a clinical record, not a login. If your product needs the patient to sign in as their own user, see the [User Registration](https://openloop.mintlify.site/api-reference/user-registration-guide.md) guide.

## Next Steps

You're ready to build your integration! Explore these resources to learn more.

> [card] [Partner Cookbook](https://openloop.mintlify.site/cookbook/getting-started.md)
>
> Picks up here: the five calls that prove your tenant is provisioned, then intake

> [card] [API Reference](https://openloop.mintlify.site/api-reference)
>
> Explore all available endpoints, parameters, and response schemas

> [card] [Best Practices](https://openloop.mintlify.site/best-practices.md)
>
> Learn about error handling, data validation, and optimization techniques

> [card] [Contact Support](mailto:developer-support@openloophealth.com)
>
> Get help from our developer support team


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