> ## 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 Target Account Tier

> File one target account under a tier

Sets which tier a target account belongs to, using the name your workspace uses
or the tier's [Clustr ID](https://docs.clustr-ai.com/clustr-ids.md).

This is a separate endpoint from the account's own fields on purpose: a tier
belongs to the **company** behind the target account (the same record the
Accounts and People tables show a tier on), so setting one here and setting one
in the app write the same thing.

Send one of the two. `tier_id` wins if you send both.

> [!NOTE]
>
> **Tier names are yours.** One workspace uses "A / B / C", the next uses
> "Strategic / Growth / Watch". An unknown name is rejected rather than created,
> and the error lists where to find the real ones, so read the vocabulary before
> writing to it.

> [!WARNING]
>
> **409 means the account has not matched a company yet.** A tier attaches to the
> company behind an account, so until Clustr has matched one there is nothing to
> file. The fix is to add or correct the account's LinkedIn URL, which makes the
> match exact. This is the one failure here that is about your data rather than
> your request.

```bash cURL (by name) theme={null}
curl -X PATCH "https://api.clustr-ai.com/api/public/target-accounts/a1b2c3d4-.../tier" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier": "Tier 1"}'
```

```bash cURL (clear it) theme={null}
curl -X PATCH "https://api.clustr-ai.com/api/public/target-accounts/a1b2c3d4-.../tier" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tier": ""}'
```

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

requests.patch(
    "https://api.clustr-ai.com/api/public/target-accounts/a1b2c3d4-.../tier",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"tier": "Tier 1"},
)
```

```javascript JavaScript theme={null}
await fetch(
  "https://api.clustr-ai.com/api/public/target-accounts/a1b2c3d4-.../tier",
  {
    method: "PATCH",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ tier: "Tier 1" }),
  },
);
```

```json 200 theme={null}
{
  "success": true,
  "data": {
    "target_account": {
      "clustr_target_account_id": "tacc_jybe005qdjmzf6wfzat2qwfr4m",
      "clustr_tier_id": "tier_e0zk0smsdyw6sb6qnvm93enef4",
      "clustr_account_id": "acc_jebpt1d3egm3196vqqm8c5s1fb",
      "id": "a1b2c3d4-...",
      "account_name": "Acme Corp",
      "account_linkedin_url": "https://www.linkedin.com/company/acme-corp",
      "tier": "Tier 1",
      "tier_id": "7f3e1a22-...",
      "company_id": "9c4d5e6f-..."
    }
  }
}
```

```json 400 theme={null}
{
  "success": false,
  "error": {
    "message": "No tier named \"Platinum\" in this workspace. Tiers are named per workspace; list them at GET /public/tenant-tiers",
    "code": "BAD_REQUEST"
  }
}
```

```json 401 theme={null}
{
  "success": false,
  "error": {
    "message": "Invalid or missing API key",
    "code": "UNAUTHORIZED"
  }
}
```

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

```json 409 theme={null}
{
  "success": false,
  "error": {
    "message": "This target account does not match any company yet, so there is no account to tier. Add or correct its LinkedIn URL first.",
    "code": "CONFLICT"
  }
}
```


## OpenAPI

````yaml PATCH /target-accounts/{accountID}/tier
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:
  /target-accounts/{accountID}/tier:
    patch:
      tags:
        - Target Accounts
      summary: Set Target Account Tier
      description: |
        File one target account under a tier.

        Send `tier` (your workspace's own label) or `tier_id`. An empty value on
        either clears the tier; `tier_id` wins when both arrive.

        Each workspace chooses its own tier names ("A/B/C" for one, "Strategic /
        Growth / Watch" for another), so read them first with
        [List Account Tiers](/api-reference/list-tiers). An unknown tier name
        answers 400.

        A target account can carry a tier once it has matched a company. Until
        then the request answers 409; add or correct the account's LinkedIn URL
        so it can match.
      operationId: setTargetAccountTier
      parameters:
        - name: accountID
          in: path
          required: true
          schema:
            type: string
          description: >-
            The target account's Clustr ID (`tacc_…`), from [List Target

            Accounts](/api-reference/list-target-accounts). The `id` from
            earlier responses also works.
          example: tacc_f1tdkcgrbawqnq90nhs7n1eq01
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tier:
                  type: string
                  description: >-
                    Tier name, as your workspace spells it. See [List Account
                    Tiers](/api-reference/list-tiers).

                    Send `""` to clear the tier.
                  example: Tier 1
                tier_id:
                  type: string
                  description: >-
                    The tier's Clustr ID (`tier_…`), if you have it. The id from
                    earlier responses also works. Send

                    `""` to clear the tier.
            examples:
              byName:
                summary: By the name you use
                value:
                  tier: Tier 1
              clear:
                summary: Clear the tier
                value:
                  tier: ''
      responses:
        '200':
          description: The account, with its new tier
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      target_account:
                        $ref: '#/components/schemas/TargetAccount'
        '400':
          description: No tier field sent, or a tier name this workspace does not have
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing API key
        '404':
          description: Target account not found
        '409':
          description: |
            The account matched no company yet, so there is nothing to tier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    TargetAccount:
      type: object
      properties:
        clustr_target_account_id:
          type: string
          description: >-
            The target account's Clustr ID, for example
            `tacc_nwc2xe6jxb0jph5j9g7ef7vsx4`. Use it to refer

            to this target account.
          example: tacc_nwc2xe6jxb0jph5j9g7ef7vsx4
        clustr_tier_id:
          type: string
          description: >-
            The tier's Clustr ID, for example `tier_bk86g6d2aftqr9e7m804xywg9z`.
            Send it back to set exactly

            this tier.
          example: tier_bk86g6d2aftqr9e7m804xywg9z
        clustr_account_id:
          type: string
          description: >-
            The Clustr ID of the account this target account matched, for
            example

            `acc_kbmpcwq22xqwksy3zv3jd27px3`. It is left out when the target
            account matched no account,

            which you can fix by adding or correcting its LinkedIn URL.
          example: acc_kbmpcwq22xqwksy3zv3jd27px3
        id:
          type: string
          example: f7c7031d-350e-4b7b-a78e-bc54dba3281e
          description: >-
            Kept for integrations built before Clustr IDs. New integrations
            should use `clustr_target_account_id`.
        account_name:
          type: string
          example: Acme Corp
        account_linkedin_url:
          type: string
          example: https://www.linkedin.com/company/acme-corp
        tier:
          type: string
          description: |
            The tier this account is filed under, spelled the way your
            workspace spells it. Empty means untiered. See GET /tenant-tiers.
          example: Tier 1
        tier_id:
          type: string
          description: >-
            Kept for integrations built before Clustr IDs. New integrations
            should use `clustr_tier_id`.
        company_id:
          type: string
          description: >-
            Kept for integrations built before Clustr IDs. New integrations
            should use `clustr_account_id`.
        linkedin_lookup:
          type: string
          enum:
            - not_found
          description: >-
            `not_found` when the LinkedIn company page given for this account
            could not be found after two lookups: the URL may be wrong or
            outdated, so check it. The account is then matched by its name when
            exactly one company has that name. Omitted otherwise.
    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.