> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getsales.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Read CRM fields, pipelines or lists

> The CRM structure behind a Send to CRM column, read live off the portal: kind fields (a person's or a company's writable fields with their options; folk reads them per group), pipelines (gohighlevel), lists (attio lists, folk groups), owners (reserved). Unbilled, no provider_calls row, no health write. 422 metadata_kind_not_supported for a kind the CRM lacks, 422 connection_disabled when off or failed; a refused read answers ok false with error_code and error_message.

Contract:
- MCP tool `read_provider_connection_crm_metadata`, registry package `mcp.integrations/provider_connections`, mount `workspace.integrations`.
- Operation `action`, response envelope `action`.
- Flags: read only.



## OpenAPI

````yaml /api-reference/integrations/openapi.yaml post /api/provider-connections/{sid}/crm-metadata
openapi: 3.0.3
info:
  title: 'GetSales public contract: gs.service.integrations'
  description: >-
    The integrations service: the integration platform (the team's credentials
    for its own APIs and its CRM grants, the HTTP tools it defines over them,
    the execution log and the priced catalog of every outbound provider call)
    and the event plane (the platform-wide webhook subscriptions and the
    delivery state of each event).


    GENERATED. This document is projected from the Zod MCP tool registry in
    `product/mcp/gs.mcp` (one tool per public endpoint, 1:1). Do not edit it by
    hand; edit the tool definition and regenerate with `pnpm openapi:public`.


    Surface: the public `/api` contract of `gs.service.integrations`, 26
    operations. This is the only OpenAPI document the platform publishes.
    Internal (`/internal`) and health endpoints are deliberately absent: they
    are not part of any contract, they can change without notice, and the
    service source is their only description.


    Conventions:

    - Auth is a bearer JWT, optionally narrowed by the `Team-SID` header.

    - Every success body is an MCP envelope: `success: true` plus one typed
    `operation` shape (`search`, `get`, `create`, `update`, `delete`, `metrics`,
    `group_by`, `action`), and a `meta` block with `trace_id` for support.

    - Every failure is the same `McpError` envelope with a code from a fixed
    16-code taxonomy, so a client maps errors once.

    - Lists page with `page_size` (0 to 500, default 50) plus an opaque forward
    `cursor`; `page_size: 0` returns counts only.

    - On `GET` and `DELETE`, object-valued query parameters (`filter`, `sort`)
    travel as JSON text and array-valued ones repeat as `name[]=value`.

    - The MCP-only `_meta` field (usage analytics) never reaches the backend and
    is not part of this contract.
  version: '1.0'
  contact:
    name: GetSales
    url: https://getsales.io
    email: support@getsales.io
  license:
    name: Proprietary
    url: https://getsales.io/terms
servers:
  - url: https://api2.getsales.io/integrations/v1
    description: Production
security:
  - BearerJwt: []
    TeamSid: []
tags:
  - name: custom_tools
    description: >-
      Registry package `mcp.integrations/custom_tools`, served on MCP mount
      `workspace.integrations`.
  - name: provider_calls
    description: >-
      Registry package `mcp.integrations/provider_calls`, served on MCP mount
      `workspace.integrations`.
  - name: provider_connections
    description: >-
      Registry package `mcp.integrations/provider_connections`, served on MCP
      mount `workspace.integrations`.
  - name: webhook_logs
    description: >-
      Registry package `mcp.integrations/webhook_logs`, served on MCP mount
      `workspace.webhooks`.
  - name: webhooks
    description: >-
      Registry package `mcp.integrations/webhooks`, served on MCP mount
      `workspace.webhooks`.
paths:
  /api/provider-connections/{sid}/crm-metadata:
    post:
      tags:
        - provider_connections
      summary: Read CRM fields, pipelines or lists
      description: >-
        The CRM structure behind a Send to CRM column, read live off the portal:
        kind fields (a person's or a company's writable fields with their
        options; folk reads them per group), pipelines (gohighlevel), lists
        (attio lists, folk groups), owners (reserved). Unbilled, no
        provider_calls row, no health write. 422 metadata_kind_not_supported for
        a kind the CRM lacks, 422 connection_disabled when off or failed; a
        refused read answers ok false with error_code and error_message.


        Contract:

        - MCP tool `read_provider_connection_crm_metadata`, registry package
        `mcp.integrations/provider_connections`, mount `workspace.integrations`.

        - Operation `action`, response envelope `action`.

        - Flags: read only.
      operationId: read_provider_connection_crm_metadata
      parameters:
        - name: sid
          in: path
          required: true
          description: Provider connection sid (in_cn_...).
          schema:
            type: string
            minLength: 18
            maxLength: 18
            pattern: ^in_cn_
            description: Provider connection sid (in_cn_...).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadProviderConnectionCrmMetadataRequest'
      responses:
        '200':
          description: '`action` success envelope.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadProviderConnectionCrmMetadataResponse'
        4XX:
          $ref: '#/components/responses/McpClientError'
        5XX:
          $ref: '#/components/responses/McpServerError'
