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

# List Closeout Events

> Query and poll the history of completed verification closeout events

# List Closeout Events

Not to be confused with [Closeout endpoint configuration](/api-reference/schemas/closeout-endpoints), which configures **where** closeout webhooks are sent — this endpoint lets you **query/poll** closeout event history after the fact.

Returns verification results for searches that have reached `COMPLETED` status, with cursor-based pagination and optional filtering. Useful for polling or reconciling closeout activity instead of (or in addition to) relying on webhooks.

<Note>
  This route intentionally lives under the shorter `/v1/` prefix rather than `/background-check/v1/` — it is a general audit/polling API, not a background-check-specific route. See [API versioning](/api-reference/background-check/overview#api-versioning).
</Note>

## Request

<ParamField query="searchId" type="string">
  Filter to closeout events for a specific search ID.
</ParamField>

<ParamField query="verificationId" type="string">
  Filter to a specific verification result ID.
</ParamField>

<ParamField query="since" type="string">
  ISO 8601 timestamp. Only returns events last updated on or after this time.
</ParamField>

<ParamField query="limit" type="number">
  Maximum number of events to return. Defaults to `50`, capped at `200`.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque cursor for pagination — pass the last `eventId` from a previous page to fetch the next page.
</ParamField>

<Note>
  Prefer either `verificationId` **or** `cursor` for a given request. When both are supplied, the server uses the cursor pagination filter and may not apply `verificationId` as a separate filter.
</Note>

## Response

<ResponseField name="success" type="boolean">
  Always `true` for a successful request.
</ResponseField>

<ResponseField name="data" type="array">
  Array of closeout events, ordered by `updatedAt` descending.

  <Expandable title="Closeout Event Properties">
    <ResponseField name="eventId" type="string">Identifier for the event (the underlying verification result ID).</ResponseField>
    <ResponseField name="occurredAt" type="string">Timestamp the underlying verification result was last updated (ISO 8601).</ResponseField>
    <ResponseField name="searchId" type="string">Owning search identifier (UUID).</ResponseField>
    <ResponseField name="verificationId" type="string">Verification result identifier (same value as `eventId`).</ResponseField>
    <ResponseField name="status" type="string">Always `"COMPLETED"` — only completed searches produce closeout events.</ResponseField>
    <ResponseField name="summary" type="string">Generated human-readable summary of the closeout, e.g. search type and display name.</ResponseField>

    <ResponseField name="verificationResult" type="object">
      Detailed verification result.

      <Expandable title="verificationResult Properties">
        <ResponseField name="outcome" type="string">Terminal outcome, e.g. `VERIFIED`, `NO_RECORD`.</ResponseField>
        <ResponseField name="resultDetails" type="string">Human-readable summary of findings.</ResponseField>
        <ResponseField name="fullVerification" type="object">Structured extracted verification data. May be `null`.</ResponseField>
        <ResponseField name="discrepancy" type="boolean">Whether a discrepancy was detected. May be `null`.</ResponseField>
        <ResponseField name="submittedAt" type="string">When the inbound result was submitted. May be `null`.</ResponseField>
        <ResponseField name="createdAt" type="string">Result creation timestamp.</ResponseField>
        <ResponseField name="updatedAt" type="string">Result last-update timestamp.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination Properties">
    <ResponseField name="total" type="number">Total number of completed closeout events matching your filters (ignores `cursor`/`limit`).</ResponseField>
    <ResponseField name="limit" type="number">The effective limit applied to this request (after the 200 cap).</ResponseField>
    <ResponseField name="offset" type="number">`0` when paginating by page (no `cursor` supplied). Omitted from the response entirely when a `cursor` is supplied, since cursor-based pagination doesn't use offsets.</ResponseField>
    <ResponseField name="hasMore" type="boolean">Whether more events exist beyond this page.</ResponseField>
  </Expandable>
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -sS -X GET "https://sandbox.theary.ai/v1/closeout-events?limit=50" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "Accept: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://sandbox.theary.ai/v1/closeout-events?limit=50', {
    method: 'GET',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
  })

  const result = await response.json()
  ```

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

  response = requests.get(
      'https://sandbox.theary.ai/v1/closeout-events',
      params={'limit': 50},
      headers={
          'Authorization': 'Bearer YOUR_JWT_TOKEN',
          'Content-Type': 'application/json',
      },
  )

  result = response.json()
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "eventId": "123e4567-e89b-12d3-a456-426614174004",
      "occurredAt": "2026-01-16T15:00:00.000Z",
      "searchId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "verificationId": "123e4567-e89b-12d3-a456-426614174004",
      "status": "COMPLETED",
      "summary": "employment verification completed for Acme Corp - Status: Completed",
      "verificationResult": {
        "outcome": "VERIFIED",
        "resultDetails": "Employment verified: John Smith worked as Senior Software Engineer at Acme Corp from 2020-01-15 to 2023-06-30.",
        "fullVerification": { "position": "Senior Software Engineer", "salaryConfirmed": true },
        "discrepancy": false,
        "submittedAt": "2026-01-16T15:00:00.000Z",
        "createdAt": "2026-01-16T15:00:00.000Z",
        "updatedAt": "2026-01-16T15:00:00.000Z"
      }
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}
```

## Error Responses

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "statusCode": 401,
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

## Use Cases

* **Polling/reconciliation**: Periodically poll for newly completed closeouts using `since` or `cursor` as an alternative or backstop to webhooks.
* **Auditing**: Retrieve the full closeout history for a specific `searchId` or `verificationId`.


## OpenAPI

````yaml GET /v1/closeout-events
openapi: 3.0.0
info:
  title: SNH AI Background Check API
  description: >-
    AI-powered agentic background verification service for employment and
    education checks.
  version: '1.0'
  contact: {}
servers:
  - url: https://sandbox.theary.ai
    description: Sandbox
  - url: https://api.theary.ai
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - bearerAuth: []
tags: []
paths:
  /v1/closeout-events:
    get:
      tags:
        - Closeout Events
      summary: Get closeout events
      description: Returns all IDs with closeout events, supports pagination and filtering
      operationId: get-closeout-events
      parameters:
        - name: searchId
          required: false
          in: query
          description: Filter by specific search ID
          schema:
            type: string
        - name: verificationId
          required: false
          in: query
          description: Filter by specific verification ID
          schema:
            type: string
        - name: since
          required: false
          in: query
          description: ISO timestamp to filter events since (ISO string)
          schema:
            type: string
        - name: limit
          required: false
          in: query
          description: Maximum number of events to return (default 50, max 200)
          schema:
            type: number
        - name: cursor
          required: false
          in: query
          description: Cursor for pagination
          schema:
            type: string
      responses:
        '200':
          description: List of closeout events
          content:
            application/json:
              schema:
                type: object
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      scheme: bearer
      bearerFormat: JWT
      type: http

````