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

# Get Tag Field CRM Mappings

> Which CRM property each tag field syncs with

Reads which property of one connected CRM each tag field (the tag-groups endpoints) syncs with. Change them with
[Set Tag Field CRM Mappings](https://docs.clustr-ai.com/api-reference/set-tag-group-crm-mappings.md).

Each mapping has:

| Field | Description |
| - | - |
| `clustr_tag_group_id` | The tag field's [Clustr ID](https://docs.clustr-ai.com/clustr-ids.md), from [List Tag Groups](https://docs.clustr-ai.com/api-reference/list-tag-groups.md) |
| `group_id` | The same tag field by its earlier id, kept for integrations built before Clustr IDs |
| `object_type` | The CRM record the property is on: `companies`, `contacts` or `deals` |
| `property` | The CRM property's API name (for `checkbox_per_tag`, the prefix) |
| `shape` | `multiselect` (default), or `checkbox_per_tag` on Salesforce: one checkbox per tag |
| `direction` | `clustr_owns` (default), `fill_if_empty`, `crm_owns` or `off` (paused) |
| `options` | Tag id to the CRM's value for it. Only the tags listed here are pushed |

## Errors

| Status | Code | When |
| - | - | - |
| 400 | | `provider` is missing or not one of the three |
| 404 | `CRM_NOT_CONNECTED` | That CRM is not connected for this workspace |

```bash cURL theme={null}
curl "https://api.clustr-ai.com/api/public/crm/tag-group-mappings?provider=hubspot" \
  -H "Authorization: Bearer YOUR_API_KEY"
```


## OpenAPI

````yaml GET /crm/tag-group-mappings
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:
  /crm/tag-group-mappings:
    parameters:
      - name: provider
        in: query
        required: true
        description: >-
          The CRM to read or change: `hubspot`, `salesforce` or `attio`. That
          CRM must be connected to your workspace.
        schema:
          type: string
          enum:
            - hubspot
            - salesforce
            - attio
        example: hubspot
    get:
      tags:
        - Owners
      summary: Get Tag Field CRM Mappings
      description: >
        Returns which property of one connected CRM each record type's tag field
        syncs with (one multi-select property). Each

        mapping names the tag field, the CRM record and property it writes to,
        the property's

        shape, which side owns the values, and the CRM value for each tag.
        Change the mappings

        with Set Tag Field CRM Mappings.
      operationId: getTagFieldCrmMappings
      responses:
        '200':
          description: The tag field mappings for this CRM
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/TagFieldCrmMappings'
              example:
                success: true
                data:
                  provider: hubspot
                  mappings:
                    - clustr_tag_group_id: tgrp_w2s12cdkx8fk3enbk53hmg1pzd
                      group_id: 5b0c2e7a-3f41-4d8e-9a6b-1c2d3e4f5a6b
                      object_type: companies
                      property: clustr_audience
                      shape: multiselect
                      direction: clustr_owns
                      options:
                        9f8e7d6c-5b4a-4321-8fed-cba987654321: Competitor customer
                        1a2b3c4d-5e6f-4789-8abc-def012345678: Strategic account
        '400':
          description: '`provider` is missing or is not hubspot, salesforce or attio'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing API key
        '404':
          description: >-
            That CRM is not connected to your workspace (code
            `CRM_NOT_CONNECTED`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    TagFieldCrmMappings:
      type: object
      required:
        - provider
        - mappings
      properties:
        provider:
          type: string
          enum:
            - hubspot
            - salesforce
            - attio
          example: hubspot
        mappings:
          type: array
          description: >-
            Every tag field mapping for this CRM, an empty array when there are
            none.
          items:
            $ref: '#/components/schemas/TagFieldCrmMapping'
    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
    TagFieldCrmMapping:
      type: object
      description: Which CRM multi-select property one record type's tag field syncs with.
      required:
        - group_id
        - object_type
        - property
      properties:
        group_id:
          type: string
          format: uuid
          description: >-
            The record type's tag field, from List Tag Groups. When you send a
            mapping, you can also give the tag field's Clustr ID (`tgrp_…`).
          example: 5b0c2e7a-3f41-4d8e-9a6b-1c2d3e4f5a6b
        object_type:
          type: string
          enum:
            - companies
            - contacts
            - deals
          description: The CRM record the property is on.
          example: companies
        property:
          type: string
          description: >-
            The CRM property's API name. With `checkbox_per_tag`, a prefix for
            the tag checkboxes, whose own field names are the values in
            `options`.
          example: clustr_audience
        shape:
          type: string
          enum:
            - multiselect
            - checkbox_per_tag
          default: multiselect
          description: >-
            `multiselect`: one property holds every tag as an option.
            `checkbox_per_tag` (Salesforce): one checkbox field per tag, which
            Salesforce reports can group by.
          example: multiselect
        direction:
          type: string
          enum:
            - clustr_owns
            - fill_if_empty
            - crm_owns
            - 'off'
          default: clustr_owns
          description: >-
            Which side owns the values. `clustr_owns`: every sync writes
            Clustr's tags to the property. `fill_if_empty`: Clustr fills the
            property on records where it is empty and keeps every value already
            there. `crm_owns`: the property stays under your CRM's control.
            `off`: the mapping and its tag pairings are kept and paused.
          example: clustr_owns
        options:
          type: object
          additionalProperties:
            type: string
          description: >-
            Maps each tag id to the CRM's value for that tag (with
            `checkbox_per_tag`, the checkbox's field API name). Only the tags
            listed here are written to your CRM; a tag left out stays in Clustr
            only.
          example:
            9f8e7d6c-5b4a-4321-8fed-cba987654321: Competitor customer
  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.