# Sessions API

View and manage pre-screening sessions. Sessions are created when prospects complete your public chat workflows (e.g., pre-screening questionnaires). Each session contains the prospect's submission data and can be approved or denied.

## List Sessions

```
GET /api/v1/sessions
```

Returns a paginated list of pre-screening sessions.

**Query Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `page` | number | Page number (default: 1) |
| `limit` | number | Items per page (default: 20, max varies by plan) |
| `contactId` | uuid | Filter by contact |
| `workflowTemplateId` | uuid | Filter by workflow template |
| `status` | string | Filter: `active`, `completed`, `expired`, `draft` |
| `reviewStatus` | string | Filter: `pending_review`, `approved`, `denied` |

**Response:**

```json
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "contactId": "550e8400-e29b-41d4-a716-446655440000",
      "workflowTemplateId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "submission": {
        "fullName": "Jane Smith",
        "moveInDate": "2026-04-01",
        "budget": 2500,
        "pets": "1 cat"
      },
      "status": "completed",
      "reviewStatus": "pending_review",
      "reviewNotes": null,
      "reviewedAt": null,
      "createdAt": "2026-02-12T10:30:00Z",
      "updatedAt": "2026-02-12T10:45:00Z",
      "expiresAt": "2026-03-14T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 15,
    "totalPages": 1
  }
}
```

## Get Session

```
GET /api/v1/sessions/:id
```

Returns a single session by ID, including the full submission data.

## Review Session

```
PATCH /api/v1/sessions/:id/review
```

Approve or deny a completed pre-screening session. Only sessions with `status: "completed"` and `reviewStatus: "pending_review"` can be reviewed.

**Request Body:**

```json
{
  "reviewStatus": "approved",
  "reviewNotes": "Strong candidate, good income verification"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `reviewStatus` | string | Yes | `approved` or `denied` |
| `reviewNotes` | string | No | Internal notes (max 2000 chars, not shown to prospect) |

**Response:** Returns the updated session object.

**Side effects:**
- If the prospect has an email on file, a notification email is sent informing them of the decision.
- Review is final — a session cannot be re-reviewed once approved or denied.

**Error codes:**
- `404` — Session not found
- `409` — Session has already been reviewed
- `422` — Session is not in `completed` status, or invalid request body

## Notes

- **Read-only creation** — sessions are created by prospects via public chat, not via the API.
- **Submission data** — the `submission` object contains key-value pairs from the pre-screening form. Keys depend on the workflow template configuration.
- **Sessions expire** — sessions have a 30-day TTL. Expired sessions remain queryable but cannot be reviewed.
- **Review notes are internal** — `reviewNotes` are not shown to the prospect. They see only the approval/denial status on their status page.