This endpoint performs an upsert operation: it creates a new companies segment or updates an existing one
based on the segment_id you provide.

If segment_id is provided:

• The segment with that ID will be updated
• If the segment doesn't exist or is being deleted, a 404 error will be returned

If segment_id is not provided:

• A new segment will be created

What is a Segment?

A segment is a dynamic or static list of companies that match a set of conditions.
When a segment is created or its filters change, Customerly automatically computes
which companies belong to it.

The filters field — Predicate Structure

The filters field defines which companies belong to this segment. It is a predicate tree with:

Root object:

{
  "audience": "<audience_value>",
  "operation": { ... }
}

audience (required) — for companies segments the only supported value is:

• "is_any_company" — all companies

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

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 such as "name", "website", "created_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 another companies segment:

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

Examples

Example 1 — All companies on the "enterprise" plan:

{
  "audience": "is_any_company",
  "operation": {
    "type": "condition",
    "target": "company_state",
    "name": "plan",
    "operation": "is",
    "value": "enterprise"
  }
}

Example 2 — Companies with MRR above 1000 AND at least 50 employees:

{
  "audience": "is_any_company",
  "operation": {
    "type": "operation",
    "operator": "and",
    "predicates": [
      {
        "type": "condition",
        "target": "company_state",
        "name": "mrr",
        "operation": "greater_than",
        "value": 1000
      },
      {
        "type": "condition",
        "target": "company_state",
        "name": "employees",
        "operation": "greater_than",
        "value": 50
      }
    ]
  }
}

Example 3 — Companies in segment 5 but NOT in segment 12:

{
  "audience": "is_any_company",
  "operation": {
    "type": "operation",
    "operator": "and",
    "predicates": [
      {
        "type": "condition",
        "target": "companies_segment",
        "operation": "is",
        "value": 5
      },
      {
        "type": "condition",
        "target": "companies_segment",
        "operation": "is_not",
        "value": 12
      }
    ]
  }
}

Errors

• 422 segment_invalid_filters — malformed predicate (unknown target, invalid operation, missing required fields)
• 422 segment_circular_dependency — the filters reference this or other segments in a circular way