components:
  schemas:
    ReadProviderConnectionCrmMetadataRequest:
      type: object
      description: Request body of `read_provider_connection_crm_metadata`.
      properties:
        kind:
          type: string
          enum:
            - fields
            - pipelines
            - owners
            - lists
          description: >-
            What to read: fields, pipelines, lists (attio lists, folk groups) or
            owners (reserved).
        object:
          type: string
          enum:
            - person
            - company
          description: >-
            With kind fields: whose fields, a person's or a company's (required
            then).
        group:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            With kind fields on folk: the group whose custom fields join the
            standard ones (a folk group id, grp_...); the other CRMs ignore it.
      required:
        - kind
    ReadProviderConnectionCrmMetadataResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        operation:
          type: string
          enum:
            - action
        action:
          type: string
          description: kebab-case verb; matches the route segment.
        item:
          type: object
          nullable: true
          properties:
            sid:
              type: string
              description: Connection sid (in_cn_...).
            team_sid:
              type: string
              description: The owning workspace (ts_tm_...).
            name:
              type: string
              description: Display name, unique within the team among live rows.
            provider:
              type: string
              enum:
                - openai
                - anthropic
                - google
                - deepseek
                - xai
                - voyage
                - cohere
                - hunter
                - findymail
                - anymailfinder
                - emaillistverify
                - custom
                - hubspot
                - gohighlevel
                - pipedrive
                - salesforce
                - attio
                - folk
                - serper
              description: >-
                custom (the team's own API), an OAuth CRM grant (hubspot,
                gohighlevel, pipedrive, salesforce) or a pasted API key (attio:
                a workspace key; folk: a member's key); immutable.
            auth_type:
              type: string
              enum:
                - api_key
                - bearer
                - basic
                - header
                - query
                - oauth
              description: The shape of the stored secret; oauth on a HubSpot grant.
            external_account_id:
              type: string
              nullable: true
              description: >-
                The provider-side account this credential belongs to (the
                HubSpot portal id, the GoHighLevel location id, the Pipedrive
                company id, the Salesforce org id, the Attio workspace id, the
                folk member id the key acts as): the reconnect key; null on
                custom key auth.
            status:
              type: string
              enum:
                - 'on'
                - 'off'
                - failed
              description: >-
                on; off (paused by hand); failed (auto-disabled after five auth
                failures in a row, revived by update or a reconnect).
            settings:
              type: object
              nullable: true
              properties:
                activity:
                  type: object
                  properties:
                    messages:
                      type: boolean
                      description: >-
                        Log sent and received LinkedIn and email messages onto
                        the CRM person's timeline.
                    handoff:
                      type: boolean
                      description: Log an AI SDR hand-off as a note on the CRM person.
              description: The portal's activity-sync policy; null = off (the default).
            consecutive_failed_attempts:
              type: integer
              description: >-
                Auth-classified failures in a row; any non-cache success or a
                rotation resets it.
            last_failure_at:
              type: string
              nullable: true
              description: ISO 8601 UTC of the last auth failure.
            created_by:
              type: object
              properties:
                actor_type:
                  type: string
                  enum:
                    - user
                    - support
                    - api_key
                    - system
                    - agent
                actor_sid:
                  type: string
                  nullable: true
                team_sid:
                  type: string
                actor_name:
                  type: string
                  nullable: true
                  description: >-
                    The OAuth client that acted ("Claude", "n8n"); null for a
                    user, an API key or a system job.
                oauth_client_sid:
                  type: string
                  nullable: true
                  description: The acting OAuth client (id_oc_*); null off the OAuth path.
                reason:
                  type: string
                  nullable: true
                  description: >-
                    Why a system actor wrote the row (snapshot_capture_job,
                    ...); null otherwise.
                permissions:
                  type: object
                  additionalProperties: {}
                  description: >-
                    Internal audit context: the grant set the actor held at
                    write time. Not a contract.
                cluster_id:
                  type: integer
                  nullable: true
                  description: 'Internal audit context: the cluster that served the write.'
                trace_id:
                  type: string
                  nullable: true
                  description: >-
                    Internal audit context: the trace id of the request that
                    wrote the row.
              required:
                - actor_type
                - actor_sid
                - team_sid
                - permissions
              description: Who stored it.
            deleted_by:
              type: object
              nullable: true
              properties:
                actor_type:
                  type: string
                  enum:
                    - user
                    - support
                    - api_key
                    - system
                    - agent
                actor_sid:
                  type: string
                  nullable: true
                team_sid:
                  type: string
                actor_name:
                  type: string
                  nullable: true
                  description: >-
                    The OAuth client that acted ("Claude", "n8n"); null for a
                    user, an API key or a system job.
                oauth_client_sid:
                  type: string
                  nullable: true
                  description: The acting OAuth client (id_oc_*); null off the OAuth path.
                reason:
                  type: string
                  nullable: true
                  description: >-
                    Why a system actor wrote the row (snapshot_capture_job,
                    ...); null otherwise.
                permissions:
                  type: object
                  additionalProperties: {}
                  description: >-
                    Internal audit context: the grant set the actor held at
                    write time. Not a contract.
                cluster_id:
                  type: integer
                  nullable: true
                  description: 'Internal audit context: the cluster that served the write.'
                trace_id:
                  type: string
                  nullable: true
                  description: >-
                    Internal audit context: the trace id of the request that
                    wrote the row.
              required:
                - actor_type
                - actor_sid
                - team_sid
                - permissions
              description: Who deleted it; null while live.
            created_at:
              type: string
              description: ISO 8601 UTC.
            updated_at:
              type: string
              description: ISO 8601 UTC.
            deleted_at:
              type: string
              nullable: true
              description: ISO 8601 UTC; the secret is scrubbed with it.
          required:
            - sid
            - team_sid
            - name
            - provider
            - auth_type
            - external_account_id
            - status
            - settings
            - consecutive_failed_attempts
            - last_failure_at
            - created_by
            - deleted_by
            - created_at
            - updated_at
            - deleted_at
        result:
          type: object
          properties:
            ok:
              type: boolean
              description: >-
                false = the portal refused the read; error_code and
                error_message say why.
            kind:
              type: string
              enum:
                - fields
                - pipelines
                - owners
                - lists
            items:
              type: array
              items:
                type: object
                additionalProperties: {}
              description: >-
                kind fields: {name, label, type, field_type, group, read_only,
                options?, required?} per field; pipelines and lists: the CRM
                arm's own shapes (a pipeline with its stages; a list or group
                with id and name).
            error_code:
              type: string
              nullable: true
            error_message:
              type: string
              nullable: true
          required:
            - ok
            - kind
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                The team this call ran in (the token team, or the team_sid
                override). Null when unauthenticated; absent from pre-2026-08-20
                backends.
            actor_type:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
      required:
        - success
        - operation
        - action
        - item
        - result
        - meta
    McpError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_failed
                - nothing_to_update
                - not_found
                - relation_not_found
                - invalid_transition
                - limit_exceeded
                - payment_required
                - duplicate_rejected
                - conflict
                - delete_blocked
                - unauthorized
                - forbidden
                - rate_limited
                - internal_error
                - service_unavailable
                - not_implemented
            message:
              type: string
            recoverable:
              type: boolean
            suggestion:
              type: string
            field_errors:
              type: object
              additionalProperties:
                type: array
                items:
                  type: object
                  properties:
                    rule:
                      type: string
                    message:
                      type: string
                  required:
                    - rule
                    - message
            blockers:
              type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: >-
                      Machine-readable blocker type (active_flow, pending_tasks,
                      …).
                  severity:
                    type: string
                    enum:
                      - hard
                      - soft
                    description: >-
                      hard = external action required; soft = acknowledge is
                      enough.
                  description:
                    type: string
                  entity_sid:
                    type: string
                    nullable: true
                  count:
                    type: integer
                  resolution:
                    type: string
                    description: 'Hard: tool name to call. Soft: code for acknowledge[].'
                  resolution_hint:
                    type: string
                required:
                  - type
                  - severity
                  - description
                  - entity_sid
                  - resolution
                  - resolution_hint
            context:
              type: object
              additionalProperties: {}
          required:
            - code
            - message
            - recoverable
        meta:
          type: object
          properties:
            trace_id:
              type: string
              description: UUID v7; same 128-bit value as the X-Trace-Id header.
            span_id:
              type: string
              pattern: ^[0-9a-f]{16}$
              description: 16 hex chars, root span of this request.
            timestamp:
              type: string
              description: ISO 8601 UTC (Y-m-dTH:i:sZ), response time.
            duration_ms:
              type: integer
              minimum: 0
              description: Server-side wall clock.
            team_sid:
              type: string
              nullable: true
              description: >-
                The team this call ran in (the token team, or the team_sid
                override). Null when unauthenticated; absent from pre-2026-08-20
                backends.
            actor_type:
              type: string
              nullable: true
              description: >-
                user | agent | api_key | system. Null when unauthenticated;
                absent from pre-2026-08-20 backends.
          required:
            - trace_id
            - span_id
            - timestamp
            - duration_ms
      required:
        - success
        - error
  responses:
    McpClientError:
      description: >-
        MCP error envelope. `error.code` is one of validation_failed,
        nothing_to_update, not_found, relation_not_found, invalid_transition,
        limit_exceeded, payment_required, duplicate_rejected, conflict,
        delete_blocked, unauthorized, forbidden, rate_limited, not_implemented.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
    McpServerError:
      description: >-
        MCP error envelope with `error.code` internal_error or
        service_unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/McpError'
  securitySchemes:
    BearerJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Access token issued by gs.service.id. Its `access_identity` claim
        carries `team_sid`, `actor_sid` and `actor_type`, and that team scope is
        authoritative.
    TeamSid:
      type: apiKey
      in: header
      name: Team-SID
      description: >-
        Team scope for tokens that do not carry one. Ignored when the token
        already names a team.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.