ZoomInfo Customer Settings API

openapi: 3.2.0
info:
  title: Copilot API V1 Customer Settings API
  version: '1.0'
  contact:
    name: ZoomInfo Customer Support
    email: help@zoominfo.com
  description: Copilot API for interacting with the Copilot related services.
servers:
- url: https://api.zoominfo.com/gtm
  description: Base URL for the Copilot API
security:
- OAuth2Auth: []
tags:
- name: Customer Settings
paths:
  /copilot/v1/customer-settings:
    get:
      operationId: CustomerSettingsInterface_getCustomerSettings
      summary: Get Customer Settings
      description: 'Retrieves the customer settings for the authenticated customer.


        Customer Settings represent the core company-level configuration.

        This includes foundational information such as the company name, description, elevator pitch, and strategic go-to-market priorities.

        This information provides the baseline context that AI agents use to generate recommendations, messaging, targeting insights,

        and account prioritization.


        This resource is a singleton per customer, meaning each customer can have only one Customer Settings record.

        If no configuration has been created yet, the endpoint will return **404 Not Found**.


        Use [Post Customer Settings](ref:customersettingsinterface_upsertcustomersettings) to create or update the settings.


        Common use cases

        - Retrieve the current company context powering GTM AI features

        - Verify whether company configuration has been initialized

        - Load existing company overview information for editing or synchronization'
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/CustomerSettingsModel'
        '401':
          description: Unauthorized
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel'
        '403':
          description: Forbidden
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel'
        '404':
          description: Not Found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel'
        '429':
          description: Too Many Requests
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel'
      tags:
      - Customer Settings
      security:
      - OAuth2Auth:
        - api:gtm-config:read
      x-api-roles:
      - fea:gsa
    post:
      operationId: CustomerSettingsInterface_upsertCustomerSettings
      summary: Upsert Customer Settings
      description: 'Creates or updates the Customer Settings for the authenticated customer.

        Customer Settings store the Company Overview configuration including the company name, description, elevator pitch,

        and strategic go-to-market priorities.


        This endpoint performs an upsert operation:

        If a Customer Settings record does not exist, it will be created.

        If a record already exists, only the fields included in the request will be updated.


        Each customer can have only one Customer Settings record.

        All attributes in the request body are optional, but at least one attribute must be provided. Requests with no attributes will

        return a **400 Bad Request**. Updates are applied as a partial update, meaning only the fields included in the request will be modified.

        All other fields remain unchanged.


        Common use cases

        - Initialize company configuration during setup

        - Update company overview information

        - Modify strategic priorities used by AI recommendations


        Use [Get Customer Settings](ref:customersettingsinterface_getcustomersettings) to retrieve the current settings

        before updating, or [Delete Customer Settings](ref:customersettingsinterface_deletecustomersettings) to remove them.'
      parameters: []
      responses:
        '201':
          description: Created
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/CustomerSettingsModel'
        '400':
          description: Bad Request
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel'
        '401':
          description: Unauthorized
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel'
        '403':
          description: Forbidden
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel'
        '429':
          description: Too Many Requests
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel'
      tags:
      - Customer Settings
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/CustomerSettingsModelCreate'
        description: Customer settings to create or fields to update.
      security:
      - OAuth2Auth:
        - api:gtm-config:manage
      x-additional-content-types:
      - application/json
      x-api-roles:
      - fea:gsa
    delete:
      operationId: CustomerSettingsInterface_deleteCustomerSettings
      summary: Delete Customer Settings
      description: 'Permanently deletes the Customer Settings record for the authenticated customer. Customer Settings store the customers

        Company Overview configuration.


        Deleting this record removes that configuration from the system.

        This resource is a singleton per customer, meaning each customer can have only one Customer Settings record.

        If no Customer Settings record exists, the endpoint returns **404 Not Found**.


        This is a hard delete operation. Once deleted, the record is removed from the backend and must be recreated using

        [Upsert Customer Settings](ref:customersettingsinterface_upsertcustomersettings) if needed.


        Common use cases

        - Remove an existing company overview configuration

        - Reset customer-level company settings before recreating them

        - Clean up configuration that is no longer valid


        Use [Get Customer Settings](ref:customersettingsinterface_getcustomersettings) to verify settings exist before deletion,

        or [Upsert Customer Settings](ref:customersettingsinterface_upsertcustomersettings) to recreate them if needed.'
      parameters: []
      responses:
        '204':
          description: Success
          content:
            application/vnd.api+json:
              schema: {}
        '401':
          description: Unauthorized
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel'
        '403':
          description: Forbidden
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel'
        '404':
          description: Not Found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel'
        '429':
          description: Too Many Requests
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel'
      tags:
      - Customer Settings
      security:
      - OAuth2Auth:
        - api:gtm-config:manage
      x-api-roles:
      - fea:gsa
