> ## 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 Competitor CRM Properties

> Write competitor customers, confidence and last engagement onto your CRM companies

Turns competitor properties on or off for one connected CRM, and chooses the company field each
one writes. Send only the properties you want to change: one you leave out keeps its saved
setting. Admin only.

| Key | What lands on the company |
| - | - |
| `competitor_customer` | The competitors the company is a customer of |
| `competitor_confidence` | `confirmed`, `likely` or `possible` |
| `competitor_last_engagement` | The date a competitor's people last engaged someone at the company |

On HubSpot, Clustr creates a company property for each one (`clustr_competitor_customer`,
`clustr_competitor_confidence` and `clustr_last_competitor_engagement`) unless you name a field
of your own. On Salesforce and Attio, create the field first and name it in `field`: Clustr does
not create fields there. A field you name must exist on the CRM and be writable.

> [!NOTE]
>
> **Values stay current.** Turning a property on starts a CRM sync, and every sync after it
> rewrites the values. When you reject a customer, or a competitor takes it off their site,
> the next sync clears the field on that company. Companies Clustr never linked to a competitor
> are left alone.

## Errors

| Status | Code | When |
| - | - | - |
| 400 | | An unknown property, or a property turned on with no field on Salesforce or Attio, or a field that does not exist or is read-only |
| 403 | | The key's workspace role is not admin |
| 404 | `CRM_NOT_CONNECTED` | That CRM is not connected for this workspace |

```bash cURL theme={null}
curl -X PUT "https://api.clustr-ai.com/api/public/crm/competitor-properties?provider=hubspot" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"properties": {"competitor_customer": {"enabled": true}, "competitor_confidence": {"enabled": true}}}'
```

```python Python theme={null}
import requests

requests.put(
    "https://api.clustr-ai.com/api/public/crm/competitor-properties",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"provider": "hubspot"},
    json={"properties": {"competitor_customer": {"enabled": True}, "competitor_confidence": {"enabled": True}}},
)
```

```javascript JavaScript theme={null}
await fetch("https://api.clustr-ai.com/api/public/crm/competitor-properties?provider=hubspot", {
  method: "PUT",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    properties: { competitor_customer: { enabled: true }, competitor_confidence: { enabled: true } },
  }),
});
```

```json 200 theme={null}
{
  "success": true,
  "data": {
    "provider": "hubspot",
    "properties": [
      { "key": "competitor_customer", "label": "Competitor customer", "enabled": true, "field": "", "defaultField": "clustr_competitor_customer", "effectiveField": "clustr_competitor_customer" },
      { "key": "competitor_confidence", "label": "Competitor customer confidence", "enabled": true, "field": "", "defaultField": "clustr_competitor_confidence", "effectiveField": "clustr_competitor_confidence" },
      { "key": "competitor_last_engagement", "label": "Last competitor engagement", "enabled": false, "field": "", "defaultField": "clustr_last_competitor_engagement", "effectiveField": "clustr_last_competitor_engagement" }
    ],
    "resync": "triggered"
  }
}
```


## OpenAPI

````yaml PUT /crm/competitor-properties
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:
  /crm/competitor-properties:
    parameters:
      - name: provider
        in: query
        required: true
        description: >-
          The CRM to read or change: `hubspot`, `salesforce` or `attio`. That
          CRM must be connected to your workspace.
        schema:
          type: string
          enum:
            - hubspot
            - salesforce
            - attio
        example: hubspot
    put:
      tags:
        - Competitor Monitoring
      summary: Set Competitor CRM Properties
      description: >
        Turns competitor properties on or off for one connected CRM, and chooses
        the company

        field each one writes. Send only the properties you want to change: one
        you leave out

        keeps its saved setting. Admin only.


        On HubSpot, Clustr creates a property for each one unless you name a
        field of your own.

        On Salesforce and Attio, create the field first and name it: Clustr does
        not create

        fields there. A field you name must exist on the CRM and be writable.


        Turning a property on starts a CRM sync, and `resync` in the response
        reports how that

        went. After that, every sync keeps the values current, and clears them
        on a company

        that is no longer a competitor's customer.
      operationId: setCompetitorCrmProperties
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                properties:
                  type: object
                  description: >-
                    The property key (`competitor_customer`,
                    `competitor_confidence` or `competitor_last_engagement`) to
                    its new setting.
                  additionalProperties:
                    $ref: '#/components/schemas/CompetitorCrmPropertyInput'
            examples:
              turn_on:
                summary: Write the competitor names into HubSpot
                value:
                  properties:
                    competitor_customer:
                      enabled: true
      responses:
        '200':
          description: The saved competitor properties
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    allOf:
                      - $ref: '#/components/schemas/CompetitorCrmProperties'
                      - type: object
                        properties:
                          resync:
                            type: string
                            enum:
                              - triggered
                              - already_running
                              - unchanged
                              - skipped
                            description: >-
                              What happened to the CRM sync after the save.
                              `triggered`: a sync started and writes the values.
                              `already_running`: a sync was already in progress.
                              `unchanged`: nothing was turned on. `skipped`: the
                              next scheduled sync writes the values.
                            example: triggered
        '400':
          description: >-
            An unknown property, or a property turned on with no field on
            Salesforce or Attio
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing API key
        '403':
          description: The key's workspace role is not admin
        '404':
          description: >-
            That CRM is not connected to your workspace (code
            `CRM_NOT_CONNECTED`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CompetitorCrmPropertyInput:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether Clustr writes this property.
        field:
          type: string
          description: >-
            The CRM company field to write, by its API name. `""` means the
            default: the property Clustr creates on HubSpot.
    CompetitorCrmProperties:
      type: object
      required:
        - provider
        - properties
      properties:
        provider:
          type: string
          example: hubspot
        properties:
          type: array
          items:
            type: object
            required:
              - key
              - label
              - enabled
              - field
              - defaultField
              - effectiveField
            properties:
              key:
                type: string
                enum:
                  - competitor_customer
                  - competitor_confidence
                  - competitor_last_engagement
              label:
                type: string
              enabled:
                type: boolean
              field:
                type: string
                description: The field you named. `""` means the default.
              defaultField:
                type: string
                description: >-
                  The property Clustr creates on HubSpot. `""` on Salesforce and
                  Attio.
              effectiveField:
                type: string
                description: The field Clustr writes.
    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.