> ## 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 Search by External ID

> Look up searches for your tenant by external search ID

# Get Search by External ID

Looks up any searches belonging to the authenticated tenant that match the given `externalSearchId` (the `refId` you supplied, e.g. from your client system). Upstream integrators use this to avoid recreating or reprocessing a search that already exists for their tenant.

## Path Parameters

<ParamField path="externalSearchId" type="string" required>
  External search identifier to look up. Matched exactly as stored — the value is persisted as submitted on create and is **not** trimmed, so a stored value with leading/trailing spaces will only match an identical lookup value.
</ParamField>

## Response

<ResponseField name="exists" type="boolean">
  Whether any searches matched the given `externalSearchId`.
</ResponseField>

<ResponseField name="externalSearchId" type="string">
  Echo of the `externalSearchId` you looked up.
</ResponseField>

<ResponseField name="searches" type="array">
  Matching searches for your tenant, ordered by `createdAt` ascending. Empty array when none match.

  <Expandable title="Search Properties">
    <ResponseField name="id" type="string">Search identifier (UUID).</ResponseField>
    <ResponseField name="externalSearchId" type="string">External 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="createdAt" type="string">Search creation timestamp (ISO 8601).</ResponseField>
  </Expandable>
</ResponseField>

<Note>
  A blank or whitespace-only `externalSearchId` returns `{ exists: false, externalSearchId, searches: [] }` with HTTP `200` rather than an error.
</Note>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -sS -X GET "https://sandbox.theary.ai/background-check/v1/searches/by-external-id/client-emp-001" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "Accept: application/json"
  ```

  ```javascript JavaScript theme={null}
  const externalSearchId = 'client-emp-001'
  const response = await fetch(`https://sandbox.theary.ai/background-check/v1/searches/by-external-id/${externalSearchId}`, {
    method: 'GET',
    headers: {
      Authorization: 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json',
    },
  })

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

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

  external_search_id = "client-emp-001"
  headers = {
      'Authorization': 'Bearer YOUR_JWT_TOKEN',
      'Content-Type': 'application/json'
  }

  response = requests.get(
      f'https://sandbox.theary.ai/background-check/v1/searches/by-external-id/{external_search_id}',
      headers=headers
  )

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

## Example Response

```json theme={null}
{
  "exists": true,
  "externalSearchId": "client-emp-001",
  "searches": [
    {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "externalSearchId": "client-emp-001",
      "searchType": "EMPLOYMENT",
      "searchStatus": "COMPLETED",
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ]
}
```

**No match found:**

```json theme={null}
{
  "exists": false,
  "externalSearchId": "client-emp-999",
  "searches": []
}
```

## Error Responses

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

## Use Cases

* **Idempotency / dedupe**: Check whether a search already exists for your `externalSearchId` before creating a new order.
* **Reconciliation**: Look up the internal search state for a reference ID from your own system without needing the internal order/search UUIDs.


## OpenAPI

````yaml GET /background-check/v1/searches/by-external-id/{externalSearchId}
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/searches/by-external-id/{externalSearchId}:
    get:
      tags:
        - Searches
      summary: Look up searches by external search ID
      description: >-
        Returns any searches for the authenticated tenant matching the given
        externalSearchId. Used by upstream integrators to avoid recreating or
        processing a search that already exists for this tenant.
      operationId: get-by-external-search-id
      parameters:
        - name: externalSearchId
          required: true
          in: path
          description: External search identifier provided at order creation
          schema:
            type: string
      responses:
        '200':
          description: Lookup result
          content:
            application/json:
              schema:
                type: object
                required:
                  - exists
                  - externalSearchId
                  - searches
                properties:
                  exists:
                    type: boolean
                  externalSearchId:
                    type: string
                  searches:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        externalSearchId:
                          type: string
                        searchType:
                          type: string
                          enum:
                            - EMPLOYMENT
                            - EDUCATION
                        searchStatus:
                          type: string
                        createdAt:
                          type: string
                          format: date-time
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      scheme: bearer
      bearerFormat: JWT
      type: http

````