---
title: "Upsert Customer Competitor"
method: POST
path: "/copilot/v1/customer-competitors"
tags: ["Customer Competitors"]
---

# Upsert Customer Competitor

`POST /copilot/v1/customer-competitors`

## Request

- Base URL: `https://api.zoominfo.com/gtm`
- URL: `https://api.zoominfo.com/gtm/copilot/v1/customer-competitors`
- Auth: OAuth 2
  - Authorization code: `https://login.zoominfo.com`
  - Token URL: `https://okta-login.zoominfo.com/oauth2/default/v1/token` scopes: `api:gtm-config:manage`

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.

## Request body

- CustomerCompetitorUpsert: Customer Competitor resource for upsert operations.
  - `data` object, required: The primary data of the document
    - `id` string: The unique identifier for the resource
    - `type` 'CustomerCompetitor', required: The type of the resource
    - `attributes` CustomerCompetitorAttributes, required: Attributes that define a Customer Competitor — a company that competes with the customer in the market.
      - `name` string: 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` string: Detailed description of the competitor, including market position, strengths, and relevance to the customer's business. Maximum 10,000 characters.
      - `url` string, uri: URL of the competitor's website. Maximum 1024 characters.
      - `competitorProducts` string: Description of the products or services this competitor offers that overlap with the customer's portfolio. Maximum 10,000 characters.
      - `reasonsTheyWin` string: Analysis of why this competitor wins deals, covering key strengths, differentiators, and advantages in competitive situations. Maximum 10,000 characters.
      - `reasonsTheyLose` string: Analysis of why this competitor loses deals, covering weaknesses, gaps, and areas where the customer holds an advantage. Maximum 10,000 characters.
      - `customersWeWon` string: Accounts that the customer has won from this competitor. Useful for case-study development and competitive proof points. Maximum 10,000 characters.
      - `competitiveProducts` string: 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` 'manual' | 'import' | 'system' | 'mcp': 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.
      - `customFields` CustomFieldItem[]: 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.
        - `title` string, required: The display title of the custom field.
        - `description` string: An optional description of the field. Defaults to an empty string in the backend.
        - `value` string, required: The string value associated with this custom field.
    - `meta` GtmConfigAuditFields: 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.
      - `createdAt` string, date-time: ISO 8601 timestamp when the record was originally created. Auto-populated by backend.
      - `updatedAt` string, date-time: ISO 8601 timestamp of the most recent modification to the record. Auto-populated by backend.
      - `createdBy` string: User ID of the person who created the record. Extracted from the JWT token on creation.
      - `updatedBy` string: User ID of the person who last modified the record. Extracted from the JWT token on update.
      - `archivedAt` string, date-time: ISO 8601 timestamp when the record was archived. Archived records are identified by archivedAt and archivedBy
      - `archivedBy` string: User ID of the person who archived the record

## Response `200`

Success

- CustomerCompetitorModel: API model for a single Customer Competitor.
  - `data` CustomerCompetitor, required: Customer Competitor resource.
    - `id` string, required: The unique identifier for the resource
    - `type` string, required: The type of the resource
    - `attributes` CustomerCompetitorAttributes, required: Attributes that define a Customer Competitor — a company that competes with the customer in the market.
      - `name` string: 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` string: Detailed description of the competitor, including market position, strengths, and relevance to the customer's business. Maximum 10,000 characters.
      - `url` string, uri: URL of the competitor's website. Maximum 1024 characters.
      - `competitorProducts` string: Description of the products or services this competitor offers that overlap with the customer's portfolio. Maximum 10,000 characters.
      - `reasonsTheyWin` string: Analysis of why this competitor wins deals, covering key strengths, differentiators, and advantages in competitive situations. Maximum 10,000 characters.
      - `reasonsTheyLose` string: Analysis of why this competitor loses deals, covering weaknesses, gaps, and areas where the customer holds an advantage. Maximum 10,000 characters.
      - `customersWeWon` string: Accounts that the customer has won from this competitor. Useful for case-study development and competitive proof points. Maximum 10,000 characters.
      - `competitiveProducts` string: 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` 'manual' | 'import' | 'system' | 'mcp': 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.
      - `customFields` CustomFieldItem[]: 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.
        - `title` string, required: The display title of the custom field.
        - `description` string: An optional description of the field. Defaults to an empty string in the backend.
        - `value` string, required: The string value associated with this custom field.
    - `meta` GtmConfigAuditFields: 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.
      - `createdAt` string, date-time: ISO 8601 timestamp when the record was originally created. Auto-populated by backend.
      - `updatedAt` string, date-time: ISO 8601 timestamp of the most recent modification to the record. Auto-populated by backend.
      - `createdBy` string: User ID of the person who created the record. Extracted from the JWT token on creation.
      - `updatedBy` string: User ID of the person who last modified the record. Extracted from the JWT token on update.
      - `archivedAt` string, date-time: ISO 8601 timestamp when the record was archived. Archived records are identified by archivedAt and archivedBy
      - `archivedBy` string: User ID of the person who archived the record

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `422`: Unprocessable Content
- `429`: Too Many Requests

---

[API](https://skmtc.dev/zoominfo/apis/copilot-api-v1.md) - [All operations](https://skmtc.dev/zoominfo/apis/copilot-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/zoominfo/apis/copilot-api-v1/revisions/f737ab239c2a?raw)