openapi: 3.2.0 info: title: Copilot API V1 Customer Buyer Persona 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 Buyer Persona paths: /copilot/v1/customer-buyer-personas: get: operationId: CustomerBuyerPersonaInterface_listCustomerBuyerPersonas summary: List Customer Buyer Personas description: 'Returns the list of Customer Buyer Personas configured for the authenticated customer. A Buyer Persona represents a profile of a key decision-maker or influencer that a company''s sales and marketing teams target. Personas capture attributes such as the buyer''s role, objectives, priorities, and the motivations that influence purchasing decisions. Personas help organizations align their go-to-market strategy by defining who the ideal buyers are, what problems they care about, and how they should be engaged. Buyer Personas can be connected to products or services with the people most likely to purchase them. If you do not know the ID of the record you need, call [List Customer Buyer Personas](ref:customerbuyerpersonainterface_listcustomerbuyerpersonas) to browse the full set. Common use cases - Retrieve all configured buyer personas - Discover persona IDs for use in other API operations - Load persona data for downstream integrations or automation' parameters: [] responses: '200': description: Success content: application/vnd.api+json: schema: $ref: '#/components/schemas/CustomerBuyerPersonaListResponse' '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 Buyer Persona security: - OAuth2Auth: - api:gtm-config:read x-api-roles: - fea:gsa post: operationId: CustomerBuyerPersonaInterface_upsertCustomerBuyerPersona summary: Upsert Customer Buyer Persona description: 'Creates or updates a Customer Buyer Persona. This endpoint performs an upsert operation: If an `id` is included in the request body, the existing persona is updated. Only the fields provided in the request are modified (partial update). If an `id` is not included, a new persona is created. When creating a new persona, `name` is the only required attribute. All other attributes are optional. A Buyer Persona represents a type of buyer that the customer''s sales and marketing teams target. Each persona captures key details about the buyer''s responsibilities, motivations, and priorities, helping teams tailor messaging and engagement strategies. Buyer Personas can be associated with specific products or services with relevant buyers. Common use cases - Create new buyer personas for targeting and messaging - Update persona characteristics or engagement insights - Link personas to products or services for GTM alignment' parameters: [] responses: '200': description: Success content: application/vnd.api+json: schema: $ref: '#/components/schemas/CustomerBuyerPersonaModel' '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 Buyer Persona requestBody: required: true content: application/vnd.api+json: schema: $ref: '#/components/schemas/CustomerBuyerPersonaUpsert' description: Buyer persona 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-buyer-personas/{buyerPersonaId}: get: operationId: CustomerBuyerPersonaInterface_getCustomerBuyerPersona summary: Get Customer Buyer Persona description: 'Retrieves a single Customer Buyer Persona by its unique identifier. A Buyer Persona represents a profile of a decision-maker or stakeholder that the customer''s sales and marketing teams target. Each persona captures insights into who the ideal buyers are, what motivates them, and how to effectively engage them during the sales process. If the specified buyerPersonaId does not exist, the endpoint returns **404 Not Found**. If you do not know the ID of the record you need, call [List Customer Buyer Personas](ref:customerbuyerpersonainterface_listcustomerbuyerpersonas) to browse the full set. This endpoint is typically used to retrieve the full configuration of a specific persona before updating or referencing it in downstream workflows. Common use cases - Retrieve detailed information about a specific persona - Load persona data before updating the record - Use persona context in integrations or automation workflows' parameters: - name: buyerPersonaId in: path required: true description: UUID of the buyer persona to retrieve. schema: type: string format: uuid responses: '200': description: Success content: application/vnd.api+json: schema: $ref: '#/components/schemas/CustomerBuyerPersonaModel' '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 Buyer Persona security: - OAuth2Auth: - api:gtm-config:read x-api-roles: - fea:gsa delete: operationId: CustomerBuyerPersonaInterface_deleteCustomerBuyerPersona summary: Delete Customer Buyer Persona description: 'Permanently deletes a Customer Buyer Persona identified by `buyerPersonaId`. Deleting a persona removes the associated buyer profile from the system and from any go-to-market configuration that references it. This is a hard delete operation. Once deleted, the persona cannot be recovered. If the specified buyerPersonaId does not exist, the endpoint returns **404 Not Found**. If you want to hide a persona without permanently removing it, use the [Archive Customer Buyer Persona](ref:customerbuyerpersonainterface_archivecustomerbuyerpersona) endpoint instead. Common use cases - Remove outdated or incorrect personas - Clean up duplicate persona records - Reset persona configuration before recreating it' parameters: - name: buyerPersonaId in: path required: true description: UUID of the buyer persona 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 Buyer Persona security: - OAuth2Auth: - api:gtm-config:manage x-api-roles: - fea:gsa /copilot/v1/customer-buyer-personas/{buyerPersonaId}/actions/archive: post: operationId: CustomerBuyerPersonaInterface_archiveCustomerBuyerPersona summary: Archive Buyer Persona description: "Archives a Customer Buyer Persona.\nArchiving hides the persona from standard list responses while retaining the record for historical reference, audit compliance, and potential restoration. \nArchived personas remain stored in the system and continue to count toward customer limits.\nWhen a persona is archived, the system sets the metadata fields `archivedAt` and `archivedBy`.\nThis action is reversible. The persona can be restored using the [Unarchive Customer Buyer Persona](ref:customerbuyerpersonainterface_unarchivecustomerbuyerpersona) endpoint.\n\nCommon use cases\n- Temporarily retire a persona that is no longer actively targeted\n- Maintain historical records without permanently deleting them\n- Clean up active persona lists while preserving data" parameters: - name: buyerPersonaId in: path required: true description: UUID of the buyer persona to archive. schema: type: string format: uuid responses: '200': description: Success content: application/vnd.api+json: schema: $ref: '#/components/schemas/CustomerBuyerPersonaModel' '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 Buyer Persona security: - OAuth2Auth: - api:gtm-config:manage x-api-roles: - fea:gsa /copilot/v1/customer-buyer-personas/{buyerPersonaId}/actions/unarchive: post: operationId: CustomerBuyerPersonaInterface_unarchiveCustomerBuyerPersona summary: Unarchive Buyer Persona description: 'Restores a previously archived Customer Buyer Persona. Unarchiving makes the persona visible again in standard list responses and allows it to be used again in GTM configuration and workflows. When a persona is restored, the metadata fields `archivedAt` and `archivedBy` are cleared. If the specified buyerPersonaId does not exist, the endpoint returns **404 Not Found**. Common use cases - Reactivate a previously archived persona - Restore a persona that is relevant again for targeting or messaging - Re-enable personas used in go-to-market strategies' parameters: - name: buyerPersonaId in: path required: true description: UUID of the buyer persona to unarchive. schema: type: string format: uuid responses: '200': description: Success content: application/vnd.api+json: schema: $ref: '#/components/schemas/CustomerBuyerPersonaModel' '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 Buyer Persona 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. CustomerBuyerPersonaListResponse: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/CustomerBuyerPersona' description: The primary data of the document description: API model for a list of customer buyer personas. CustomerBuyerPersonaAttributes: type: object properties: name: type: string minLength: 1 maxLength: 1024 description: Name of the buyer persona. 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 this buyer persona, including their role, responsibilities, and relevance to the sales process. Maximum 10,000 characters. personalObjectives: type: string maxLength: 10000 description: Personal objectives for this persona such as career goals, KPIs, and success metrics that drive their purchasing decisions. Maximum 10,000 characters. whatDoesThisPersonaCareAbout: type: string maxLength: 10000 description: Messaging angle explaining what this persona cares about in the customer's offering. Maximum 10,000 characters. titlesFunctionsSeniority: type: string maxLength: 10000 description: Typical job titles, functional areas, and seniority levels associated with this persona. Maximum 10,000 characters. relevantOfferings: type: string maxLength: 10000 description: Relevant offerings from the customer's portfolio that this persona would be interested in. Maximum 10,000 characters. source: allOf: - $ref: '#/components/schemas/GtmConfigSourceType' description: Source type indicating how this persona 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 persona attributes beyond the standard fields. description: 'Attributes that define a customer buyer persona — a profile representing a type of buyer that the customer''s sales team targets. Buyer personas capture who the ideal buyers are, what motivates them, and how to engage them effectively.' 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.' CustomerBuyerPersona: 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: CustomerBuyerPersona pattern: CustomerBuyerPersona attributes: allOf: - $ref: '#/components/schemas/CustomerBuyerPersonaAttributes' description: The attributes defining the resource meta: allOf: - $ref: '#/components/schemas/GtmConfigAuditFields' description: Non-standard meta information about the resource readOnly: true description: Customer Buyer Persona resource. 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. 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.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 CustomerBuyerPersonaUpsert: 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: - CustomerBuyerPersona description: The type of the resource attributes: allOf: - $ref: '#/components/schemas/CustomerBuyerPersonaAttributes' 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 Buyer Persona resource for upsert operations. CustomerBuyerPersonaModel: type: object required: - data properties: data: allOf: - $ref: '#/components/schemas/CustomerBuyerPersona' description: The primary data of the document description: API model for a single customer buyer persona. 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 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)