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

> List background check orders for specific tenant

# List Background Check Orders

Retrieves a paginated list of background check orders for a specific authenticated tenant.

## Request

<ParamField query="page" type="string">
  Page number for pagination (1-based). Defaults to `1` when omitted.
</ParamField>

<ParamField query="limit" type="string">
  Number of orders per page. Defaults to `10` when omitted.
</ParamField>

## Response

<ResponseField name="orders" type="array">
  Array of verification order objects. Each order includes its `applicant` (scalar fields) and its `search` array.

  <Expandable title="Order Properties">
    <ResponseField name="id" type="string">
      Order identifier (UUID).
    </ResponseField>

    <ResponseField name="applicantId" type="string">
      Applicant identifier (UUID).
    </ResponseField>

    <ResponseField name="proposedPosition" type="string">
      Applied job title (from `businessContext.appliedJobTitle`). May be `null`.
    </ResponseField>

    <ResponseField name="proposedSalary" type="number">
      Proposed salary (from `businessContext.proposedSalary`). May be `null`.
    </ResponseField>

    <ResponseField name="orderStatus" type="string">
      Order status: `IN_PROGRESS`, `COMPLETED`, or `CANCELLED`.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Order creation timestamp (ISO 8601).
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      Last update timestamp (ISO 8601).
    </ResponseField>

    <ResponseField name="applicant" type="object">
      Applicant scalar fields (`id`, `firstName`, `lastName`, `ssn`, `birthday`, `phone`, `email`, `isRedacted`, `createdAt`, `updatedAt`).
    </ResponseField>

    <ResponseField name="search" type="array">
      Summary of searches on the order (identifiers and status). Does **not** include `verificationResult`. To load results, call [Get order searches](/api-reference/endpoints/get-order-searches) for a specific order.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata

  <Expandable title="Pagination Properties">
    <ResponseField name="page" type="number">
      Current page number.
    </ResponseField>

    <ResponseField name="limit" type="number">
      Number of items per page.
    </ResponseField>

    <ResponseField name="total" type="number">
      Total number of orders for the organization.
    </ResponseField>

    <ResponseField name="totalPages" type="number">
      Total number of pages.
    </ResponseField>

    <ResponseField name="hasNext" type="boolean">
      Whether a next page exists.
    </ResponseField>

    <ResponseField name="hasPrev" type="boolean">
      Whether a previous page exists.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  `page` and `limit` are query strings that default to `1` and `10`. Results are ordered by `createdAt` descending.
</Note>

<Note>
  `isRedacted` (on `applicant`) indicates the applicant's PII (SSN, address, and similar fields) has been redacted from the record. See [Data handling and privacy](/getting-started/data-retention) for details.
</Note>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -sS -X GET "https://sandbox.theary.ai/background-check/v1/orders?page=1&limit=20" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "Accept: application/json"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://sandbox.theary.ai/background-check/v1/orders?page=1&limit=20', {
    method: 'GET',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
  })

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

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

  headers = {
      'Authorization': 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json'
  }

  response = requests.get(
      'https://sandbox.theary.ai/background-check/v1/orders',
      params={'page': 1, 'limit': 20},
      headers=headers
  )

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

## Example Response

```json theme={null}
{
  "orders": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "applicantId": "789e4567-e89b-12d3-a456-426614174002",
      "proposedPosition": "Senior Software Engineer",
      "proposedSalary": 100000,
      "orderStatus": "COMPLETED",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-16T14:45:00Z",
      "applicant": {
        "id": "789e4567-e89b-12d3-a456-426614174002",
        "firstName": "John",
        "lastName": "Smith",
        "ssn": "123-45-6789",
        "birthday": "1990-05-15",
        "phone": "+1-555-123-4567",
        "email": "john.smith@example.com",
        "isRedacted": false,
        "createdAt": "2026-01-15T10:30:00Z",
        "updatedAt": "2026-01-15T10:30:00Z"
      },
      "search": [
        {
          "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "orderId": "550e8400-e29b-41d4-a716-446655440000",
          "searchType": "EMPLOYMENT",
          "searchStatus": "COMPLETED",
          "externalSearchId": "client-emp-001"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  }
}
```


## OpenAPI

````yaml GET /background-check/v1/orders
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:
  /background-check/v1/orders:
    get:
      tags:
        - Background Check Orders
      summary: List verification orders
      description: Retrieves a paginated list of verification orders
      operationId: list-orders
      parameters:
        - name: page
          required: true
          in: query
          schema:
            type: string
        - name: limit
          required: true
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Paginated list of verification orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    items:
                      $ref: '#/components/schemas/OrderResponse'
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      total:
                        type: integer
                      totalPages:
                        type: integer
                      hasNext:
                        type: boolean
                      hasPrev:
                        type: boolean
        '401':
          description: Missing or invalid Bearer JWT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    OrderResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Order identifier
        applicantId:
          type: string
          format: uuid
          description: Applicant identifier
        proposedPosition:
          type: string
          nullable: true
          description: Applied job title
        proposedSalary:
          type: number
          nullable: true
          description: Proposed salary
        orderStatus:
          type: string
          enum:
            - IN_PROGRESS
            - COMPLETED
            - CANCELLED
          description: Current order status
        createdAt:
          type: string
          format: date-time
          description: Order creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
      title: Order Response
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          description: HTTP status code
          example: 400
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: Error message or array of validation error messages
          example: Validation failed
        error:
          type: string
          description: HTTP status text
          example: Bad Request
      required:
        - statusCode
        - message
      title: Error Response
  securitySchemes:
    bearerAuth:
      scheme: bearer
      bearerFormat: JWT
      type: http

````