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)