CustomerCompetitorUpsert

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/zoominfo/main/json-schema/zoominfo-customer-competitor-upsert-schema.json",
  "title": "CustomerCompetitorUpsert",
  "description": "Customer Competitor resource for upsert operations.",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/zoominfo-customer-competitors-api-openapi.yml#/components/schemas/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": "#/$defs/CustomerCompetitorAttributes"
            }
          ],
          "description": "The attributes defining the resource"
        },
        "meta": {
          "allOf": [
            {
              "$ref": "#/$defs/GtmConfigAuditFields"
            }
          ],
          "description": "Non-standard meta information about the resource"
        }
      },
      "x-discriminator-property": "type",
      "description": "The primary data of the document"
    }
  },
  "$defs": {
    "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."
    },
    "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": "#/$defs/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": "#/$defs/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."
    },
    "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.\nThese fields track the full lifecycle of a record including creation, modification,\narchival (temporary hiding), and soft deletion (permanent hiding for compliance).\nA record can be active, deleted only, or both."
    },
    "GtmConfigSourceType": {
      "type": "string",
      "enum": [
        "manual",
        "import",
        "system",
        "mcp"
      ],
      "description": "Source type indicating how a GTM configuration record was created or last modified.\nUsed across all customer-level entities for audit provenance tracking.\nWhen source is explicitly set in a request, the corresponding created_by/updated_by must also be provided.\nDefaults 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."
      }
    }
  }
}