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

> List all searches on an order with status and verification results — the polling endpoint for outcomes

# Get Order Searches

Use this endpoint to **read search progress and verification results** for every search on an order. Prefer [webhooks](/webhooks/overview) for production completion; use this call when you need to poll or reconcile state.

This is different from [Get order](/api-reference/endpoints/get-order), which returns an order overview and only a **summary** of related searches (no `verificationResult`). This endpoint returns the full search list with outcomes.

For outreach and inbound **activity** on a single search, use [Get specific search](/api-reference/endpoints/get-specific-search).

## Path Parameters

<ParamField path="id" type="string" required>
  Unique identifier of the verification order (UUID format)
</ParamField>

## Response

Returns a **raw array** of search objects (not wrapped in `{ orders: ... }` or similar). Each search includes status, metadata, `applicant` (scalar fields), and `verificationResult` (empty while in progress; typically one entry when complete).

Unlike [Get order](/api-reference/endpoints/get-order), this response does **not** include order-level fields such as `orderStatus` or `proposedPosition`.

<ResponseField name="[]" type="array">
  Array of search objects

  <Expandable title="Search Object Properties">
    <ResponseField name="id" type="string">
      Unique search identifier (UUID).
    </ResponseField>

    <ResponseField name="orderId" type="string">
      Parent order identifier (UUID).
    </ResponseField>

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

    <ResponseField name="externalSearchId" type="string">
      External system search identifier (as submitted; may be `null`).
    </ResponseField>

    <ResponseField name="searchType" type="string">
      Type of search: `EMPLOYMENT` or `EDUCATION`.
    </ResponseField>

    <ResponseField name="searchStatus" type="string">
      Current status: `IN_PROGRESS`, `COMPLETED`, `CANCELLED`, or `REASSIGNED`.
    </ResponseField>

    <ResponseField name="displayName" type="string">
      Human-readable label for the search (e.g. the entity being verified). May be `null`.
    </ResponseField>

    <ResponseField name="displayValue" type="string">
      Secondary display value for the search. May be `null`.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Search-type-specific details captured at creation — e.g. claimed employer/institution, location, dates, salary, and derived fields. Shape varies by `searchType`. Defaults to `{}`.
    </ResponseField>

    <ResponseField name="additionalComments" type="string">
      Additional comments or notes for the search. May be `null`.
    </ResponseField>

    <ResponseField name="questionnaireUrl" type="string">
      Online questionnaire URL, if provided at creation. May be `null`.
    </ResponseField>

    <ResponseField name="questionnaireAccessCode" type="string">
      Access code for the online questionnaire, if provided. May be `null`.
    </ResponseField>

    <ResponseField name="signedReleaseFileUrl" type="string">
      Resolved signed release file URI stored on the search (`gs://` or HTTPS). May be `null`.
    </ResponseField>

    <ResponseField name="completedAt" type="string">
      Search completion timestamp, or `null` while in progress.
    </ResponseField>

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

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

    <ResponseField name="applicant" type="object">
      Applicant scalar fields (same shape as the order `applicant`).
    </ResponseField>

    <ResponseField name="verificationResult" type="array">
      Verification results for this search (0 or 1 entry — one result per search).

      <Expandable title="VerificationResult Properties">
        <ResponseField name="id" type="string">Result identifier (UUID).</ResponseField>
        <ResponseField name="searchId" type="string">Owning search identifier (UUID).</ResponseField>
        <ResponseField name="outcome" type="string">Terminal outcome, e.g. `VERIFIED`, `NO_RECORD`, `ACTION_REQUIRED`.</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">Creation timestamp.</ResponseField>
        <ResponseField name="updatedAt" type="string">Last update timestamp.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<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/550e8400-e29b-41d4-a716-446655440000/searches" \
    -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}/searches`, {
    method: 'GET',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
  })

  const searches = 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}/searches',
      headers=headers
  )

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

## Example Response

