> ## 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.

# Add Competitor Customer

> Add a company you know buys from a competitor

Add a company you know is one of a competitor's customers, for example an account you won from
them. It is saved as a confirmed customer whatever the competitor's website shows, and it stays
on the list even when no evidence is found. It is listed with `sources` set to `["user"]`.

Send the company's name, and its LinkedIn company number and domain when you have them. If the
competitor already has that company as a customer, it is confirmed and the answer is `200`
instead of `201`.

To undo, clear its verdict with
[Set Competitor Customer Verdict](https://docs.clustr-ai.com/api-reference/set-competitor-customer-verdict.md).

```bash cURL theme={null}
curl -X POST https://api.clustr-ai.com/api/public/competitors/cmp_r0jpyyqyeh0txpgdhb604j2g9s/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_name": "Northwind Media", "domain": "northwind.com"}'
```

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

requests.post(
    "https://api.clustr-ai.com/api/public/competitors/cmp_r0jpyyqyeh0txpgdhb604j2g9s/customers",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"company_name": "Northwind Media", "domain": "northwind.com"},
)
```

```javascript JavaScript theme={null}
await fetch("https://api.clustr-ai.com/api/public/competitors/cmp_r0jpyyqyeh0txpgdhb604j2g9s/customers", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ company_name: "Northwind Media", domain: "northwind.com" }),
});
```

```json 201 theme={null}
{
  "success": true,
  "data": {
    "clustr_competitor_customer_id": "ccus_3jm919aa345jdss56074sb5vy2",
    "id": "8b4e2f6a-1c3d-4e5f-9a7b-0c2d4e6f8a1b",
    "company_name": "Northwind Media",
    "user_verdict": "confirmed",
    "created": true
  }
}
```

```json 404 theme={null}
{
  "success": false,
  "error": { "message": "Competitor not found", "code": "NOT_FOUND" }
}
```


## OpenAPI

````yaml POST /competitors/{id}/customers
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:
  /competitors/{id}/customers:
    post:
      tags:
        - Competitor Monitoring
      summary: Add Competitor Customer
      description: >-
        Adds a company you know is one of a competitor's customers. It is saved
        as a confirmed customer whatever the competitor's website shows, stays
        listed when no evidence is found, and is listed with `sources`
        `["user"]`. Adding a company the competitor already has as a customer
        confirms it. To undo, clear its verdict with [Set Competitor Customer
        Verdict](/api-reference/set-competitor-customer-verdict).
      operationId: addCompetitorCustomer
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            The competitor's Clustr ID (`cmp_…`), from [List
            Competitors](/api-reference/list-competitors).

            The id from earlier responses also works.
          schema:
            type: string
          example: cmp_6nymp4sgpm9xj1tc9xb2q7s7yj
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - company_name
              properties:
                company_name:
                  type: string
                  description: The company's name.
                  example: Northwind Media
                linkedin_numeric_id:
                  type: string
                  description: The company's LinkedIn company number, when you have it.
                  example: '64646209'
                domain:
                  type: string
                  description: The company's website or domain, when you have it.
                  example: northwind.com
      responses:
        '200':
          description: >-
            The company already was one of the competitor's customers, and is
            now confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompetitorCustomerAdded'
        '201':
          description: The customer, added and confirmed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompetitorCustomerAdded'
        '400':
          description: No company name, or a LinkedIn company number that is not a number
        '401':
          description: Invalid or missing API key
        '403':
          description: Competitor monitoring is not enabled for this workspace
        '404':
          description: Competitor not found
components:
  schemas:
    CompetitorCustomerAdded:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            clustr_competitor_customer_id:
              type: string
              description: >-
                The customer's Clustr ID, for example
                `ccus_zxv0c9v5mnb25zthavkh5jm5yn`. Use it to refer to this

                customer.
              example: ccus_zxv0c9v5mnb25zthavkh5jm5yn
            id:
              type: string
              description: >-
                Kept for integrations built before Clustr IDs. New integrations
                should use `clustr_competitor_customer_id`.
            company_name:
              type: string
              example: Northwind Media
            user_verdict:
              type: string
              example: confirmed
            created:
              type: boolean
              description: >-
                False when the company already was one of the competitor's
                customers.
  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.