> ## 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 buyer titles

> Add job titles of the people you sell to

Adds one or more [buyer titles](https://docs.clustr-ai.com/buyer-titles.md). Titles are trimmed, and a title
already on the list is skipped. The change applies to everyone already in your
workspace within seconds.

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `BAD_REQUEST` | `keywords` is missing or holds no non-empty title, or the list would pass 1,000 titles |

```bash cURL theme={null}
curl -X POST https://api.clustr-ai.com/api/public/buyer-titles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["CFO", "Head of Finance"]}'
```

```json 201 theme={null}
{
  "success": true,
  "data": {
    "inserted": 2,
    "total": 2,
    "rematches_existing_prospects": true,
    "matching_note": "Keywords and exclusions apply to everyone in your workspace, including people already imported. They also decide who your next ingestion run brings in."
  }
}
```


## OpenAPI

````yaml POST /buyer-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:
  /buyer-titles:
    post:
      tags:
        - Buyer Titles
      summary: Add buyer titles
      description: |
        Add one or more buyer titles. Titles are trimmed, and a title already on
        the list is skipped. The change applies to everyone already imported
        within seconds, and decides who your next imports bring in.
      operationId: addBuyerTitles
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddJobTitlesRequest'
      responses:
        '201':
          description: How many titles were new
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddJobTitlesResponse'
        '400':
          description: Every title sent is empty, or the list would pass 1,000 titles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing API key
components:
  schemas:
    AddJobTitlesRequest:
      type: object
      required:
        - keywords
      properties:
        keywords:
          type: array
          minItems: 1
          items:
            type: string
          description: The job titles to exclude. The list holds at most 1,000 titles.
          example:
            - CFO
            - Head of Finance
    AddJobTitlesResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            inserted:
              type: integer
              description: How many titles were new
              example: 1
            total:
              type: integer
              description: How many distinct non-empty titles you sent
              example: 2
    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.