openapi: 3.2.0 info: title: Copilot API V1 Customer Competitors 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 Competitors paths: /copilot/v1/customer-competitors: get: operationId: CustomerCompetitorsInterface_listCustomerCompetitors summary: List Customer Competitors description: 'Returns the list of Customer Competitors configured for the authenticated customer. A Customer Competitor represents a company that competes with the customer''s products or services in the market. Competitor records capture structured competitive intelligence that helps sales and marketing teams understand the competitive landscape and position their products effectively. Competitor profiles may include information such as competing products, win/loss analysis, displacement history, and reasons why deals are won or lost against a particular competitor. A competitor may optionally be linked to a ZoomInfo company record to enable additional enrichment and firmographic insights. If you do not know the ID of the record you need, call [List Customer Competitors](ref:customercompetitorsinterface_listcustomercompetitors) to browse the full set. Common use cases - Retrieve all competitors configured for competitive analysis - Discover competitor IDs for use in other API operations - Load competitor data for downstream integrations or automation' parameters: [] responses: '200': description: Success content: application/vnd.api+json: schema: $ref: '#/components/schemas/CustomerCompetitorListResponse' '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 Competitors security: - OAuth2Auth: - api:gtm-config:read x-api-roles: - fea:gsa post: operationId: CustomerCompetitorsInterface_upsertCustomerCompetitor summary: Upsert Customer Competitor description: 'Creates or updates a Customer Competitor. This endpoint performs an upsert operation: If an `id` is included in the request body, the existing competitor record is updated. Only the attributes provided in the request are modified (partial update). If an `id` is not included, a new competitor record is created. When creating a new competitor, `name` is the only required attribute. All other attributes are optional. Competitor records store structured competitive intelligence including competing products, win/loss insights, displacement scenarios, and positioning details that help organizations understand how they perform against competitors in the market. Competitors can also be associated with Products and Services to capture which products directly compete with one another. Common use cases - Create competitor profiles for competitive intelligence - Update win/loss insights or competitive positioning - Link competitors to products or services in order to track product-level competition Use [List Customer Competitors](ref:customercompetitorsinterface_listcustomercompetitors) to find the `id` of a record you want to update or to check whether a competitor already exists.' parameters: [] responses: '200': description: Success content: application/vnd.api+json: schema: $ref: '#/components/schemas/CustomerCompetitorModel' '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' '422': description: Unprocessable Content 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 Competitors requestBody: required: true content: application/vnd.api+json: schema: $ref: '#/components/schemas/CustomerCompetitorUpsert' description: Customer competitor data to create, or fields to update. Include `id` to update an existing record; omit it to create a new one. security: - OAuth2Auth: - api:gtm-config:manage x-additional-content-types: - application/json x-api-roles: - fea:gsa /copilot/v1/customer-competitors/{competitorId}: get: operationId: CustomerCompetitorsInterface_getCustomerCompetitor summary: Get Customer Competitor by ID description: 'Retrieves a single Customer Competitor by its unique identifier. A Customer Competitor represents a company that competes with the customer''s products or services. Competitor records capture structured competitive intelligence such as competing products, win/loss analysis, displacement scenarios, and reasons why deals are won or lost against that competitor. A competitor may optionally be linked to a ZoomInfo company record for additional enrichment. If the specified competitorId does not exist, the endpoint returns **404 Not Found**. If you do not know the ID of the record you need, call [List Customer Competitors](ref:customercompetitorsinterface_listcustomercompetitors) to browse the full set. Common use cases - Retrieve detailed information about a specific competitor - Load competitor data before updating the record - Use competitor intelligence in integrations or automation workflows' parameters: - name: competitorId in: path required: true description: UUID of the competitor to retrieve. schema: type: string format: uuid responses: '200': description: Success content: application/vnd.api+json: schema: $ref: '#/components/schemas/CustomerCompetitorModel' '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' '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 Competitors security: - OAuth2Auth: - api:gtm-config:read x-api-roles: - fea:gsa delete: operationId: CustomerCompetitorsInterface_deleteCustomerCompetitor summary: Delete Customer Competitor description: 'Permanently deletes a Customer Competitor identified by `competitorId`. Deleting a competitor removes the associated competitive intelligence from the system. This is a hard delete operation and cannot be undone. If the specified `competitorId` does not exist, the endpoint returns **404 Not Found**. If you want to hide a competitor without permanently removing it, use the [Archive Customer Competitor](ref:customercompetitorsinterface_archivecustomercompetitor) endpoint instead. Common use cases - Remove outdated competitor profiles - Clean up duplicate competitor records - Reset competitor data before recreating it' parameters: - name: competitorId in: path required: true description: UUID of the competitor to permanently delete. schema: type: string format: uuid responses: '204': description: Success content: application/vnd.api+json: schema: {} '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' '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 Competitors security: - OAuth2Auth: - api:gtm-config:manage x-api-roles: - fea:gsa /copilot/v1/customer-competitors/{competitorId}/actions/archive: post: operationId: CustomerCompetitorsInterface_archiveCustomerCompetitor summary: Archive Customer Competitor description: 'Archives a Customer Competitor. Archiving hides the competitor from standard list responses while retaining the record for historical reference and audit purposes. Archived competitors remain stored in the system and continue to count toward customer limits. When a competitor is archived, the metadata fields `archivedAt` and `archivedBy` are set. This action is reversible using the [Unarchive Customer Competitor](ref:customercompetitorsinterface_unarchivecustomercompetitor). Common use cases - Temporarily remove inactive competitors - Preserve historical competitive intelligence - Simplify active competitor lists while retaining records' parameters: - name: competitorId in: path required: true description: UUID of the competitor to archive. schema: type: string format: uuid responses: '200': description: Success content: application/vnd.api+json: schema: $ref: '#/components/schemas/CustomerCompetitorModel' '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' '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 Competitors security: - OAuth2Auth: - api:gtm-config:manage x-api-roles: - fea:gsa /copilot/v1/customer-competitors/{competitorId}/actions/unarchive: post: operationId: CustomerCompetitorsInterface_unarchiveCustomerCompetitor summary: Unarchive Customer Competitor description: 'Restores a previously archived Customer Competitor. Unarchiving makes the competitor visible again in standard list responses and allows it to be used again in competitive intelligence workflows. When a competitor is restored, the metadata fields `archivedAt` and `archivedBy` are cleared. If the specified `competitorId` does not exist, the endpoint returns **404 Not Found**. Common use cases - Reactivate competitors that are relevant again - Restore archived competitive intelligence records - Re-enable competitors for GTM analysis' parameters: - name: competitorId in: path required: true description: UUID of the competitor to unarchive. schema: type: string format: uuid responses: '200': description: Success content: application/vnd.api+json: schema: $ref: '#/components/schemas/CustomerCompetitorModel' '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' '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 Competitors 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. CustomerCompetitor: 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: CustomerCompetitor pattern: CustomerCompetitor attributes: allOf: - $ref: '#/components/schemas/CustomerCompetitorAttributes' description: The attributes defining the resource meta: allOf: - $ref: '#/components/schemas/GtmConfigAuditFields' description: Non-standard meta information about the resource readOnly: true description: Customer Competitor resource. CustomerCompetitorAttributes: type: object properties: name: type: string minLength: 1 maxLength: 1024 description: Name of the competitor company. Required when creating a new record. When provided (for create or update), must be between 1 and 1024 characters. description: type: string maxLength: 10000 description: Detailed description of the competitor, including market position, strengths, and relevance to the customer's business. Maximum 10,000 characters. url: type: string format: uri description: URL of the competitor's website. Maximum 1024 characters. competitorProducts: type: string maxLength: 10000 description: Description of the products or services this competitor offers that overlap with the customer's portfolio. Maximum 10,000 characters. reasonsTheyWin: type: string maxLength: 10000 description: Analysis of why this competitor wins deals, covering key strengths, differentiators, and advantages in competitive situations. Maximum 10,000 characters. reasonsTheyLose: type: string maxLength: 10000 description: Analysis of why this competitor loses deals, covering weaknesses, gaps, and areas where the customer holds an advantage. Maximum 10,000 characters. customersWeWon: type: string maxLength: 10000 description: Accounts that the customer has won from this competitor. Useful for case-study development and competitive proof points. Maximum 10,000 characters. competitiveProducts: type: string maxLength: 10000 description: The customer's own products that directly compete with this competitor's products or services. Useful for competitive mapping and battle-card generation. Maximum 10,000 characters. source: allOf: - $ref: '#/components/schemas/GtmConfigSourceType' description: Source type indicating how this competitor record was created or last modified. Defaults to `manual`. See `GtmConfigSourceType` for allowed values. When set explicitly, the backend validates source consistency with the `created_by` and `updated_by` fields. readOnly: true customFields: type: array items: $ref: '#/components/schemas/CustomFieldItem' description: Flexible key-value store for customer-specific custom fields and extended metadata. The backend validates schema and value types. Use this to capture additional competitor intelligence beyond the standard fields. description: Attributes that define a Customer Competitor — a company that competes with the customer in the market. CustomerCompetitorModel: type: object required: - data properties: data: allOf: - $ref: '#/components/schemas/CustomerCompetitor' description: The primary data of the document description: API model for a single Customer Competitor. 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. 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 CustomerCompetitorUpsert: type: object required: - data properties: data: type: object required: - type - attributes properties: id: type: string description: The unique identifier for the resource type: type: string enum: - CustomerCompetitor description: The type of the resource attributes: allOf: - $ref: '#/components/schemas/CustomerCompetitorAttributes' description: The attributes defining the resource meta: allOf: - $ref: '#/components/schemas/GtmConfigAuditFields' description: Non-standard meta information about the resource x-discriminator-property: type description: The primary data of the document description: Customer Competitor resource for upsert operations. CustomerCompetitorListResponse: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/CustomerCompetitor' description: The primary data of the document description: API model for a list of Customer Competitors. 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)