--- title: "Search Cases" method: POST path: "/cases/search" tags: ["cases"] --- # Search Cases `POST /cases/search` ## Request - Base URL: `https://api.withpersona.com/api/v1` - URL: `https://api.withpersona.com/api/v1/cases/search` - Auth: HTTP bearer Search for cases 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 /cases/search`) when you need to perform complex queries with boolean logic (AND/OR/NOT), filter by custom fields, assignee, case queue, or SLA expiration, 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 /cases`) for simple listing with basic filters like status, case template, account, inquiry, or report. ## 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 a case, use the List Cases endpoint instead. ### Searchable Attributes The following attributes can be used in query predicates: | Attribute | Description | |-----------|-------------| | `template` | Case template (e.g., `ctmpl_ABC123`) | | `case_template_id` | Case template (e.g., `ctmpl_ABC123`) | | `status` | Case status (e.g., `open`, `pending`, `resolved`) | | `state` | Case state | | `resolution` | Case resolution | | `created_at` | Case creation timestamp | | `updated_at` | Case last updated timestamp | | `resolved_at` | Case resolution timestamp | | `sla_expires_at` | SLA expiration timestamp | | `assignee` | Assigned user (e.g., `user_ABC123`) | | `case_queue` | Case queue (e.g., `cqueue_ABC123`) | | `case_queue_id` | Case queue (e.g., `cqueue_ABC123`) | | `resolver` | Resolver user | | `account_id` | Related account (e.g., `act_ABC123`) | | `inquiry_id` | Related inquiry (e.g., `inq_ABC123`) | | `tag_id` | Related tag (e.g., `tag_ABC123`) | | `fields.*` | Custom case field (e.g., `fields.priority`) | **Note:** Custom fields (`fields.*`) must be configured as searchable on the Case Template to be queryable. **Note:** `account_id`, `inquiry_id`, `tag_id`, `case_template_id`, `case_queue_id`, and `resolution` cannot be used in `sort`. **Note:** `account_id`, `inquiry_id`, and `tag_id` match against the 50 most recently added accounts, inquiries, and tags on a case. A case related to more than 50 of one of these will not match on the older ones. ## Query parameters - `fields` object - `page` CasesSearchPostParametersPage - `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 - CasesSearchCasesRequest - `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). - CasesSearchPostRequestBodyContentApplicationJsonSchemaQuery0: 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 - CasesSearchPostRequestBodyContentApplicationJsonSchemaQuery1: 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 - CasesSearchPostRequestBodyContentApplicationJsonSchemaQuery2: 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 - CasesSearchPostRequestBodyContentApplicationJsonSchemaQuery3: Attribute predicate - `attribute` string, required: The attribute name to filter on (e.g., 'created_at', 'template', 'status', 'fields.priority') - `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` CasesSearchPostRequestBodyContentApplicationJsonSchemaSort: 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` CasesSearchPostRequestBodyContentApplicationJsonSchemaPage: 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 Case objects matching the search criteria. - CasesSearchCasesResponse200 - `data` Case[], required: An array of Cases matching the search criteria - `type` 'case' - `id` string - `attributes` CaseAttributes - `status` string - `name` string - `resolution` string, nullable - `created-at` string - `updated-at` string, nullable - `assigned-at` string, nullable - `resolved-at` string, nullable - `redacted-at` string, nullable - `sla-expires-at` string, nullable - `creator-id` string, nullable - `creator-type` string, nullable: Possible values: - user - workflow-run Do not assume this is a static enumeration; Persona may add new values in the future without a versioned update. - `assignee-id` string, nullable - `assigner-id` string, nullable - `assigner-type` string, nullable: Possible values: - case-assignment-policy - user - workflow-run Do not assume this is a static enumeration; Persona may add new values in the future without a versioned update. - `resolver-id` string, nullable - `resolver-type` string, nullable: Possible values: - api-key - user - workflow-run Do not assume this is a static enumeration; Persona may add new values in the future without a versioned update. - `updater-id` string, nullable - `updater-type` string, nullable: Possible values: - api-key - case-assignment-policy - user - workflow-run Do not assume this is a static enumeration; Persona may add new values in the future without a versioned update. - `tags` unknown[] - unknown - `fields` object: JSON key-value pairs of field name to field value. Exact schema depends on the configuration of the Case template for this Case. - `attachments` CaseAttributesAttachmentsItems[] - `filename` string - `url` string - `byte-size` integer - `relationships` CaseRelationships - `accounts` CaseRelationshipsAccounts - `data` CaseRelationshipsAccountsDataItems[] - `id` string - `type` 'account' - `case-comments` CaseRelationshipsCaseComments - `data` CaseRelationshipsCaseCommentsDataItems[] - `id` string - `type` 'case-comment' - `case-template` CaseRelationshipsCaseTemplate - `data` CaseRelationshipsCaseTemplateData - `id` string - `type` 'case-template' - `case-queue` CaseRelationshipsCaseQueue - `data` CaseRelationshipsCaseQueueData - `id` string - `type` 'case-queue' - `inquiries` CaseRelationshipsInquiries - `data` CaseRelationshipsInquiriesDataItems[] - `id` string - `type` 'inquiry' - `reports` CaseRelationshipsReports - `data` CaseRelationshipsReportsDataItems[] - `id` string - `type` string - `verifications` CaseRelationshipsVerifications - `data` CaseRelationshipsVerificationsDataItems[] - `id` string - `type` string - `txns` CaseRelationshipsTxns - `data` CaseRelationshipsTxnsDataItems[] - `id` string - `type` 'transaction' - `links` CasesSearchPostResponsesContentApplicationJsonSchemaLinks, 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-3.md) - [All operations](https://skmtc.dev/withpersona/apis/withpersona-3/llms.txt) - [OpenAPI document](https://skmtc.dev/withpersona/apis/withpersona-3/revisions/0a3310d5046f?raw)