components:
  schemas:
    CustomFieldItem:
      type: object
      required:
      - title
      - value
      properties:
        title:
          type: string
          description: The display title of the custom field.
        description:
          type: string
          description: An optional description of the field. Defaults to an empty string in the backend.
          default: ''
        value:
          type: string
          description: The string value associated with this custom field.
      description: Schema for a single custom field item.
    GtmConfigAuditFields:
      type: object
      properties:
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the record was originally created. Auto-populated by backend.
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the most recent modification to the record. Auto-populated by backend.
          readOnly: true
        createdBy:
          type: string
          description: User ID of the person who created the record. Extracted from the JWT token on creation.
          readOnly: true
        updatedBy:
          type: string
          description: User ID of the person who last modified the record. Extracted from the JWT token on update.
          readOnly: true
        archivedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the record was archived. Archived records are identified by archivedAt and archivedBy
          readOnly: true
        archivedBy:
          type: string
          description: User ID of the person who archived the record
          readOnly: true
      description: 'Common audit fields present on all customer-level GTM configuration entities.

        These fields track the full lifecycle of a record including creation, modification,

        archival (temporary hiding), and soft deletion (permanent hiding for compliance).

        A record can be active, deleted only, or both.'
    ZoomInfo.Core.Foundations.ErrorResponseModel:
      type: object
      required:
      - errors
      properties:
        detail:
          type: string
          description: A high-level detail of the error(s) that occurred during the request
        title:
          type: string
          description: A high-level summary of the error(s) detected
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorModel'
          description: The list of errors raised during the request
      description: The standard error response body model for the ZoomInfo API.
    CustomerSettingsAttributes:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 1024
          description: Editable display name for the customer organization. When provided (for create or update), must be between 1 and 1024 characters.
        elevatorPitch:
          type: string
          maxLength: 1024
          description: Brief elevator pitch or value proposition for the customer organization. Used by AI agents to understand the company's core offering. When provided (for create or update), must be less than 1024 characters.
        description:
          type: string
          maxLength: 10000
          description: Company description providing context about what the organization does, its market position, and its target audience. Maximum 10,000 characters.
        strategicPriorities:
          type: string
          maxLength: 10000
          description: Strategic priorities text describing the organization's key business objectives, growth targets, and focus areas. Used by AI agents to align GTM recommendations with business goals. Maximum 10,000 characters.
        source:
          allOf:
          - $ref: '#/components/schemas/GtmConfigSourceType'
          description: Source type indicating how this settings record was created or last modified. Defaults to `manual`. See `GtmConfigSourceType` for allowed values.
          readOnly: true
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldItem'
          description: Flexible key-value storage for customer-specific custom fields and metadata. The backend validates the schema and value types. This allows storing organization-specific data beyond the standard fields.
      description: Attributes defining customer-level settings and configuration
    GtmConfigSourceType:
      type: string
      enum:
      - manual
      - import
      - system
      - mcp
      description: 'Source type indicating how a GTM configuration record was created or last modified.

        Used across all customer-level entities for audit provenance tracking.

        When source is explicitly set in a request, the corresponding created_by/updated_by must also be provided.

        Defaults to ''manual'' when not specified.'
      x-enumDescriptions:
        MANUAL: Created or updated manually by a user through the GTM Studio UI.
        IMPORT: Imported from an external data source such as CRM or CSV upload.
        SYSTEM: Generated automatically by the platform (e.g., system enrichment or background jobs).
        MCP: Created or updated via the GTM Config MCP integration by an AI agent.
    CustomerSettingsCreate:
      type: object
      required:
      - type
      - attributes
      properties:
        type:
          type: string
          description: The type of the resource
          default: CustomerSettings
          pattern: CustomerSettings
        attributes:
          allOf:
          - $ref: '#/components/schemas/CustomerSettingsAttributes'
          description: The attributes defining the resource
      description: Customer Settings resource wrapping attributes in JSON:API format.
    ZoomInfo.Core.Foundations.ErrorModel:
      type: object
      required:
      - id
      - code
      - status
      properties:
        id:
          type: string
          description: The unique id used to identify this specific error instance
        code:
          type: string
          description: The error code describing the error category. A full list of error codes can be found in the documentation for each service
        detail:
          type: string
          description: Message containing the specific details about this occurrence of the error
        source:
          allOf:
          - $ref: '#/components/schemas/ZoomInfo.Core.Foundations.ErrorSourceModel'
          description: An optional object identifying which part of the request caused the error
        status:
          type: string
          description: The HTTP status code for the error
        title:
          type: string
          description: The error name that describes this type of error
      description: The object describing a specific error from the API
    ZoomInfo.Core.Foundations.ErrorSourceModel:
      type: object
      properties:
        cookie:
          type: string
          description: Identifies the cookie name that caused the issue
        header:
          type: string
          description: Identifies the header name that caused the error
        pointer:
          type: string
          description: An RFC 6901 compliant JSON pointer to the entity in the request body that caused the error
        parameter:
          type: string
          description: The name of the path or query parameter that caused the error
    CustomerSettingsModel:
      type: object
      required:
      - data
      properties:
        data:
          allOf:
          - $ref: '#/components/schemas/CustomerSettings'
          description: The primary data of the document
      description: JSON:API response containing the customer settings singleton.
    CustomerSettingsModelCreate:
      type: object
      required:
      - data
      properties:
        data:
          allOf:
          - $ref: '#/components/schemas/CustomerSettingsCreate'
          description: The primary data of the document
      description: JSON:API response containing the customer settings singleton.
    CustomerSettings:
      type: object
      required:
      - id
      - type
      - attributes
      properties:
        id:
          type: string
          description: The unique identifier for the resource
        type:
          type: string
          description: The type of the resource
          default: CustomerSettings
          pattern: CustomerSettings
        attributes:
          allOf:
          - $ref: '#/components/schemas/CustomerSettingsAttributes'
          description: The attributes defining the resource
        meta:
          allOf:
          - $ref: '#/components/schemas/GtmConfigAuditFields'
          description: Non-standard meta information about the resource
          readOnly: true
      description: Customer Settings resource wrapping attributes in JSON:API format.
  securitySchemes:
    OAuth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.zoominfo.com
          tokenUrl: https://okta-login.zoominfo.com/oauth2/default/v1/token
          scopes:
            api:account-summary:read: Read Copilot Account Summary Data
            api:insights:read: Read Insights Data
            api:recommendations:read: Read Copilot recommendation data
            api:gtm-config:read: Read GTM configuration data
            api:gtm-config:manage: Manage GTM configuration data (create, update, delete)