> ## Documentation Index > Fetch the complete documentation index at: https://docs.chatsailer.com/llms.txt > Use this file to discover all available pages before exploring further. # Search contacts > For queries `GET /v1/contacts` cannot express: nested and/or, ranges, and conditions across relationships. Returns the same contact objects in the same envelope, and accepts the same `expand` and `fields`. Both endpoints compile to one query engine, so their results cannot disagree. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/contacts/search openapi: 3.1.0 info: description: >- The Sailer REST API for CRM, conversations, and campaigns. **Authentication.** Send a scoped token as `Authorization: Bearer sk_live_...`. Tokens are workspace-scoped; the workspace is implied by the token, so no tenant header is needed. During early access, tokens are issued by Sailer on request — contact your Sailer representative. **Pagination.** Collections return `{data, meta, links}`. Follow `links.next` until it is `null`; treat the cursor as opaque. **Errors.** Every non-2xx response is `{"error": {...}}` with a stable `code`. Quote `error.request_id` when contacting support. **Custom fields.** Workspace-defined fields appear under `custom_fields`, keyed by `field_key`. Read a record to see which keys a workspace uses; a dedicated field-discovery endpoint is not part of this release. title: Sailer API version: 1.0.0 servers: - url: https://api.chatsailer.com security: - SailerApiToken: [] tags: - description: Token introspection and workspace capabilities. name: Meta - description: >- People you talk to. Called *leads* in older Sailer surfaces; `contact` is the current name. name: Contacts - description: Companies that contacts belong to (B2B accounts). name: Organizations - description: Opportunities moving through a pipeline. name: Deals - description: Pipelines and their stages. name: Pipelines - description: Field definitions, including custom fields. name: Fields - description: Free-text annotations on CRM records. name: Notes - description: Scheduled and logged CRM activities. name: Activities - description: Per-entity label catalogs. name: Tags - description: Message threads with contacts, across every channel. name: Conversations - description: Outbound campaigns and their participants. name: Campaigns paths: /v1/contacts/search: post: tags: - Contacts summary: Search contacts description: >- For queries `GET /v1/contacts` cannot express: nested and/or, ranges, and conditions across relationships. Returns the same contact objects in the same envelope, and accepts the same `expand` and `fields`. Both endpoints compile to one query engine, so their results cannot disagree. operationId: search_contacts requestBody: content: application/json: schema: $ref: '#/components/schemas/ContactSearchRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ContactList' description: Successful Response '422': content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' description: Validation Error security: - SailerApiToken: [] components: schemas: ContactSearchRequest: additionalProperties: false description: >- Body for ``POST /v1/contacts/search``, and arguments for the MCP ``search_records`` tool. Defined here rather than beside the route because two surfaces share it. The MCP tool derives its JSON Schema from this class, so a filter added for REST reaches the tool in the same commit — there is no second copy to forget. Extras are forbidden for the same reason they are on `FilterCondition`: every field here is optional, so an ignored `filtr` typo would silently mean "no filter" and return the whole collection with 200 OK. properties: cursor: anyOf: - type: string - type: 'null' title: Cursor expand: anyOf: - type: string - type: 'null' title: Expand fields: anyOf: - type: string - type: 'null' title: Fields filter: anyOf: - $ref: '#/components/schemas/FilterGroup' - $ref: '#/components/schemas/FilterCondition' - type: 'null' description: Condition tree. Groups may nest and mix and/or. title: Filter limit: default: 50 maximum: 200 minimum: 1 title: Limit type: integer q: anyOf: - type: string - type: 'null' description: Free text across name, email and phone. title: Q sort: anyOf: - type: string - type: 'null' description: Same syntax as the `sort` query parameter. title: Sort title: ContactSearchRequest type: object ContactList: description: >- A page of contacts. A named subclass purely so the generated SDK type is ``ContactList`` rather than the ``Page_Contact_`` FastAPI derives from the generic. properties: data: items: $ref: '#/components/schemas/Contact' title: Data type: array links: $ref: '#/components/schemas/PageLinks' meta: $ref: '#/components/schemas/PageMeta' required: - data - meta - links title: ContactList type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object FilterGroup: additionalProperties: false description: A set of conditions combined with `and` / `or`. Groups may nest. properties: conditions: items: anyOf: - $ref: '#/components/schemas/FilterCondition' - $ref: '#/components/schemas/FilterGroup' title: Conditions type: array join: default: and enum: - and - or title: Join type: string title: FilterGroup type: object FilterCondition: additionalProperties: false description: One comparison against a field. properties: field: description: Public field name, or `custom.` for a custom field. examples: - status title: Field type: string operator: $ref: '#/components/schemas/OperatorType' default: equals description: Comparison to apply. Valid operators depend on the field type. value: anyOf: - {} - type: 'null' description: Value to compare against. Omitted for `is_empty`/`is_not_empty`. title: Value required: - field title: FilterCondition type: object Contact: description: A person in your CRM. properties: address: anyOf: - type: string - type: 'null' title: Address avatar_url: anyOf: - type: string - type: 'null' description: Short-lived signed URL; do not store it. title: Avatar Url channels: items: $ref: '#/components/schemas/ContactChannel' title: Channels type: array city: anyOf: - type: string - type: 'null' title: City company_name: anyOf: - type: string - type: 'null' description: >- Free-text employer name. Unrelated to your workspace and to `organization`, which is a CRM record. title: Company Name created_at: format: date-time title: Created At type: string custom_fields: additionalProperties: true description: >- Every custom field defined on contacts in this workspace, keyed by field key and typed from its definition. Unset fields are `null`, so reading any contact shows the full set of keys in use. title: Custom Fields type: object email: anyOf: - type: string - type: 'null' title: Email first_name: anyOf: - type: string - type: 'null' title: First Name id: description: Unique identifier for a contact. examples: - con_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4 pattern: ^con_[0-9a-f]{32}$ title: Id type: string job_title: anyOf: - type: string - type: 'null' title: Job Title last_name: anyOf: - type: string - type: 'null' title: Last Name lost_reason: anyOf: - type: string - type: 'null' description: Name of the reason, when `status` is `lost`. title: Lost Reason name: anyOf: - type: string - type: 'null' description: Display name. Derived from `first_name` and `last_name`. title: Name object: const: contact default: contact title: Object type: string organization: anyOf: - $ref: '#/components/schemas/Organization' - type: 'null' description: Populated only when `organization` is in `expand`. organization_id: anyOf: - description: Unique identifier for an organization. examples: - org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4 pattern: ^org_[0-9a-f]{32}$ type: string - type: 'null' title: Organization Id owner: anyOf: - $ref: '#/components/schemas/User' - type: 'null' description: Populated only when `owner` is in `expand`. owner_id: anyOf: - description: Unique identifier for an user. examples: - usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4 pattern: ^usr_[0-9a-f]{32}$ type: string - type: 'null' title: Owner Id phone: anyOf: - type: string - type: 'null' description: E.164. Normalized on write. title: Phone score: anyOf: - $ref: '#/components/schemas/LeadScore' - type: 'null' state: anyOf: - type: string - type: 'null' title: State status: $ref: '#/components/schemas/LeadStatus' description: Where the contact stands. tags: items: $ref: '#/components/schemas/Tag' title: Tags type: array updated_at: format: date-time title: Updated At type: string visibility: $ref: '#/components/schemas/RecordVisibility' description: >- Governs who sees this record in the Sailer UI. API tokens are workspace-scoped and are not filtered by it. required: - id - status - visibility - created_at - updated_at title: Contact type: object PageLinks: properties: next: anyOf: - type: string - type: 'null' description: Opaque cursor for the following page; null on the last page. title: Next title: PageLinks type: object PageMeta: properties: has_more: description: True when a next page exists. title: Has More type: boolean limit: description: Maximum items requested for this page. title: Limit type: integer required: - limit - has_more title: PageMeta type: object ValidationError: properties: ctx: title: Context type: object input: title: Input loc: items: anyOf: - type: string - type: integer title: Location type: array msg: title: Message type: string type: title: Error Type type: string required: - loc - msg - type title: ValidationError type: object OperatorType: enum: - equals - not_equals - is_empty - is_not_empty - contains - not_contains - starts_with - ends_with - greater_than - less_than - greater_than_or_equal_to - less_than_or_equal_to - is_relative_to_today - is_between - is_one_of - is_not_one_of title: OperatorType type: string ContactChannel: description: >- Where a contact is reachable. An array rather than a ``whatsapp_*`` column cluster: Instagram and Telegram arrive without a breaking change, and an empty list is a meaningful "not reachable anywhere" signal. properties: identifier: description: Address on that platform. title: Identifier type: string platform: description: Channel platform, e.g. `whatsapp`. title: Platform type: string status: anyOf: - type: string - type: 'null' description: Reachability, when the platform reports it. title: Status username: anyOf: - type: string - type: 'null' title: Username required: - platform - identifier title: ContactChannel type: object Organization: description: A company a contact belongs to. properties: created_at: format: date-time title: Created At type: string id: description: Unique identifier for an organization. examples: - org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4 pattern: ^org_[0-9a-f]{32}$ title: Id type: string name: title: Name type: string object: const: organization default: organization title: Object type: string owner: anyOf: - $ref: '#/components/schemas/User' - type: 'null' description: Populated only when `owner` is included in `expand`. owner_id: anyOf: - description: Unique identifier for an user. examples: - usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4 pattern: ^usr_[0-9a-f]{32}$ type: string - type: 'null' description: Teammate responsible for this organization. title: Owner Id tags: items: $ref: '#/components/schemas/Tag' title: Tags type: array updated_at: format: date-time title: Updated At type: string visibility: $ref: '#/components/schemas/RecordVisibility' description: >- Governs who sees this record in the Sailer UI. API tokens are workspace-scoped and are not filtered by it. website: anyOf: - type: string - type: 'null' title: Website required: - id - name - visibility - created_at - updated_at title: Organization type: object User: description: A Sailer teammate. Exposed only as the owner of a record. properties: email: anyOf: - type: string - type: 'null' title: Email id: description: Unique identifier for an user. examples: - usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4 pattern: ^usr_[0-9a-f]{32}$ title: Id type: string name: anyOf: - type: string - type: 'null' title: Name object: const: user default: user title: Object type: string required: - id title: User type: object LeadScore: enum: - cold - warm - hot title: LeadScore type: string LeadStatus: enum: - open - on_hold - won - lost title: LeadStatus type: string Tag: description: A CRM label. The catalogue is per entity type. properties: color: anyOf: - type: string - type: 'null' description: Hex colour used by the Sailer UI, e.g. `#FFAA00`. title: Color id: description: Unique identifier for a tag. examples: - tag_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4 pattern: ^tag_[0-9a-f]{32}$ title: Id type: string name: title: Name type: string object: const: tag default: tag title: Object type: string required: - id - name title: Tag type: object RecordVisibility: description: >- CRM record visibility levels; resolved live against the owner's current teams. enum: - private - team - team_and_subteams - company title: RecordVisibility type: string securitySchemes: SailerApiToken: description: >- A workspace API token. Create one in Settings → API. Send it as `Authorization: Bearer sk_live_...`. scheme: bearer type: http ````