```json theme={null}
[
  {
    "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": "IN_PROGRESS",
    "displayName": "Acme Corp",
    "displayValue": "Senior Software Engineer",
    "metadata": {
      "employerName": "Acme Corp",
      "employerLocation": "Cupertino, CA",
      "startDate": "2020-01-15",
      "endDate": "2023-06-30"
    },
    "additionalComments": "Verify salary and job responsibilities",
    "questionnaireUrl": "https://verify.example.com/form/abc123",
    "questionnaireAccessCode": "ACCESS123",
    "signedReleaseFileUrl": "gs://verification-api-storage/tenants/acme/releaseForms/uuid.pdf",
    "completedAt": null,
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30: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"
    },
    "verificationResult": []
  },
  {
    "id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "applicantId": "789e4567-e89b-12d3-a456-426614174002",
    "externalSearchId": "client-edu-001",
    "searchType": "EDUCATION",
    "searchStatus": "COMPLETED",
    "displayName": "Stanford University",
    "displayValue": "Bachelor of Computer Science",
    "metadata": {
      "institutionName": "Stanford University",
      "institutionLocation": "Stanford, CA",
      "graduationDate": "2020-06-15"
    },
    "additionalComments": null,
    "questionnaireUrl": null,
    "questionnaireAccessCode": null,
    "signedReleaseFileUrl": null,
    "completedAt": "2026-01-14T15:45:00Z",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-14T15: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"
    },
    "verificationResult": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174004",
        "searchId": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
        "outcome": "VERIFIED",
        "resultDetails": "Degree verified successfully",
        "fullVerification": { "degree": "BS Computer Science", "graduationDate": "2020-06-15" },
        "discrepancy": false,
        "submittedAt": "2026-01-14T16:00:00Z",
        "createdAt": "2026-01-14T16:00:00Z",
        "updatedAt": "2026-01-14T16:00:00Z"
      }
    ]
  }
]
```

## When to use this vs Get order

| Goal                                                              | Endpoint                                                            |
| ----------------------------------------------------------------- | ------------------------------------------------------------------- |
| Overall order status and applicant summary                        | [Get order](/api-reference/endpoints/get-order)                     |
| Poll search status and pull `verificationResult` for all searches | **This endpoint**                                                   |
| Activity log (outbound/inbound) for one search                    | [Get specific search](/api-reference/endpoints/get-specific-search) |

## Use Cases

* Poll for verification outcomes when webhooks are unavailable or as a reconciliation fallback
* Display per-search status and results in your UI after create
* Confirm `searchStatus` / `outcome` after a `verification.completed` webhook
* Export search-level results for reporting without loading activity history


## OpenAPI

````yaml GET /background-check/v1/orders/{id}/searches
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}/searches:
    get:
      tags:
        - Background Check Orders
      summary: Get order searches
      description: >-
        Retrieves all searches associated with a verification order. Returns a
        raw array of search objects (not wrapped in an envelope).
      operationId: get-order-searches
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Array of search objects for the order
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    orderId:
                      type: string
                      format: uuid
                    applicantId:
                      type: string
                      format: uuid
                    externalSearchId:
                      type: string
                      nullable: true
                    searchType:
                      type: string
                      enum:
                        - EMPLOYMENT
                        - EDUCATION
                    searchStatus:
                      $ref: '#/components/schemas/SearchStatus'
                    displayName:
                      type: string
                      nullable: true
                    displayValue:
                      type: string
                      nullable: true
                    metadata:
                      type: object
                    completedAt:
                      type: string
                      format: date-time
                      nullable: true
                    createdAt:
                      type: string
                      format: date-time
                    updatedAt:
                      type: string
                      format: date-time
        '401':
          description: Missing or invalid Bearer JWT
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    SearchStatus:
      type: string
      enum:
        - IN_PROGRESS
        - COMPLETED
        - CANCELLED
        - REASSIGNED
      description: Current search status
      title: Search Status
    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

````