---
title: "Upsert Ideal Customer Profile"
method: POST
path: "/copilot/v1/ideal-company-profile"
tags: ["Ideal Customer Profile"]
---

# Upsert Ideal Customer Profile

`POST /copilot/v1/ideal-company-profile`

## Request

- Base URL: `https://api.zoominfo.com/gtm`
- URL: `https://api.zoominfo.com/gtm/copilot/v1/ideal-company-profile`
- 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 an Ideal Customer Profile.
This endpoint performs an upsert operation:
If an `id` is included in the request body, the existing segment is updated. Only the attributes provided in the request are modified (partial update).

If an `id` is not included, a new segment is created.

When creating a new segment, `name` is the only required attribute. All other attributes are optional.
An Ideal Customer Profile defines the type of companies that best match the organization’s target market.
Segments typically describe firms using firmographic attributes such as industry, company size, revenue range, geography, and other qualification criteria.

Common use cases
- Define new ICP segments for GTM targeting
- Update firmographic filters used to identify target accounts
- Align company targeting with products or services and personas

## Request body

- IdealCompanySegmentUpsert: Ideal Customer Profile resource for upsert operations.
  - `data` object, required: The primary data of the document
    - `id` string: The unique identifier for the resource
    - `type` 'IdealCompanySegment', required: The type of the resource
    - `attributes` IdealCompanySegmentAttributes, required: Attributes that define an ideal company segment/Ideal Customer Profile. Ideal company segments/Ideal Customer Profile describe the types of companies a customer wants to target. This typically contains industry, company size, revenue range, geography, etc.
      - `name` string: Name of the Ideal Customer Profile (e.g., 'Enterprise SaaS', 'Mid-Market Financial Services'). Required when creating a new record. When provided (for create or update), must be between 1 and 1024 characters.
      - `description` string: Description of the profile. Typically includes industry, company size, revenue range, geography, etc. 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 profile criteria 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

- IdealCompanySegmentModel: API model for a single Ideal Customer Profile.
  - `data` IdealCompanySegment, required: Ideal Customer Profile resource.
    - `id` string, required: The unique identifier for the resource
    - `type` string, required: The type of the resource
    - `attributes` IdealCompanySegmentAttributes, required: Attributes that define an ideal company segment/Ideal Customer Profile. Ideal company segments/Ideal Customer Profile describe the types of companies a customer wants to target. This typically contains industry, company size, revenue range, geography, etc.
      - `name` string: Name of the Ideal Customer Profile (e.g., 'Enterprise SaaS', 'Mid-Market Financial Services'). Required when creating a new record. When provided (for create or update), must be between 1 and 1024 characters.
      - `description` string: Description of the profile. Typically includes industry, company size, revenue range, geography, etc. 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 profile criteria 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)