--- title: "Search Accounts" method: POST path: "/accounts/search" tags: ["accounts"] --- # Search Accounts `POST /accounts/search` ## Request - Base URL: `https://api.withpersona.com/api/v1` - URL: `https://api.withpersona.com/api/v1/accounts/search` - Auth: HTTP bearer Search for accounts 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 /accounts/search`) when you need to perform complex queries with boolean logic (AND/OR/NOT), filter by custom fields or identifiers, or apply multiple conditions simultaneously. Search is optimized for flexible querying and is faster than paginating through all resources when looking for specific records. Use the **List** endpoint (`GET /accounts`) 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 account, use the List Accounts endpoint instead. ### Searchable Attributes The following attributes can be used in query predicates: | Attribute | Description | |-----------|-------------| | `type` | Account type (e.g., `acttp_ABC123`) | | `status` | Account status (e.g., `actst_ABC123`) | | `created_at` | Account creation timestamp | | `updated_at` | Account last updated timestamp | | `identifiers.*` | Custom identifier (e.g., `identifiers.user_id`) | | `fields.*` | Custom account field (e.g., `fields.age`) | **Note:** Custom fields (`fields.*`) must be configured as searchable on the Account Type to be queryable. ## Query parameters - `fields` object - `page` AccountsSearchPostParametersPage - `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 - AccountsSearchAccountsRequest - `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). - AccountsSearchPostRequestBodyContentApplicationJsonSchemaQuery0: 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 - AccountsSearchPostRequestBodyContentApplicationJsonSchemaQuery1: 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 - AccountsSearchPostRequestBodyContentApplicationJsonSchemaQuery2: 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 - AccountsSearchPostRequestBodyContentApplicationJsonSchemaQuery3: Attribute predicate - `attribute` string, required: The attribute name to filter on (e.g., 'created_at', 'type', 'status', 'fields.age') - `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` AccountsSearchPostRequestBodyContentApplicationJsonSchemaSort: 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` AccountsSearchPostRequestBodyContentApplicationJsonSchemaPage: 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 Account objects matching the search criteria. - AccountsSearchAccountsResponse200 - `data` Account[], required: An array of Accounts matching the search criteria - `id` string - `attributes` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributes - `reference-id` string, nullable - `account-type-name` string - `created-at` string, date-time - `updated-at` string, date-time - `redacted-at` string, date-time, nullable - `fields` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFields: JSON key-value pairs of field name to field value. Exact schema depends on the configuration of the Account Type for this Account. Keys in `fields` are **not** key inflected. - `name` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsName - `type` string - `value` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsNameValue - `first` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsNameValueFirst - … - `middle` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsNameValueMiddle - … - `last` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsNameValueLast - … - `address` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddress - `type` string - `value` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValue - `street_1` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValueStreet1 - … - `street_2` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValueStreet2 - … - `subdivision` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValueSubdivision - … - `city` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValueCity - … - `postal_code` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValuePostalCode - … - `country_code` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsAddressValueCountryCode - … - `identification_numbers` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsIdentificationNumbers - `type` string - `value` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsIdentificationNumbersValueItems[] - `type` string - `value` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsIdentificationNumbersValueItemsValue - … - `birthdate` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsBirthdate - `type` string - `value` string, nullable - `phone_number` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsPhoneNumber - `type` string - `value` string, nullable - `email_address` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsEmailAddress - `type` string - `value` string, nullable - `selfie_photo` VerificationIncludedObjectsItemsDiscriminatorMappingAccountAttributesFieldsSelfiePhoto - `type` 'file' - `value` File - `filename` string - `url` string - `byte-size` integer - `tags` string[] - `account-status` string - `relationships` VerificationIncludedObjectsItemsDiscriminatorMappingAccountRelationships - `account-type` VerificationIncludedObjectsItemsDiscriminatorMappingAccountRelationshipsAccountType - `data` VerificationIncludedObjectsItemsDiscriminatorMappingAccountRelationshipsAccountTypeData - `id` string - `type` 'account-type' - `links` AccountsSearchPostResponsesContentApplicationJsonSchemaLinks, 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-5.md) - [All operations](https://skmtc.dev/withpersona/apis/withpersona-5/llms.txt) - [OpenAPI document](https://skmtc.dev/withpersona/apis/withpersona-5/revisions/0281de74819e?raw)