Returns a paginated list of the companies matching an arbitrary predicate tree — the same engine that
powers companies segments, but evaluated on the fly without having to create a segment first.

Use GET /companies when a simple name keyword search is enough. Use this endpoint when you need to
combine several conditions with and/or, or to filter on company attributes and segment membership.

Pagination

This endpoint uses offset-based pagination:

1. First request: POST /companies/filter with { "per_page": 20 }
2. The response returns a cursor (the offset of the next page, e.g. 20)
3. Next page: repeat the same body adding "cursor": 20
4. Continue until cursor is null (no more companies)

cursor is an offset, not a company ID. Keep filters, sort_by and order identical across pages,
otherwise the offset points at a different result set.

Sorting

• sort_by: name, created_at or last_seen_at. If omitted, companies are sorted by internal ID
  (creation order).
• order: ascending or descending (default: descending).

Counting before listing

To know how many companies match a predicate — without paging through them — call
POST /companies/filter/count with the same filters payload.

The filters field — Predicate Structure

filters is a predicate tree. Omit it (or send null) to match every company.

Root object:

{
  "audience": "is_any_company",
  "operation": { ... }
}

audience (required) — the only accepted value is "is_any_company": unlike contacts, companies have
no sub-types to restrict.

operation (optional) — a predicate node, either an operation or a condition:

Operation node (combines multiple predicates):

{
  "type": "operation",
  "operator": "and",
  "predicates": [ ... ]
}

• operator: "and" or "or" (lowercase)
• predicates: array of condition or operation nodes (they can be nested at any depth)

Condition node (single filter rule):

{
  "type": "condition",
  "target": "<target>",
  "operation": "<operation>",
  "value": "<value>"
}

Condition Targets and Operations

company_state — Company attribute. Requires name (the attribute key, e.g. "plan", or a default
company field: "name", "company_id" — your custom_company_id —, "created_at", "last_seen_at").
The operation set depends on the value type:

• string: is, is_not, starts_with, ends_with, contains, does_not_contain
• number: greater_than, less_than, equal_to, not_equal
• boolean: is_true, is_false
• date: date_on, date_before, date_after, date_exactly, date_more_than, date_less_than,
  date_more_than_hours, date_less_than_hours, date_more_than_ahead, date_less_than_ahead,
  date_more_than_hours_ahead, date_less_than_hours_ahead
• any type: has_any_value, is_unknown (no value needed)

For date_on, date_before and date_after, value is a date (timestamp or parsable date string). For
the other date operations, value is a number of days (or hours, for the _hours variants).

companies_segment — Membership in a companies segment:

• operation: is, is_not
• value: segment_id (integer)

Unsupported targets

Everything that describes a contact rather than a company — state, tag, event, campaign,
campaigns_multiple, segment — the real-time messenger targets (page, stats, platform,
office_hours, incoming_message) and every conversation_* target cannot be evaluated against
companies. Using them here returns 422 company_invalid_filters.

Examples

Example 1 — First page of companies on the enterprise plan, sorted by name:

{
  "per_page": 50,
  "sort_by": "name",
  "order": "ascending",
  "filters": {
    "audience": "is_any_company",
    "operation": {
      "type": "condition",
      "target": "company_state",
      "name": "plan",
      "operation": "is",
      "value": "enterprise"
    }
  }
}

Example 2 — Companies with more than 100 seats that were seen in the last 7 days:

{
  "filters": {
    "audience": "is_any_company",
    "operation": {
      "type": "operation",
      "operator": "and",
      "predicates": [
        { "type": "condition", "target": "company_state", "name": "seats", "operation": "greater_than", "value": 100 },
        { "type": "condition", "target": "company_state", "name": "last_seen_at", "operation": "date_less_than", "value": 7 }
      ]
    }
  }
}

Example 3 — Companies in segment 10 but not in segment 20, second page:

{
  "per_page": 20,
  "cursor": 20,
  "filters": {
    "audience": "is_any_company",
    "operation": {
      "type": "operation",
      "operator": "and",
      "predicates": [
        { "type": "condition", "target": "companies_segment", "operation": "is", "value": 10 },
        { "type": "condition", "target": "companies_segment", "operation": "is_not", "value": 20 }
      ]
    }
  }
}

Example 4 — Companies created less than 30 days ago whose name contains acme, or that have no plan set:

{
  "filters": {
    "audience": "is_any_company",
    "operation": {
      "type": "operation",
      "operator": "or",
      "predicates": [
        {
          "type": "operation",
          "operator": "and",
          "predicates": [
            { "type": "condition", "target": "company_state", "name": "created_at", "operation": "date_less_than", "value": 30 },
            { "type": "condition", "target": "company_state", "name": "name", "operation": "contains", "value": "acme" }
          ]
        },
        { "type": "condition", "target": "company_state", "name": "plan", "operation": "is_unknown" }
      ]
    }
  }
}