> ## 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 Specific Search

> Retrieve one search with verification results and activity history

# Get Specific Search

Use this endpoint for a **single search in detail**: the same search fields and `verificationResult` as [Get order searches](/api-reference/endpoints/get-order-searches), plus the `activity` array (outbound and inbound communications).

Use [Get order](/api-reference/endpoints/get-order) for order-level status only. Use [Get order searches](/api-reference/endpoints/get-order-searches) when you need results for every search on the order without activity logs.

## Path Parameters

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

<ParamField path="searchId" type="string" required>
  Unique identifier of the specific search (UUID format)
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique search identifier (UUID format)
</ResponseField>

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

<ResponseField name="applicantId" type="string">
  Applicant identifier
</ResponseField>

<ResponseField name="externalSearchId" type="string">
  External system search identifier
</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 (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">
  URL to online verification questionnaire (if applicable). May be `null`.
</ResponseField>

<ResponseField name="questionnaireAccessCode" type="string">
  Access code for online questionnaire. 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
</ResponseField>

<ResponseField name="createdAt" type="string">
  Search creation timestamp
</ResponseField>

<ResponseField name="updatedAt" type="string">
  Last update timestamp
</ResponseField>

<ResponseField name="applicant" type="object">
  Complete applicant information
</ResponseField>

<Note>
  `isRedacted` (on `applicant`) — when `true`, PII fields have been cleared per your organization's data retention terms.
</Note>

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

<ResponseField name="activity" type="array">
  Array of activity records for this search.

  <Expandable title="Activity Properties">
    <ResponseField name="id" type="string">Activity identifier (UUID).</ResponseField>
    <ResponseField name="searchId" type="string">Owning search identifier (UUID).</ResponseField>
    <ResponseField name="applicantId" type="string">Applicant identifier (UUID).</ResponseField>
    <ResponseField name="contactId" type="string">Associated contact identifier (UUID), or `null`.</ResponseField>
    <ResponseField name="activityType" type="string">Type: `INBOUND` or `OUTBOUND`.</ResponseField>
    <ResponseField name="channel" type="string">Communication channel: `EMAIL`, `FAX`, `VOICE`, or `JSON`.</ResponseField>
    <ResponseField name="channelValue" type="string">Contact destination (email address, fax/phone number).</ResponseField>
    <ResponseField name="description" type="string">Activity description. May be `null`.</ResponseField>
    <ResponseField name="metadata" type="object">Channel-specific activity metadata. Defaults to `{}`.</ResponseField>
    <ResponseField name="createdAt" type="string">Activity timestamp (ISO 8601).</ResponseField>
    <ResponseField name="updatedAt" type="string">Last update timestamp (ISO 8601).</ResponseField>
  </Expandable>
</ResponseField>

## 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/6ba7b810-9dad-11d1-80b4-00c04fd430c8" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "Accept: application/json"
  ```

  ```javascript JavaScript theme={null}
  const orderId = '550e8400-e29b-41d4-a716-446655440000'
  const searchId = '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
  const response = await fetch(`/background-check/v1/orders/${orderId}/searches/${searchId}`, {
    method: 'GET',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
  })

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

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

  order_id = "550e8400-e29b-41d4-a716-446655440000"
  search_id = "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  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/{search_id}',
      headers=headers
  )

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

## Example Response

