---
title: "Search accounts"
method: POST
path: "/v1/accounts/search"
tags: ["CRM"]
---

# Search accounts

`POST /v1/accounts/search`

Search accounts with structured filters, sort, cursor pagination, and field projection. Custom attribute names and value types are returned in `data.custom_field_definitions`; keys in that map match keys under each account's `custom_fields` object.

## Request body

- SearchRequest
  - `query` string
  - `q` string
  - `filters` SearchFilter[]
    - `field` string, required — Public field name, system field alias, or custom field slug.
    - `operator` 'eq' | 'neq' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'in' | 'not_in' | 'gt' | 'gte' | 'lt' | 'lte' | 'between' | 'empty' | 'not_empty' | 'contains_all' | 'contains_none' — Filter operator. For multi-value operators such as `in`, `not_in`, `between`, `contains_all`, and `contains_none`, pass an array in `value`.
    - `value` union — Filter value. For date/time fields such as `created_at`, `updated_at`, `close_date`, and custom date/timestamp fields, pass an ISO 8601 date or date-time string such as `2024-06-11T01:40:00Z`; Unix timestamps such as `1718070000` are not accepted in search filters. Use an array here for multi-value operators; omit for `empty` and `not_empty`.
      - string
      - number
      - boolean
      - unknown[]
        - unknown
  - `sort` union
    - string — Compact sort expression. Use `field`, `field:asc`, or `field:desc`.
    - SearchSort
      - `field` string, required
      - `direction` 'asc' | 'desc'
    - SearchSort[]
      - `field` string, required
      - `direction` 'asc' | 'desc'
  - `cursor` string, nullable
  - `limit` integer
  - `fields` string[]

## Response `200`

Accounts were returned.

- object
  - `success` boolean
  - `message` string
  - `data` object — Endpoint-specific response payload.
    - `custom_field_definitions` CustomFieldDefinitions, required — Map of custom field slug to definition. This is returned by `/v1/accounts`, `/v1/accounts/search`, `/v1/contacts`, `/v1/contacts/search`, `/v1/opportunities`, and `/v1/opportunities/search`. The map key matches the key used under each record's `custom_fields` object. If the request uses `fields`, only selected custom fields are included; otherwise all visible custom fields for the object are included. For opportunities, definitions are scoped to the requested `pipeline_id`.
    - `has_more` boolean, required — Whether another page is available.
    - `next_cursor` string, nullable, required — Cursor to pass on the next request when `has_more` is true.
    - `limit` integer, required — Effective page size used for this response.
    - `accounts` AccountRecord[], required
      - `id` string, uuid
      - `name` string, nullable
      - `domain` string, nullable
      - `custom_fields` RecordCustomFields — Custom field values keyed by custom field slug. Use the sibling `custom_field_definitions` map in the same response to get each custom field's display name (`current_name`), stable property name (`property_name`), and value type (`attribute_type`).

## Other responses

- `400` — The request failed validation.
- `401` — The API key is missing, invalid, or not allowed to access this route.
- `429` — The route rate limit was exceeded.

---

[API](https://skmtc.net/octolane-org/apis/octolane-public-api.md) · [All operations](https://skmtc.net/octolane-org/apis/octolane-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/octolane-org/octolane-public-api/revisions/d248d0a2be5d/schema)