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

# Import excluded companies

> Exclude up to 500 companies in one call

Excludes many companies at once, such as a list of competitors, partners or
existing customers from a spreadsheet. Send up to 500 rows per request, the size
of the list itself.

**Each row is checked on its own,** with the same rules as
[Exclude a company](https://docs.clustr-ai.com/api-reference/exclude-company.md): at least one of `domain`,
`linkedinVanityName`, `linkedinNumericId` or `companyId`. Valid rows are excluded,
invalid rows come back in `invalid` with their row number and the reason, and one
bad row never blocks the others.

**Re-running an import is safe.** A company that is already excluded, matched on
any of its keys, is skipped and counted in `alreadyExcluded`, and so is a repeat of
the same company within one request.

**The list holds at most 500 companies.** Rows past that come back in `invalid`
with the reason `The exclusion list is full (maximum 500 companies)`; the ones
before it are still excluded.

The **Import CSV** button on **Targeting > Excluded** sends the same request from a
file.

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `BAD_REQUEST` | The body is not valid JSON, has no rows, or has more than 500 |

```bash cURL theme={null}
curl -X POST https://api.clustr-ai.com/api/public/excluded-companies/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows": [
        {"row": 2, "label": "Acme Corp", "domain": "acme.com", "reason": "Competitor"},
        {"row": 3, "label": "Globex", "linkedinVanityName": "https://www.linkedin.com/company/globex"},
        {"row": 4, "label": "Initech", "linkedinVanityName": "https://www.linkedin.com/in/bill-lumbergh"}
      ]}'
```

```json 200 theme={null}
{
  "success": true,
  "data": {
    "added": 1,
    "alreadyExcluded": 1,
    "invalid": [
      { "row": 4, "reason": "That LinkedIn URL is not a company page (linkedin.com/company/...)" }
    ],
    "excludedCompanies": [
      {
        "clustrExcludedCompanyId": "exco_rd79v8mryqk4krgjns3zkfx6ej",
        "clustrWorkspaceId": "ten_93tdpgecrrpwmf19spn5k2cds3",
        "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d",
        "tenantId": "3b0f6a52-1c9e-4d7a-8f21-5e6c7d8a9b10",
        "linkedinVanityName": "globex",
        "label": "Globex",
        "createdAt": "2026-10-12T09:30:00Z"
      }
    ]
  }
}
```

```json 400 theme={null}
{
  "success": false,
  "error": { "message": "Exclude at most 500 companies per request", "code": "BAD_REQUEST" }
}
```


## OpenAPI

````yaml POST /excluded-companies/import
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:
  /excluded-companies/import:
    post:
      tags:
        - Excluded Companies
      summary: Import excluded companies
      description: >
        Exclude up to 500 companies in one call. Each row is checked on its own:

        a valid row is excluded, an invalid one is returned in `invalid` with
        its

        row number and reason, and the rest of the request still goes through.
      operationId: importExcludedCompanies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportExcludedCompaniesRequest'
      responses:
        '200':
          description: What was excluded, skipped and rejected
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/ImportExcludedCompaniesResult'
        '400':
          description: Invalid body, no rows, or more than 500 rows
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing API key
components:
  schemas:
    ImportExcludedCompaniesRequest:
      type: object
      required:
        - rows
      properties:
        rows:
          type: array
          description: The companies to exclude, between 1 and 500.
          minItems: 1
          maxItems: 500
          items:
            allOf:
              - $ref: '#/components/schemas/ExcludedCompanyInput'
              - type: object
                properties:
                  row:
                    type: integer
                    description: >-
                      Your own row number, such as the spreadsheet line. Echoed
                      back if the row is

                      invalid so you can find it. When omitted, it is the row's
                      position in `rows`,

                      starting at 1.
                    example: 2
    ImportExcludedCompaniesResult:
      type: object
      properties:
        added:
          type: integer
          description: How many companies this call excluded.
          example: 41
        alreadyExcluded:
          type: integer
          description: >-
            How many valid rows were skipped because the company was already
            excluded, including repeats within the same request.
          example: 3
        invalid:
          type: array
          description: >-
            The rows that were rejected. Each has `row` (your number) and
            `reason`.
          items:
            type: object
            properties:
              row:
                type: integer
                example: 14
              reason:
                type: string
                example: Give a domain, a LinkedIn company URL, or a company to exclude
        excludedCompanies:
          type: array
          description: >-
            The exclusions this call added, in the shape [List excluded
            companies](/api-reference/list-excluded-companies)

            returns, with their ids for [Remove an
            exclusion](/api-reference/remove-excluded-company).
          items:
            $ref: '#/components/schemas/ExcludedCompany'
    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
    ExcludedCompanyInput:
      type: object
      description: >-
        One company to exclude. Send at least one of `domain`,
        `linkedinVanityName`, `linkedinNumericId` or `companyId`.
      properties:
        label:
          type: string
          description: >-
            The name shown on the list, for display only. Defaults to the first
            key you give.
          example: Acme Corp
        domain:
          type: string
          description: >
            A domain or website, stored as the bare host:
            `https://www.acme.com/about`

            becomes `acme.com`. A LinkedIn URL sent here is read as
            `linkedinVanityName`.
          example: acme.com
        linkedinVanityName:
          type: string
          description: >-
            The company's LinkedIn slug, or its LinkedIn company page URL

            (`linkedin.com/company/acme-corp`). A LinkedIn URL that is not a
            company page,

            such as a person's profile, is rejected.
          example: https://www.linkedin.com/company/acme-corp
        linkedinNumericId:
          type: string
          example: '1035'
          description: LinkedIn's own numeric id for the company.
        companyId:
          type: string
          description: >-
            The account's Clustr ID (`acc_…`), when you have one. The company id
            from earlier responses also

            works.
        reason:
          type: string
          description: >-
            Why the company is excluded. It is shown on the list, for display
            only.
          example: Competitor
    ExcludedCompany:
      type: object
      properties:
        clustrExcludedCompanyId:
          type: string
          description: >-
            The exclusion's Clustr ID, for example
            `exco_gs55xmz75eekyeen4gcze1vn6d`. Use it to refer to

            this exclusion.
          example: exco_gs55xmz75eekyeen4gcze1vn6d
        clustrWorkspaceId:
          type: string
          description: >-
            The workspace's Clustr ID, for example
            `ten_d7ybajxezg97cghd2y3x7am2qg`.
          example: ten_d7ybajxezg97cghd2y3x7am2qg
        clustrAccountId:
          type: string
          description: >-
            The Clustr ID of the account it matched, for example
            `acc_5x3vqy454qx6m6q2thvk020zmn`. For a

            company Clustr does not know yet, it is filled in once that company
            appears.
          example: acc_5x3vqy454qx6m6q2thvk020zmn
        clustrCreatedByUserId:
          type: string
          description: >-
            The Clustr ID of the member who added it, for example
            `usr_z21gb6gp5qg90dfrsf5hb5dfdj`.
          example: usr_z21gb6gp5qg90dfrsf5hb5dfdj
        id:
          type: string
          format: uuid
          description: >-
            Kept for integrations built before Clustr IDs. New integrations
            should use `clustrExcludedCompanyId`.
        tenantId:
          type: string
          format: uuid
          description: >-
            Kept for integrations built before Clustr IDs. New integrations
            should use `clustrWorkspaceId`.
        companyId:
          type: string
          description: >-
            Kept for integrations built before Clustr IDs. New integrations
            should use `clustrAccountId`.
        linkedinNumericId:
          type: string
          example: '1035'
        linkedinVanityName:
          type: string
          description: The LinkedIn company slug, lower-cased.
          example: acme-corp
        domain:
          type: string
          description: The bare host, without scheme, `www.` or path.
          example: acme.com
        label:
          type: string
          description: The name shown on the list, for display only.
          example: Acme Corp
        reason:
          type: string
          example: Competitor
        createdBy:
          type: string
          description: >-
            Kept for integrations built before Clustr IDs. New integrations
            should use `clustrCreatedByUserId`.
        createdAt:
          type: string
          format: date-time
  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.