```json theme={null}
{
  "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "applicantId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
  "externalSearchId": "client-emp-001",
  "searchType": "EMPLOYMENT",
  "searchStatus": "COMPLETED",
  "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": "2026-01-16T14:30:00Z",
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-01-16T14: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": "123e4567-e89b-12d3-a456-426614174004",
      "searchId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "outcome": "VERIFIED",
      "resultDetails": "Employment verified: John Smith worked as Senior Software Engineer at Acme Corp from 2020-01-15 to 2023-06-30. Salary confirmed.",
      "fullVerification": { "position": "Senior Software Engineer", "salaryConfirmed": true },
      "discrepancy": false,
      "submittedAt": "2026-01-16T15:00:00Z",
      "createdAt": "2026-01-16T15:00:00Z",
      "updatedAt": "2026-01-16T15:00:00Z"
    }
  ],
  "activity": [
    {
      "id": "activity_789e4567-e89b-12d3-a456-426614174005",
      "searchId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "applicantId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
      "contactId": "contact_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "activityType": "OUTBOUND",
      "channel": "EMAIL",
      "channelValue": "hr@acme.example",
      "description": "Employment verification request sent",
      "metadata": {},
      "createdAt": "2026-01-15T11:00:00Z",
      "updatedAt": "2026-01-15T11:00:00Z"
    },
    {
      "id": "activity_012e4567-e89b-12d3-a456-426614174006",
      "searchId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "applicantId": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
      "contactId": "contact_1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "activityType": "INBOUND",
      "channel": "EMAIL",
      "channelValue": "hr@acme.example",
      "description": "Employment verification response received",
      "metadata": {},
      "createdAt": "2026-01-16T14:15:00Z",
      "updatedAt": "2026-01-16T14:15:00Z"
    }
  ]
}
```

### Search not found

```json theme={null}
{
  "error": "Search not found",
  "orderId": "550e8400-e29b-41d4-a716-446655440000",
  "searchId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
```

## When to use this vs other read endpoints

| Goal                                          | Endpoint                                                          |
| --------------------------------------------- | ----------------------------------------------------------------- |
| Order status / applicant overview             | [Get order](/api-reference/endpoints/get-order)                   |
| Results for **all** searches on the order     | [Get order searches](/api-reference/endpoints/get-order-searches) |
| One search **plus** outreach/inbound activity | **This endpoint**                                                 |

## Use Cases

* Audit who was contacted and which channel was used (`activity`)
* Troubleshoot a stuck search with outbound/inbound history
* Load a detail view for one `searchId` after listing searches
* Reconcile state after a webhook when you need activity context


## OpenAPI

````yaml GET /background-check/v1/orders/{id}/searches/{searchId}
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/{searchId}:
    get:
      tags:
        - Background Check Orders
      summary: Get specific search within order
      description: >-
        Retrieves a specific search within the context of an order, including
        verification results and activity history. Returns an error body with
        HTTP 200 if the search does not exist.
      operationId: get-order-search
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
            format: uuid
        - name: searchId
          required: true
          in: path
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: >-
            Search details with verification results and activity (or error body
            if not found — check for the `error` field)
          content:
            application/json:
              schema:
                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
                  verificationResult:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        searchId:
                          type: string
                          format: uuid
                        outcome:
                          $ref: '#/components/schemas/VerificationOutcome'
                        resultDetails:
                          type: string
                        fullVerification:
                          type: object
                          nullable: true
                        discrepancy:
                          type: boolean
                          nullable: true
                        submittedAt:
                          type: string
                          format: date-time
                          nullable: true
                        createdAt:
                          type: string
                          format: date-time
                        updatedAt:
                          type: string
                          format: date-time
                  activity:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        searchId:
                          type: string
                          format: uuid
                        applicantId:
                          type: string
                          format: uuid
                        contactId:
                          type: string
                          format: uuid
                          nullable: true
                        activityType:
                          type: string
                          enum:
                            - INBOUND
                            - OUTBOUND
                        channel:
                          type: string
                          enum:
                            - EMAIL
                            - FAX
                            - VOICE
                            - JSON
                        channelValue:
                          type: string
                        description:
                          type: string
                          nullable: true
                        metadata:
                          type: object
                        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
    VerificationOutcome:
      type: string
      enum:
        - VERIFIED
        - NO_RECORD
        - ACTION_REQUIRED
        - WRONG_ORG
        - THIRD_PARTY
      description: Terminal verification outcome
      title: Verification Outcome
    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

````