> ## Documentation Index > Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search contacts with filter body > Use this when a large or nested `contactFilter` cannot fit conveniently in query parameters. It returns the same contact data as `contacts.list`, including `include` and `withCount` options. ## OpenAPI ````yaml /api-reference/platform-api.json post /v1/contacts/search openapi: 3.1.1 info: title: ChatbotX version: 0.0.1 servers: - url: https://app.chatbotx.io/api security: - bearerAuth: [] - developerAccessToken: [] - tokenInSearchParams: [] paths: /v1/contacts/search: post: tags: - Contacts summary: Search contacts with filter body description: >- Use this when a large or nested `contactFilter` cannot fit conveniently in query parameters. It returns the same contact data as `contacts.list`, including `include` and `withCount` options. operationId: contacts.search requestBody: required: true content: application/json: schema: type: object properties: page: anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: 'null' description: Page number, starting at 1. perPage: anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: 'null' description: Number of items per page. sort: anyOf: - type: array items: type: object properties: id: type: string desc: type: boolean required: - id - desc - type: 'null' description: Sort order as `[{ id, desc }]` column/direction pairs. keyword: type: string description: >- Case-insensitive substring match against the contact's name, email, or phone. contactFilter: type: object properties: operator: enum: - and - or type: string conditions: type: array items: anyOf: - anyOf: - type: object properties: field: const: locale operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: language operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: fullName operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: country operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: continent operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: gender operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: subscribedToBroadcast operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: contactCreatedAt operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: source operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: conversationTransferredToHuman operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: interactedInLast24h operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: followUp operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: archived operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: blocked operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: currentChannel operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: inbox operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: timezone operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: lastSeen operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: lastSent operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: lastInteraction operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: contactCreatedDateMinutesAgo operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: lastSeenMinutesAgo operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: lastInteractionMinutesAgo operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: lastUserInput operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: lastComment operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: lastUserInputType operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: email operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: phone operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: hasContactInfo operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: tags operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: broadcastSent operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: broadcastDelivered operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: broadcastSeen operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: broadcastClicked operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: broadcastFailed operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: subscribedToDripCampaign operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: entryPointsLinks operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: questionnaireStarted operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: questionnaireInProgress operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: questionnaireFinished operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: conversationAssigned operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: unreplied operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: unread operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: existingContact operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: consecutiveAiFailures operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: emailWasVerified operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: optedInForEmail operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: fromCtwaAd operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: ctwaConversion operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array items: type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - operator - type: object properties: field: const: customField customFieldId: type: string minLength: 1 customFieldType: enum: - shortText - email - phoneNumber - number - date - datetime - boolean - longText type: string valueType: enum: - multiSelect - select - text - boolean - datetime - number type: string operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - customFieldId - valueType - operator - type: object properties: field: const: botField botFieldId: type: string minLength: 1 botFieldType: enum: - shortText - email - phoneNumber - number - date - datetime - boolean - longText type: string valueType: enum: - multiSelect - select - text - boolean - datetime - number type: string operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: anyOf: - type: string minLength: 1 maxLength: 255 - type: array prefixItems: - type: string minLength: 1 maxLength: 255 - type: string minLength: 1 maxLength: 255 required: - field - botFieldId - valueType - operator - type: object properties: field: const: couponTopic topicId: type: string minLength: 1 operator: enum: - in - notIn - isEmpty - isNotEmpty - eq - ne - startsWith - endsWith - contains - notContains - lt - lte - gt - gte - isBetween - notBetween - used type: string value: type: string minLength: 1 maxLength: 255 required: - field - topicId - operator - type: object properties: field: const: ctwaRetarget segment: enum: - conversations - leads - purchases type: string adId: type: string minLength: 1 integrationWhatsappId: type: string pattern: ^\d+$ channel: enum: - whatsapp - messenger - instagram type: string since: type: string pattern: ^\d{4}-\d{2}-\d{2}$ until: type: string pattern: ^\d{4}-\d{2}-\d{2}$ required: - field - segment - since - until timezone: type: string maxLength: 64 required: - operator - conditions description: >- Structured filter for advanced matching beyond `keyword`. See `contacts.listFilterFields` for the field/operator reference. channels: type: array items: enum: - omnichannel - webchat - messenger - whatsapp - zalo - smtp - telegram - instagram - threads - tiktok - api type: string description: >- Restrict to contacts with at least one inbox on one of these channels. integrationWhatsappId: type: string pattern: ^\d+$ description: >- Restrict to contacts reachable via this WhatsApp integration id. integrationMessengerId: type: string pattern: ^\d+$ description: >- Restrict to contacts reachable via this Messenger integration id. inboxIds: type: array items: type: string pattern: ^\d+$ description: >- Restrict to contacts with at least one conversation in one of these inbox ids. subaction: enum: - allContacts - messengerActiveContacts - messengerTemplateMessage - whatsappTemplateMessage - whatsappWithin24Hours - instagramActiveContacts - telegramAllContacts - tiktokActiveContacts type: string description: Broadcast recipient sub-action filter. include: type: array items: enum: - tags - customFields - inboxes - conversation type: string description: >- Relations to embed in each contact. Omit to include everything (default); pass an empty selection or a narrower list — e.g. `["tags"]` — to shrink the response when scanning many contacts. withCount: type: boolean default: true description: >- Whether to compute totalCount/pageCount. Set to false to skip the count query when you only need the rows — faster on large workspaces. responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: allOf: - type: object properties: id: type: string createdAt: type: string format: date-time x-native-type: date updatedAt: type: string format: date-time x-native-type: date avatar: anyOf: - type: string - type: 'null' phoneNumber: anyOf: - type: string - type: 'null' email: anyOf: - type: string - type: 'null' emailVerified: type: boolean emailOptIn: type: boolean firstName: anyOf: - type: string - type: 'null' lastName: anyOf: - type: string - type: 'null' fullName: anyOf: - type: string - type: 'null' gender: anyOf: - enum: - male - female - unknown type: string - type: 'null' lastReadAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' ref: anyOf: - type: string - type: 'null' country: anyOf: - type: string - type: 'null' state: anyOf: - type: string - type: 'null' city: anyOf: - type: string - type: 'null' location: anyOf: - anyOf: - anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: {} - type: array items: anyOf: - {} - type: 'null' - type: 'null' locale: anyOf: - type: string - type: 'null' timezone: anyOf: - type: string - type: 'null' subscribedAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' broadcastSubscribedAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' blockedAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' workspaceId: type: string required: - id - createdAt - updatedAt - avatar - phoneNumber - email - emailVerified - emailOptIn - firstName - lastName - fullName - gender - lastReadAt - ref - country - state - city - location - locale - timezone - subscribedAt - broadcastSubscribedAt - blockedAt - workspaceId - type: object properties: contactCustomFields: type: array items: type: object properties: id: type: string createdAt: type: string format: date-time x-native-type: date updatedAt: type: string format: date-time x-native-type: date value: type: string contactId: type: string customFieldId: type: string required: - id - createdAt - updatedAt - value - contactId - customFieldId tags: type: array items: type: object properties: id: type: string createdAt: type: string format: date-time x-native-type: date updatedAt: type: string format: date-time x-native-type: date name: type: string deletedAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' folderId: anyOf: - type: string - type: 'null' workspaceId: type: string required: - id - createdAt - updatedAt - name - deletedAt - folderId - workspaceId contactNotes: type: array items: type: object properties: id: type: string pattern: ^\d+$ createdAt: type: string format: date-time x-native-type: date updatedAt: type: string format: date-time x-native-type: date text: type: string contactId: type: string pattern: ^\d+$ createdById: anyOf: - type: string pattern: ^\d+$ - type: 'null' required: - id - createdAt - updatedAt - text - contactId - createdById contactInboxes: type: array items: type: object properties: id: type: string contactId: type: string inboxId: type: string channel: type: string source: type: string sourceId: type: string sourceUserId: anyOf: - type: string - type: 'null' sourceUsername: anyOf: - type: string - type: 'null' language: anyOf: - type: string - type: 'null' lastIncomingMessageAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' contactLastReadAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' inbox: type: object properties: id: type: string pattern: ^\d+$ createdAt: type: string format: date-time x-native-type: date updatedAt: type: string format: date-time x-native-type: date name: type: string channel: type: string sourceId: type: string workspaceId: type: string pattern: ^\d+$ status: type: string disconnectedAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' disconnectReason: anyOf: - type: string - type: 'null' required: - id - createdAt - updatedAt - name - channel - sourceId - workspaceId - status - disconnectedAt - disconnectReason required: - id - contactId - inboxId - channel - source - sourceId - language - lastIncomingMessageAt - inbox conversation: anyOf: - allOf: - type: object properties: id: type: string createdAt: type: string format: date-time x-native-type: date updatedAt: type: string format: date-time x-native-type: date botEnabled: type: boolean botResumeAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' archivedAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' additionalAttributes: anyOf: - anyOf: - anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object propertyNames: type: string additionalProperties: {} - type: array items: anyOf: - {} - type: 'null' - type: 'null' contactLastReadAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' agentLastReadAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' aiContextLastMessageId: anyOf: - {} - type: 'null' lastActivityAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' followed: type: boolean assignedUserId: anyOf: - {} - type: 'null' assignedInboxTeamId: anyOf: - {} - type: 'null' workspaceId: type: string contactId: type: string sourceId: anyOf: - type: string - type: 'null' lastStep: anyOf: - type: string - type: 'null' currentStep: anyOf: - type: string - type: 'null' adminRepliedAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' contactRepliedAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' required: - id - createdAt - updatedAt - botEnabled - botResumeAt - archivedAt - additionalAttributes - contactLastReadAt - agentLastReadAt - lastActivityAt - followed - workspaceId - contactId - sourceId - lastStep - currentStep - adminRepliedAt - contactRepliedAt - type: object properties: assignedUser: anyOf: - type: object properties: id: type: string createdAt: type: string format: date-time x-native-type: date updatedAt: type: string format: date-time x-native-type: date name: anyOf: - type: string - type: 'null' email: type: string emailVerified: type: boolean image: anyOf: - type: string - type: 'null' isAnonymous: type: boolean mustChangePassword: type: boolean tenantId: {} required: - id - createdAt - updatedAt - name - email - emailVerified - image - isAnonymous - mustChangePassword - type: 'null' assignedInboxTeam: anyOf: - type: object properties: id: type: string createdAt: type: string format: date-time x-native-type: date updatedAt: type: string format: date-time x-native-type: date workspaceId: type: string name: type: string required: - id - createdAt - updatedAt - workspaceId - name - type: 'null' inbox: anyOf: - type: object properties: id: type: string pattern: ^\d+$ createdAt: type: string format: date-time x-native-type: date updatedAt: type: string format: date-time x-native-type: date name: type: string channel: type: string sourceId: type: string workspaceId: type: string pattern: ^\d+$ status: type: string disconnectedAt: anyOf: - type: string format: date-time x-native-type: date - type: 'null' disconnectReason: anyOf: - type: string - type: 'null' required: - id - createdAt - updatedAt - name - channel - sourceId - workspaceId - status - disconnectedAt - disconnectReason - type: 'null' - type: 'null' pageCount: type: number totalCount: type: number totalCountCapped: type: boolean required: - data - pageCount - totalCount - totalCountCapped '400': description: '400' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: businessError status: const: 400 message: type: string default: An error occurred while processing your request data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '401': description: '401' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: UNAUTHORIZED status: const: 401 message: type: string default: Authentication required data: {} required: - defined - code - status - message - type: object properties: defined: const: true code: const: INVALID_CHATBOT_TOKEN status: const: 401 message: type: string default: Invalid or missing workspace API token data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '403': description: '403' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: FORBIDDEN status: const: 403 message: type: string default: You do not have permission to perform this action data: {} required: - defined - code - status - message - type: object properties: defined: const: true code: const: trialExpired status: const: 403 message: type: string default: Trial expired data: {} required: - defined - code - status - message - type: object properties: defined: const: true code: const: macLimitReached status: const: 403 message: type: string default: Monthly active contact limit reached data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '422': description: '422' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: invalidRequestData status: const: 422 message: type: string default: Input validation failed data: type: object properties: issues: type: array items: type: object properties: message: type: string path: type: array items: anyOf: - type: string - type: number - type: object properties: key: anyOf: - type: string - type: number required: - key additionalProperties: {} required: - message additionalProperties: {} required: - issues additionalProperties: {} required: - defined - code - status - message - data - type: object properties: defined: const: true code: const: validation status: const: 422 message: type: string default: Validation error data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '429': description: '429' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: tooManyRequests status: const: 429 message: type: string default: Too many requests data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' '500': description: '500' content: application/json: schema: oneOf: - type: object properties: defined: const: true code: const: INTERNAL_SERVER_ERROR status: const: 500 message: type: string default: An unexpected error occurred data: {} required: - defined - code - status - message - $ref: '#/components/schemas/UndefinedError' components: schemas: UndefinedError: type: object properties: defined: const: false code: type: string status: type: number message: type: string data: {} required: - defined - code - status - message securitySchemes: bearerAuth: type: http scheme: bearer developerAccessToken: type: http scheme: bearer tokenInSearchParams: type: apiKey in: query name: token ````