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

# Get Order

> Retrieve an order overview: status, applicant, and summary of related searches

# Get Background Check Order

Use this endpoint for an **order-level overview**: overall `orderStatus`, applicant identity fields, and a summary of the searches on the order.

It does **not** return verification outcomes. Nested `search` objects are status summaries only (for example `id`, `searchType`, `searchStatus`). To read results or poll progress, use [Get order searches](/api-reference/endpoints/get-order-searches). For outreach history on one search, use [Get specific search](/api-reference/endpoints/get-specific-search).

## Request

<ParamField path="id" type="string" required>
  Unique identifier of the background check order
</ParamField>

## Response

Returns the order with `applicant` (scalar fields) and a nested `search` array of **summary** search rows. If the order does not exist, returns `{ "error": "Order not found", "orderId": "<id>" }` with HTTP `200`.

<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 information (scalar fields only — nested addresses/aliases are not included on this endpoint).

  <Expandable title="Applicant Properties">
    <ResponseField name="id" type="string">Applicant identifier (UUID).</ResponseField>
    <ResponseField name="firstName" type="string">First name.</ResponseField>
    <ResponseField name="lastName" type="string">Last name.</ResponseField>
    <ResponseField name="ssn" type="string">Social Security Number.</ResponseField>
    <ResponseField name="birthday" type="string">Date of birth (`YYYY-MM-DD`), or `null`.</ResponseField>
    <ResponseField name="phone" type="string">Phone number, or `null`.</ResponseField>
    <ResponseField name="email" type="string">Email address, or `null`.</ResponseField>
    <ResponseField name="isRedacted" type="boolean">When `true`, PII fields on this record have been cleared per your organization's data retention terms.</ResponseField>
    <ResponseField name="createdAt" type="string">Creation timestamp.</ResponseField>
    <ResponseField name="updatedAt" type="string">Last update timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="search" type="array">
  Summary of searches on this order (status and identifiers). Does **not** include `verificationResult`, `metadata`, or `activity`. For those fields, call [Get order searches](/api-reference/endpoints/get-order-searches) or [Get specific search](/api-reference/endpoints/get-specific-search).
</ResponseField>

<Note>
  `isRedacted` 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>

## When to use this vs search endpoints

| Goal                                                         | Endpoint                                                            |
| ------------------------------------------------------------ | ------------------------------------------------------------------- |
| Is the **order** still in progress or finished?              | **This endpoint** (`GET /orders/{id}`)                              |
| What are the **verification results** for each search?       | [Get order searches](/api-reference/endpoints/get-order-searches)   |
| What outreach / inbound **activity** happened on one search? | [Get specific search](/api-reference/endpoints/get-specific-search) |

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -sS -X GET "https://sandbox.theary.ai/background-check/v1/orders/550e8400-e29b-41d4-a716-446655440000" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "Accept: application/json"
  ```

  ```javascript JavaScript theme={null}
  const orderId = '550e8400-e29b-41d4-a716-446655440000'
  const response = await fetch(`/background-check/v1/orders/${orderId}`, {
    method: 'GET',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
  })

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

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

  order_id = "550e8400-e29b-41d4-a716-446655440000"
  headers = {
      'Authorization': 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json'
  }

  response = requests.get(
      f'https://sandbox.theary.ai/background-check/v1/orders/{order_id}',
      headers=headers
  )

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

## Example Response

```json theme={null}
{
  "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",
      "applicantId": "789e4567-e89b-12d3-a456-426614174002",
      "externalSearchId": "client-emp-001",
      "searchType": "EMPLOYMENT",
      "searchStatus": "COMPLETED",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-16T14:45:00Z"
    }
  ]
}
```

### Order not found

```json theme={null}
{
  "error": "Order not found",
  "orderId": "550e8400-e29b-41d4-a716-446655440000"
}
```

## Use Cases

* Confirm an order was created and see its overall `orderStatus`
* Look up applicant identity fields for support or internal tooling
* See which searches exist on the order (IDs, types, statuses) without loading results
* Cancel or escalate workflows that only need order-level state

Do **not** use this endpoint as your primary poll for verification outcomes — use [Get order searches](/api-reference/endpoints/get-order-searches) or [webhooks](/webhooks/overview).


## OpenAPI

````yaml GET /background-check/v1/orders/{id}
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/{id}:
    get:
      tags:
        - Background Check Orders
      summary: Get specific order
      description: >-
        Retrieves details of a specific verification order including applicant
        and search data. Returns an error body with HTTP 200 if the order does
        not exist.
      operationId: get-order
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: >-
            Order details (or error body if not found — check for the `error`
            field)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '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

````