> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# List Qualification Sessions

GET https://dev-api.truemed.com/api/v1/qualification_sessions

Returns a paginated view of all Qualification Sessions associated with the API key used
in the request header, sorted by their `created_at` date. Optional search fields are provided
to aid in finding the session or sessions associated with a given user.

## Request Notes

Query Params:

- `status` (Optional): filter Qualification Sessions by status. The supported values
  and their meanings are listed in the parameter's description below.
- `page` (Optional): int - the page to retrieve, defaults to 1. 30 entries are
  returned per page.

## Response Notes

### Bad Request

HTTP Status: 400

If a field is missing or the request otherwise can't be processed, we'll return a 400 with
the following fields:

- **error**: Can be one of:
    - `ValidationError`: invalid request
- **message**: Details on how the request was invalid

Reference: https://developers.truemed.com/api-reference/qualification-sessions/list-qualification-session

## Authentication

- `x-truemed-api-key` header (required) — Sales channel API key for merchant server-to-server authentication

## Servers

- `https://dev-api.truemed.com` (Development server, default)
- `https://api.truemed.com` (Production server)

## Request

### Query parameters

- `page` (integer, optional) — Optional field indicating which page to access. Defaults to 1.
- `page_size` (integer, optional) — Optional field indicating the number of records per page. Defaults to 30.
- `user_id` (string, optional) — An optional user_id to search for.
- `status` (string, optional) — An optional filter to only return sessions with the given status. One of: - `pending` — The session was created; the shopper hasn't completed the survey yet. - `processing` — The shopper completed the survey and it is under review. - `approved` — The shopper holds a valid Letter of Medical Necessity covering the items in this order. - `rejected` — The shopper is ineligible for a Letter of Medical Necessity for the items in this order.
- `expires_at` (datetime, optional) — Filter by expiration date (YYYY-MM-DD format)
- `search` (string, optional) — Search across user name, email, user_business_id, utm, and external_user_id fields.

## Response

### 200

Successful response

- `qualification_sessions` (list of QualificationSessionResponse, required) — An array of qualification_session objects.
- `pagination` (PaginationBody, optional, nullable) — A pagination object with information about the current page, page size, total count, and last page.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (enum, required)
  - Allowed values: `TotalAmountInvalid`, `ValidationError`
- `message` (string, required)

### 404 Not Found Error

Not Found

- `error` (enum, required)
  - Allowed values: `NotFound`
- `message` (string, required)

### 405 Method Not Allowed Error

Method Not Allowed

- `error` (enum, required)
  - Allowed values: `MethodNotAllowed`
- `message` (string, required)

### 500 Internal Server Error

Internal Server Error

- `error` (enum, required)
  - Allowed values: `ServerError`
- `message` (string, required)

### 501 Not Implemented Error

Not Implemented

- `error` (enum, required)
  - Allowed values: `NotImplemented`
- `message` (string, required)

## Types

### QualificationSessionResponse

- `qualification_session_id` (string, required) — The id of the qualification session.
- `status` (enum, required) — The status of the qualification session. One of: - `pending` — The session was created; the shopper hasn't completed the survey yet. - `processing` — The shopper completed the survey and it is under review. - `approved` — The shopper holds a valid Letter of Medical Necessity covering the items in this order. - `rejected` — The shopper is ineligible for a Letter of Medical Necessity for the items in this order.
  - Allowed values: `pending`, `processing`, `approved`, `rejected`
- `charge_group_created_at` (datetime, optional, nullable) — When the charge group was created.
- `created_at` (datetime, optional, nullable) — When the qualification session was created.
- `customer_status` (string, optional, nullable) — The customer's status.
- `eligible_amount` (double, optional, nullable) — The eligible amount for this qualification.
- `email` (string, optional, nullable) — The email address of the consumer who completed the qualification session.
- `expires_at` (datetime, optional, nullable) — The datetime at which the Letter-of-Medical-Necessity expires (inclusive, UTC).
- `fee` (double, optional, nullable) — The fee amount for this qualification.
- `lmn_reviewed_at` (datetime, optional, nullable) — When the Letter of Medical Necessity was reviewed.
- `session_type` (string, optional, nullable) — The type of qualification session.
- `skus_param` (string, optional, nullable) — The SKUs parameter from the qualification session.
- `source` (string, optional, nullable) — The source provided in the qualification session redirect URL param.
- `stripe_invoice_id` (string, optional, nullable) — The Stripe invoice ID associated with this qualification.
- `stripe_invoice_number` (string, optional, nullable) — The Stripe invoice number.
- `stripe_invoice_paid_at` (datetime, optional, nullable) — When the Stripe invoice was paid.
- `user_business_id` (string, optional, nullable) — The user's business ID.
- `user_id` (string, optional, nullable) — The user_id provided in the qualification session redirect URL param.
- `user_name` (string, optional, nullable) — The user's name (may be null if PII is hidden).

### PaginationBody

- `count` (integer, required) — The total number of items associated with the provided API key.
- `current_page` (integer, required) — The page requested. If none was provided, this will default to 1.
- `last_page` (integer, required) — The last page. You can iterate through pages by providing integers up to last_page in the page parameter.
- `page_size` (integer, required) — The number of items per page applied to this response.

## Examples

**Response**

```json
{
  "qualification_sessions": [
    {
      "qualification_session_id": "string",
      "status": "pending",
      "charge_group_created_at": "2024-01-15T09:30:00Z",
      "created_at": "2024-01-15T09:30:00Z",
      "customer_status": "string",
      "eligible_amount": 1.1,
      "email": "string",
      "expires_at": "2024-01-15T09:30:00Z",
      "fee": 1.1,
      "lmn_reviewed_at": "2024-01-15T09:30:00Z",
      "session_type": "string",
      "skus_param": "string",
      "source": "string",
      "stripe_invoice_id": "string",
      "stripe_invoice_number": "string",
      "stripe_invoice_paid_at": "2024-01-15T09:30:00Z",
      "user_business_id": "string",
      "user_id": "string",
      "user_name": "string"
    }
  ],
  "pagination": {
    "count": 1,
    "current_page": 1,
    "last_page": 1,
    "page_size": 1
  }
}
```

**SDK Code**

```python
import requests

url = "https://dev-api.truemed.com/api/v1/qualification_sessions"

headers = {"x-truemed-api-key": "<apiKey>"}

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

print(response.json())
```

```javascript
const url = 'https://dev-api.truemed.com/api/v1/qualification_sessions';
const options = {method: 'GET', headers: {'x-truemed-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```