> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clustr-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Client Rule

> Set who counts as a client in one connected CRM

Saves the client rule for one CRM, the same rule as **Targeting > Clients** in
the app. It replaces the saved rule whole. The rule is checked against the CRM's
company schema, then a pull of that CRM's clients starts straight away; after
that the list updates nightly.

A rule has one or both of two conditions:

* **A company property**: `field`, `fieldType` and the `values` that mean
  client. Get the property names, types and options from
  [List Client Rule Fields](https://docs.clustr-ai.com/api-reference/list-client-rule-fields.md).
* **A won deal** (`wonDeal: true`): HubSpot reads `hs_is_closed_won`, Salesforce
  reads `IsWon`, and Attio, which has no won flag, uses the deal stages you list
  in `wonStages`.

With both, `match` is `any` (either is enough, the default) or `all` (both must
hold). Check what a rule selects first with
[Preview Client Rule](https://docs.clustr-ai.com/api-reference/preview-client-rule.md).

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `INVALID_CLIENT_RULE` | No condition, a property that does not exist or values that do not match it, or an Attio won-deal rule with no stages |
| 404 | `CRM_NOT_CONNECTED` | That CRM is not connected for this workspace |
| 502 | `CRM_UNAVAILABLE`, `CRM_SCHEMA_UNAVAILABLE` | The CRM could not be reached; nothing was saved |
| 502 | `CLIENT_COMPANIES_UNAVAILABLE` | A disabled rule was saved but its companies could not be cleared; try again |

```bash cURL theme={null}
curl -X PUT https://api.clustr-ai.com/api/public/client-companies/rule/hubspot \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "field": "customer_status",
    "fieldType": "single_select",
    "values": ["active"],
    "wonDeal": true,
    "match": "any"
  }'
```

```bash Attio, won deals only theme={null}
curl -X PUT https://api.clustr-ai.com/api/public/client-companies/rule/attio \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wonDeal": true, "wonStages": ["8f2c..."], "wonStageLabels": ["Won"]}'
```

```json 200 theme={null}
{
  "success": true,
  "data": {
    "rule": {
      "enabled": true,
      "field": "customer_status",
      "fieldLabel": "Customer status",
      "fieldType": "single_select",
      "values": ["active"],
      "valueLabels": [],
      "wonDeal": true,
      "match": "any",
      "updatedAt": "2026-10-07T10:00:00Z"
    }
  }
}
```


## OpenAPI

````yaml PUT /client-companies/rule/{provider}
openapi: 3.1.0
info:
  title: Clustr Public API
  description: >
    Programmatic access to your Clustr network: import connectors, search warm
    intros (opportunities), and manage target accounts.


    ## Authentication

    All endpoints require a Bearer token (API key) in the `Authorization`
    header.


    ```

    Authorization: Bearer <your_api_key>

    ```


    API keys can be created and managed from the [API settings
    page](https://app.clustr-ai.com/api).
  version: '1.0'
  contact:
    name: Clustr Support
    url: https://clustr-ai.com
servers:
  - url: https://api.clustr-ai.com/api/public
    description: Production
security:
  - BearerAuth: []
paths:
  /client-companies/rule/{provider}:
    parameters:
      - $ref: '#/components/parameters/ClientRuleProvider'
    put:
      tags:
        - Client Companies
      summary: Set Client Rule
      description: |
        Save the client rule for one CRM, replacing the saved one whole. It is
        checked against the CRM's company schema, then a pull of that CRM's
        clients starts straight away.
      operationId: setClientRule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientRuleRequest'
      responses:
        '200':
          description: The rule, as saved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      rule:
                        $ref: '#/components/schemas/ClientRule'
        '400':
          description: The rule is invalid for this CRM (`INVALID_CLIENT_RULE`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing API key
        '404':
          description: >-
            The CRM is not connected (`CRM_NOT_CONNECTED`), or the provider is
            unknown
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: >-
            The CRM or the client list could not be reached (`CRM_UNAVAILABLE`,
            `CRM_SCHEMA_UNAVAILABLE`, `CLIENT_COMPANIES_UNAVAILABLE`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    ClientRuleProvider:
      name: provider
      in: path
      required: true
      schema:
        type: string
        enum:
          - hubspot
          - salesforce
          - attio
      description: >-
        The CRM whose client rule to use. It must be connected to your
        workspace.
  schemas:
    ClientRuleRequest:
      type: object
      description: |
        Who counts as a client in one CRM: a company property condition
        (`field`, `fieldType` and the `values` that mean client), a won deal
        (`wonDeal`), or both, combined by `match`.
      properties:
        confirm:
          type: boolean
          description: >-
            Set Client Rule only (Preview Client Rule ignores it). Changing or
            turning off a rule

            that is on can remove companies from your client list, so such a
            save writes nothing

            and answers `confirmationRequired: true` with `currentRuleMatches`,
            `newRuleMatches`,

            `countIsLowerBound`, a `sample` and a `message`. Send the same
            request with `confirm`

            set to true to apply it.
        enabled:
          type: boolean
          description: >-
            Whether the rule applies. A disabled rule is kept but marks no
            company as a client.
        field:
          type: string
          description: >-
            The company property's API name, from the fields endpoint. Omit
            `field` and `fieldType` for a rule on won deals alone.
        fieldLabel:
          type: string
          description: The property's display name. Filled from the CRM when omitted.
        fieldType:
          type: string
          description: >-
            `boolean`, `single_select`, `multi_select` or `text`, as the fields
            endpoint reports it.
          enum:
            - boolean
            - single_select
            - multi_select
            - text
        values:
          type: array
          items:
            type: string
          description: >-
            The values that mean client: option values for a dropdown,
            `["true"]` for a checkbox, exact text for a text property.
        valueLabels:
          type: array
          items:
            type: string
          description: Display labels for `values`, in the same order.
        wonDeal:
          type: boolean
          description: |
            A company with at least one won deal is a client: HubSpot
            `hs_is_closed_won`, Salesforce `IsWon`, Attio a deal in one of
            `wonStages`.
        wonStages:
          type: array
          items:
            type: string
          description: >-
            Attio only, and required there with `wonDeal`: the ids of the deal
            stages that count as won, from `dealStages`. Ignored for HubSpot and
            Salesforce.
        wonStageLabels:
          type: array
          items:
            type: string
          description: 'Attio only: display labels for `wonStages`, in the same order.'
        match:
          type: string
          enum:
            - any
            - all
          default: any
          description: >-
            With both conditions, `any` (either is enough) or `all` (both must
            hold).
    ClientRule:
      allOf:
        - $ref: '#/components/schemas/ClientRuleRequest'
        - type: object
          properties:
            updatedAt:
              type: string
              format: date-time
              description: When the rule was last saved.
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            message:
              type: string
              example: Invalid request body
            code:
              type: string
              example: BAD_REQUEST
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: The API key you created on the API settings page of the Clustr app.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.