> ## 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 Team Titles

> Replace the job titles the competitor team search looks for

Replace your workspace's title list. Send the whole list: a title you leave out is dropped. To
switch a title off without losing it, send it with `enabled: false`.

People already tracked stay as they are. The new list applies from the next team search, where the
new matches are followed automatically while you have free slots. Read the current list with
[Get Competitor Team Titles](https://docs.clustr-ai.com/api-reference/get-competitor-team-titles.md).

```bash cURL theme={null}
curl -X PUT https://api.clustr-ai.com/api/public/competitor-team-titles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "titles": [
      { "title": "account executive", "function": "sales", "enabled": true },
      { "title": "customer success manager", "function": "cs", "enabled": true },
      { "title": "solutions engineer", "function": "sales", "enabled": true }
    ]
  }'
```

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

requests.put(
    "https://api.clustr-ai.com/api/public/competitor-team-titles",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "titles": [
            {"title": "account executive", "function": "sales", "enabled": True},
            {"title": "customer success manager", "function": "cs", "enabled": True},
            {"title": "solutions engineer", "function": "sales", "enabled": True},
        ]
    },
)
```

```javascript JavaScript theme={null}
await fetch("https://api.clustr-ai.com/api/public/competitor-team-titles", {
  method: "PUT",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    titles: [
      { title: "account executive", function: "sales", enabled: true },
      { title: "customer success manager", function: "cs", enabled: true },
      { title: "solutions engineer", function: "sales", enabled: true },
    ],
  }),
});
```

```json 200 theme={null}
{
  "success": true,
  "data": {
    "titles": [
      { "title": "account executive", "function": "sales", "group": "sales", "enabled": true },
      { "title": "customer success manager", "function": "cs", "group": "cs", "enabled": true },
      { "title": "solutions engineer", "function": "sales", "group": "customer_facing", "enabled": true }
    ],
    "is_default": false
  }
}
```


## OpenAPI

````yaml PUT /competitor-team-titles
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:
  /competitor-team-titles:
    put:
      tags:
        - Competitor Monitoring
      summary: Set Competitor Team Titles
      description: >-
        Replaces the title list. The new list applies from the next team search;
        people already tracked keep their current status.
      operationId: setCompetitorTeamTitles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - titles
              properties:
                titles:
                  type: array
                  description: The titles, from 1 to 300.
                  minItems: 1
                  maxItems: 300
                  items:
                    type: object
                    required:
                      - title
                    properties:
                      title:
                        type: string
                        description: >-
                          A job title keyword, matched case-insensitively
                          against the person's current title.
                      function:
                        type: string
                        description: >-
                          The function the title belongs to: `sales`, `cs` or
                          `other`. Defaults to `other`.
                        enum:
                          - sales
                          - cs
                          - other
                      group:
                        type: string
                        enum:
                          - sales
                          - cs
                          - exec
                          - founder
                          - customer_facing
                          - custom
                        description: >-
                          The role group this title belongs to. A competitor set
                          to follow a group (in its `title_groups`) is searched
                          with every title in that group. Send `custom` for a
                          title you add yourself. When you leave it out, a title
                          from the default list keeps the group the default list
                          assigns it.
                        example: custom
                      enabled:
                        type: boolean
                        description: >-
                          Whether the team search uses this title. Defaults to
                          `true`.
      responses:
        '200':
          description: The title list, as stored
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/CompetitorTeamTitles'
        '400':
          description: Empty or invalid list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing API key
components:
  schemas:
    CompetitorTeamTitles:
      type: object
      properties:
        titles:
          type: array
          items:
            $ref: '#/components/schemas/CompetitorTeamTitle'
        is_default:
          type: boolean
          description: True while the workspace uses the default list.
    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
    CompetitorTeamTitle:
      type: object
      properties:
        title:
          type: string
          example: account executive
        function:
          type: string
          enum:
            - sales
            - cs
            - other
        group:
          type: string
          enum:
            - sales
            - cs
            - exec
            - founder
            - customer_facing
            - custom
          description: >-
            The role group the title belongs to, which title_groups on a
            competitor selects; `custom` for a title you added.
        enabled:
          type: boolean
  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.