> ## Documentation Index > Fetch the complete documentation index at: https://docs.heyy.io/llms.txt > Use this file to discover all available pages before exploring further. # Search contacts ## OpenAPI ````yaml /api-reference/openapi-v3.json post /contacts/search openapi: 3.1.0 info: title: Heyy API version: 3.0.0 servers: - url: https://api.heyy.io/v3 security: - bearerAuth: [] paths: /contacts/search: post: summary: Search contacts requestBody: required: true content: application/json: schema: type: object properties: query: type: string description: >- Structured filter expression. See [Query syntax](/api-reference/v3/query) for expression functions. Filterable fields: `id`, `createdAt`, `updatedAt`, `firstName`, `lastName`, `isSubscribed`, `labels`, `notes`, `groups`, `phoneNumber`, `email`. Filter custom contact attributes with `getBy('attributes', 'name', 'your_attribute_name')` or `getBy('attributes', 'id', 'attribute-id')`. sortBy: type: string description: >- Sort expression. See [Sort By syntax](/api-reference/v3/sort-by) for expression functions. Sortable fields: `id`, `createdAt`, `updatedAt`, `firstName`, `lastName`, `isSubscribed`, `labels`, `notes`, `groups`, `phoneNumber`, `email`. Sort custom contact attributes with `getBy('attributes', 'name', 'your_attribute_name')` or `getBy('attributes', 'id', 'attribute-id')`. search: type: string description: >- Free-text search by full name (`firstName` and `lastName` combined with a space), phone number, or email. See [Search](/api-reference/v3/search). pagination: type: object properties: page: type: integer minimum: 0 description: Zero-based page index. Defaults to 0 when omitted. limit: type: integer minimum: 1 maximum: 100 description: Rows per page. Defaults to 10 when omitted. Maximum 100. required: - page - limit additionalProperties: false description: >- Page through results. Defaults to page 0 and limit 10 when omitted. See [Pagination](/api-reference/v3/pagination). additionalProperties: false responses: '200': description: '' content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time firstName: type: - string - 'null' lastName: type: - string - 'null' fullName: type: - string - 'null' isSubscribed: type: boolean handles: type: array items: anyOf: - type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time type: type: string enum: - phone_number isPrimary: type: boolean value: type: string extra: type: - object - 'null' additionalProperties: {} hasChats: type: boolean required: - id - createdAt - updatedAt - type - isPrimary - value - extra additionalProperties: false - type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time type: type: string enum: - email isPrimary: type: boolean value: type: string extra: type: - object - 'null' additionalProperties: {} hasChats: type: boolean required: - id - createdAt - updatedAt - type - isPrimary - value - extra additionalProperties: false - type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time type: type: string enum: - instagram isPrimary: type: boolean value: type: string extra: type: - object - 'null' additionalProperties: {} hasChats: type: boolean required: - id - createdAt - updatedAt - type - isPrimary - value - extra additionalProperties: false - type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time type: type: string enum: - messenger isPrimary: type: boolean value: type: string extra: type: - object - 'null' additionalProperties: {} hasChats: type: boolean required: - id - createdAt - updatedAt - type - isPrimary - value - extra additionalProperties: false - type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time type: type: string enum: - live_chat isPrimary: type: boolean value: type: string extra: type: - object - 'null' additionalProperties: {} hasChats: type: boolean required: - id - createdAt - updatedAt - type - isPrimary - value - extra additionalProperties: false - type: object properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time type: type: string enum: - whatsapp isPrimary: type: boolean value: type: string extra: type: - object - 'null' additionalProperties: {} hasChats: type: boolean required: - id - createdAt - updatedAt - type - isPrimary - value - extra additionalProperties: false labels: type: array items: type: object properties: id: type: string required: - id additionalProperties: false attributes: type: array items: type: object properties: id: type: string format: uuid contactId: type: string format: uuid attribute: type: - object - 'null' properties: id: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time name: type: string type: type: string enum: - text - number - single_select - multi_select - date - datetime displayName: type: string description: type: - string - 'null' visibility: type: object properties: inbox: type: boolean contacts: type: boolean create: type: boolean required: - inbox - contacts - create details: type: object properties: options: type: - array - 'null' items: type: object properties: color: type: string value: type: string required: - color - value required: - id - createdAt - updatedAt - name - type - displayName - description - visibility - details additionalProperties: false value: anyOf: - type: string - type: number - type: array items: type: string - type: 'null' - type: 'null' required: - attribute - value displayName: type: - string - 'null' phoneNumber: type: - string - 'null' email: type: - string - 'null' chats: type: array items: type: object properties: id: type: string required: - id metadata: type: object additionalProperties: {} required: - id - createdAt - updatedAt - firstName - lastName - fullName - isSubscribed - handles - labels - attributes - displayName - phoneNumber - email - chats - metadata additionalProperties: false pagination: type: object properties: page: type: integer minimum: 0 limit: type: integer maximum: 1000 total: type: integer minimum: 0 required: - page - limit - total additionalProperties: false query: type: object properties: query: type: string sortBy: type: string search: type: string success: type: boolean enum: - true required: - data - pagination - query - success additionalProperties: false example: success: true data: [] pagination: page: 0 limit: 0 total: 0 query: query: string sortBy: string search: string '400': description: Bad request. The request body or parameters are invalid. content: application/json: schema: type: object properties: success: type: boolean enum: - false error: type: object properties: messageKey: type: string message: type: string invalidParams: type: object additionalProperties: type: object properties: key: type: string message: type: string required: - key - message required: - success additionalProperties: false example: success: false error: messageKey: invalid_body_params message: Invalid body params invalidParams: email: key: invalid_string message: Invalid email '401': description: Unauthorized. A valid API key is required. content: application/json: schema: type: object properties: success: type: boolean enum: - false error: type: object properties: messageKey: type: string message: type: string invalidParams: type: object additionalProperties: type: object properties: key: type: string message: type: string required: - key - message required: - success additionalProperties: false example: success: false error: messageKey: unauthorized message: Unauthorized '402': description: >- Payment required. The current billing plan does not allow this request. content: application/json: schema: type: object properties: success: type: boolean enum: - false error: type: object properties: messageKey: type: string message: type: string invalidParams: type: object additionalProperties: type: object properties: key: type: string message: type: string required: - key - message required: - success additionalProperties: false example: success: false error: messageKey: insufficient_billing_plan message: Insufficient billing plan '403': description: >- Forbidden. The API key does not have permission to perform this action. content: application/json: schema: type: object properties: success: type: boolean enum: - false error: type: object properties: messageKey: type: string message: type: string invalidParams: type: object additionalProperties: type: object properties: key: type: string message: type: string required: - key - message required: - success additionalProperties: false example: success: false error: messageKey: forbidden message: Forbidden '404': description: Not found. The requested resource does not exist. content: application/json: schema: type: object properties: success: type: boolean enum: - false error: type: object properties: messageKey: type: string message: type: string invalidParams: type: object additionalProperties: type: object properties: key: type: string message: type: string required: - key - message required: - success additionalProperties: false example: success: false error: messageKey: contact_not_found message: Contact not found '429': description: >- Too many requests. Retry after the time indicated by the X-RateLimit-Reset header. content: application/json: schema: type: object properties: success: type: boolean enum: - false error: type: object properties: messageKey: type: string message: type: string invalidParams: type: object additionalProperties: type: object properties: key: type: string message: type: string required: - key - message required: - success additionalProperties: false example: success: false error: messageKey: too_many_requests message: >- Too many requests. Limit is applied per minute per tenant. Please retry after the time indicated by the X-RateLimit-Reset header. '500': description: Internal server error. content: application/json: schema: type: object properties: success: type: boolean enum: - false error: type: object properties: messageKey: type: string message: type: string invalidParams: type: object additionalProperties: type: object properties: key: type: string message: type: string required: - key - message required: - success additionalProperties: false example: success: false error: messageKey: internal_error message: Oops! Something went wrong components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````