---
title: "Search Inquiries"
method: POST
path: "/inquiries/search"
tags: ["inquiries"]
---

# Search Inquiries

`POST /inquiries/search`

## Request

- Base URL: `https://api.withpersona.com/api/v1`
- URL: `https://api.withpersona.com/api/v1/inquiries/search`
- Auth: HTTP bearer

Search for inquiries using a flexible query language.

## Search vs. List Endpoints

The Search and List endpoints serve different purposes and have distinct performance characteristics.

Use the **Search** endpoint (`POST /inquiries/search`) when you need to perform complex queries with boolean logic (AND/OR/NOT), filter on multiple statuses simultaneously, or apply multiple conditions at once. Search is optimized for flexible querying and is faster than paginating through all resources when looking for specific records.

Use the **List** endpoint (`GET /inquiries`) for simple listing with basic filters like reference ID.

## Data Freshness

Do not use search for read-after-write flows because the data will not be immediately available to search.
Under normal operating conditions, data is searchable within approximately 1 minute of creation or modification.
Propagation of new or updated data could be delayed during an outage.
For workflows that require immediate data availability after creating or updating an inquiry, use the List Inquiries endpoint instead.

### Searchable Attributes

The following attributes can be used in query predicates:

| Attribute | Description |
|-----------|-------------|
| `status` | Inquiry status (e.g., `pending`, `completed`, `approved`, `declined`) |
| `created_at` | Inquiry creation timestamp |
| `updated_at` | Inquiry last updated timestamp |
| `reference_id` | Reference ID associated with the inquiry's account |
| `inquiry_template_id` | Inquiry template ID (e.g., `itmpl_ABC123`) |

## Query parameters

- `fields` object
- `page` InquiriesSearchPostParametersPage
  - `after` string: Cursor for forward pagination. Use the value from `links.next` in the previous response.
  - `before` string: Cursor for backward pagination. Use the value from `links.prev` in the previous response.
  - `size` integer: Number of results to return per page.

## Headers

