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`
`reviewStatus`	string	Filter: `pending_review`, `approved`, `denied`

Response:


{
  "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:


{
  "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.