- `Key-Inflection` 'camel' | 'kebab' | 'snake'
- `Idempotency-Key` string
- `Persona-Version` '2026-09-29' | '2025-12-08' | '2025-10-27' | '2023-01-05' | '2022-09-01' | '2021-08-18' | '2021-07-05' | '2021-02-21' | '2020-05-18': Server API version. More info on versioning can be found [here](https://docs.withpersona.com/versioning).

## Request body

- InquiriesSearchInquiriesRequest
  - `query` union: Search query using boolean logic (AND/OR/NOT) and comparison operators. Supports predicates with operators: eq (equal), gt (greater than), gte (greater than or equal), lt (less than), lte (less than or equal).
    - InquiriesSearchPostRequestBodyContentApplicationJsonSchemaQuery0: Boolean AND clause - combines multiple conditions where ALL must be true. This clause is recursive: each item in the `and` array can be another AND, OR, NOT clause, or a leaf predicate, enabling complex nested queries. Maximum nesting depth: 2 levels, Maximum clauses per AND: 20
      - `and` object[], required
    - InquiriesSearchPostRequestBodyContentApplicationJsonSchemaQuery1: Boolean OR clause - combines multiple conditions where AT LEAST ONE must be true. This clause is recursive: each item in the `or` array can be another AND, OR, NOT clause, or a leaf predicate, enabling complex nested queries. Maximum nesting depth: 2 levels, Maximum clauses per OR: 20
      - `or` object[], required
    - InquiriesSearchPostRequestBodyContentApplicationJsonSchemaQuery2: Boolean NOT clause - negates a single condition. This clause is recursive: the `not` value can be another AND, OR, NOT clause, or a leaf predicate, enabling complex nested queries. Maximum nesting depth: 2 levels
      - `not` object, required
    - InquiriesSearchPostRequestBodyContentApplicationJsonSchemaQuery3: Attribute predicate
      - `attribute` string, required: The attribute name to filter on (e.g., 'status', 'created_at', 'reference_id', 'inquiry_template_id')
      - `operator` string, required: Comparison operator. Possible values: eq (equal), gt (greater than), gte (greater than or equal), lt (less than), lte (less than or equal).
      - `value` union, required: Value to compare against
        - string
        - number, double
        - boolean
  - `sort` InquiriesSearchPostRequestBodyContentApplicationJsonSchemaSort: Sort configuration for results
    - `attribute` string, required: The attribute name to sort by
    - `direction` string, required: Sort direction. Possible values: asc (ascending), desc (descending).
  - `page` InquiriesSearchPostRequestBodyContentApplicationJsonSchemaPage: Pagination parameters
    - `after` string: Cursor for forward pagination
    - `before` string: Cursor for backward pagination
    - `size` integer: Number of results to return per page

## Response `200`

This endpoint returns a collection of Inquiry objects matching the search criteria.

- InquiriesSearchInquiriesResponse200
  - `data` Inquiry[], required: An array of Inquiries matching the search criteria
    - `id` string, required
    - `attributes` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributes, required
      - `status` string, required: The status of the Inquiry Possible values: - created - pending - completed - expired - failed - needs_review - approved - declined Do not assume this is a static enumeration; Persona may add new values in the future without a versioned update.
      - `reference-id` string, nullable, required
      - `note` string, nullable, required
      - `behaviors` object, nullable, required: Risk signals surfaced to enterprise customers. Specific keys are not enumerated in the public spec and may be added or removed over time. Contact your Persona account team for more information.
      - `tags` string[], required
      - `creator` string, required
      - `reviewer-comment` string, nullable, required
      - `created-at` string, date-time, required
      - `updated-at` string, date-time, required
      - `started-at` string, date-time, nullable, required
      - `expires-at` string, date-time, nullable, required
      - `completed-at` string, date-time, nullable, required
      - `failed-at` string, date-time, nullable, required: Set when an Inquiry transitions to `failed`. Not typically set on `declined` Inquiries — those carry `completed-at` from the transition that preceded the decision.
      - `marked-for-review-at` string, date-time, nullable, required
      - `decisioned-at` string, date-time, nullable, required
      - `expired-at` string, date-time, nullable, required
      - `redacted-at` string, date-time, nullable, required
      - `previous-step-name` string, nullable, required
      - `next-step-name` string, nullable, required
      - `fields` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFields, required: JSON key-value pairs of field name to field value. Exact schema depends on the configuration of the Inquiry template for this Inquiry.
        - `name-first` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsNameFirst
          - `type` string
          - `value` string, nullable
        - `name-middle` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsNameMiddle
          - `type` string
          - `value` string, nullable
        - `name-last` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsNameLast
          - `type` string
          - `value` string, nullable
        - `address-street-1` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsAddressStreet1
          - `type` string
          - `value` string, nullable
        - `address-street-2` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsAddressStreet2
          - `type` string
          - `value` string, nullable
        - `address-city` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsAddressCity: City of residence address. Not all international addresses use this attribute.
          - `type` string
          - `value` string, nullable
        - `address-subdivision` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsAddressSubdivision: State or subdivision of residence address. In the US, this should be the unabbreviated name. Not all international addresses use this attribute.
          - `type` string
          - `value` string, nullable
        - `address-postal-code` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsAddressPostalCode: ZIP or postal code of residence address. Not all international addresses use this attribute.
          - `type` string
          - `value` string, nullable
        - `address-country-code` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsAddressCountryCode: ISO 3166-1 alpha 2 country code.
          - `type` string
          - `value` string, nullable
        - `birthdate` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsBirthdate
          - `type` string
          - `value` string, nullable: Date of birth in YYYY-MM-DD format
        - `email-address` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsEmailAddress
          - `type` string
          - `value` string, nullable
        - `phone-number` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsPhoneNumber
          - `type` string
          - `value` string, nullable
        - `driver-license-number` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsDriverLicenseNumber
          - `type` string
          - `value` string, nullable
        - `passport-number` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryAttributesFieldsPassportNumber
          - `type` string
          - `value` string, nullable
      - `birthdate` string, date, nullable: Birthdate, must be in the format "YYYY-MM-DD".
      - `name-first` string, nullable: Given or first name.
      - `name-middle` string, nullable: Middle name.
      - `name-last` string, nullable: Family or last name.
      - `phone-number` string, nullable: Phone number.
      - `email-address` string, nullable: Email address.
      - `social-security-number` string, nullable: Social security number.
      - `address-street-1` string, nullable: Street name of residence address.
      - `address-street-2` string, nullable: Extension of residence address, usually apartment or suite number.
      - `address-city` string, nullable: City of residence address. Not all international addresses use this attribute.
      - `address-subdivision` string, nullable: State or subdivision of residence address. In the US, this should be the unabbreviated name. Not all international addresses use this attribute.
      - `address-postal-code` string, nullable: ZIP or postal code of residence address. Not all international addresses use this attribute.
      - `address-subdivision-abbr` string, nullable
      - `address-postal-code-abbr` string, nullable
      - `identification-number` string, nullable
      - `reviewer` string, nullable: The email address or identifier of the reviewer who made the decision on this inquiry. For User reviewers, this is their email address. For Workflow reviewers, this is the workflow token. For API decisions, this is "api".
      - `reviewer-type` string, nullable: The type of reviewer who made the decision. Can be "user", "workflow", "workflow-run", or "api".
      - `driver-license-number` string, nullable
      - `passport-number` string, nullable
    - `relationships` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationships, required
      - `account` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsAccount
        - `data` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsAccountData
          - `id` string
          - `type` 'account'
      - `documents` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsDocuments
        - `data` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsDocumentsDataItems[]
          - `id` string
          - `type` string
      - `template` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsTemplate: Only present for Legacy 2.0 inquiries
        - `data` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsTemplateData
          - `id` string
          - `type` 'template'
      - `inquiry-template` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsInquiryTemplate: Only present for Dynamic Flow inquiries
        - `data` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsInquiryTemplateData
          - `id` string
          - `type` 'inquiry-template'
      - `inquiry-template-version` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsInquiryTemplateVersion: Only present for Dynamic Flow inquiries
        - `data` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsInquiryTemplateVersionData
          - `id` string
          - `type` 'inquiry-template-version'
      - `reports` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsReports
        - `data` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsReportsDataItems[]
          - `id` string
          - `type` string
      - `transaction` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsTransaction
        - `data` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsTransactionData
          - `id` string
          - `type` 'transaction'
      - `selfies` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsSelfies
        - `data` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsSelfiesDataItems[]
          - `id` string
          - `type` string
      - `sessions` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsSessions
        - `data` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsSessionsDataItems[]
          - `id` string
          - `type` 'inquiry-session'
      - `verifications` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsVerifications
        - `data` SelfieIncludedObjectsItemsDiscriminatorMappingInquiryRelationshipsVerificationsDataItems[]
          - `id` string
          - `type` string
  - `links` InquiriesSearchPostResponsesContentApplicationJsonSchemaLinks, required
    - `prev` string, nullable, required: URL pointing to the previous page of data, or null if on the first page. Must be used with POST request and original request body.
    - `next` string, nullable, required: URL pointing to the next page of data, or null if on the last page. Must be used with POST request and original request body.

## Other responses

- `400`: The request was unacceptable, often due to invalid parameters.
- `401`: An invalid API key was provided.
- `403`: The given API key doesn’t have permissions to perform the request or a quota has been exceeded.
- `404`: The requested resource doesn’t exist.
- `409`: The request conflicts with another request, often due to attempting to create a duplicate resource.
- `422`: The request modifies the resource in an unacceptable way, often due to an invalid action or parameter.
- `429`: Your organization’s rate limit has been exceeded. We recommend an exponential backoff on requests.

---

[API](https://skmtc.dev/withpersona/apis/withpersona-2.md) - [All operations](https://skmtc.dev/withpersona/apis/withpersona-2/llms.txt) - [OpenAPI document](https://skmtc.dev/withpersona/apis/withpersona-2/revisions/f1c78133b3b2?raw)