openapi: 3.2.0 info: title: Copilot API V1 Recommendations 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: Recommendations paths: /copilot/v1/companies/lookalikes: get: operationId: CompanyLookalikesInterface_companyLookalikes summary: Find Similar Companies description: 'Company Lookalikes can be used to retrieve a ranked list of companies that are similar to a given reference company. The similar companies are identified using a machine learning model that analyzes industry, revenue range, employee count, and other firmographic signals. These lookalike companies can be used to power prospecting, territory planning, or market expansion workflows where one wants to quickly find companies that "look like" a successful or high-priority account. **IMPORTANT: Either `filter[companyId]` or `filter[companyName]` MUST be provided. Omitting both will result in a 422 error.** To find Company Lookalikes, select the `companyId`, which identifies the company you want to use as the basis for finding lookalikes. If you are not able to provide the `companyId`, you can provide only the `companyName` instead, the service will attempt to resolve the best matching company and then return lookalike companies based on that company. The more precise the company name is (for example, use the full company name with correct spelling and full legal name), the more likely the service is able to track down the company ID and use it to find lookalikes. Optionally, you can narrow the results using the following boolean filters. When set to true, each filter restricts lookalikes to companies that share the corresponding attribute with the reference company: - `filter[sameRevenueRange]`: same revenue range - `filter[sameCountry]`: same country - `filter[sameIndustry]`: same industry - `filter[sameEmployeeRange]`: same employee count range Behind the scenes, the model uses a semantic vector representation of the reference company''s data to efficiently find similar companies in the ZoomInfo database. The endpoint returns up to 100 lookalike companies, ordered from the most similar company to the least similar company (descending order by similarity score `attributes.score`). To control the number of results returned, use the `page[size]` parameter with any integer value between 1 and 100. Each result includes the company name, similarity score, rank, and key firmographic attributes such as industry, revenue range, employee range, and country.' parameters: - name: filter[companyId] in: query required: false description: Unique ZoomInfo identifier for the reference company used to retrieve lookalikes. Required if companyName is not provided. schema: type: string explode: false - name: filter[companyName] in: query required: false description: Name of the reference company used to retrieve lookalikes. Required if companyId is not provided. schema: type: string explode: false - name: filter[sameRevenueRange] in: query required: false description: When true, restricts results to companies within the same revenue range as the reference company. schema: type: boolean explode: false - name: filter[sameCountry] in: query required: false description: When true, restricts results to companies in the same country as the reference company. schema: type: boolean explode: false - name: filter[sameIndustry] in: query required: false description: When true, restricts results to companies in the same industry as the reference company. schema: type: boolean explode: false - name: filter[sameEmployeeRange] in: query required: false description: When true, restricts results to companies within the same employee count range as the reference company. schema: type: boolean explode: false - name: page[size] in: query required: false description: Number of records to return per page. Default is 25, maximum is 100. schema: type: integer format: int32 minimum: 1 maximum: 100 default: 25 explode: false responses: '200': description: Success content: application/vnd.api+json: schema: $ref: '#/components/schemas/CompanyLookalikesResponse' '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: - Recommendations security: - OAuth2Auth: - api:recommendations:read x-api-roles: - fea:zia - fea:api x-api-role-requirement: ANY_REQUIRED /copilot/v1/contacts/recommendations: get: operationId: ContactRecommendationsInterface_getContactRecommendations summary: Get Contact Recommendations description: "Contact Recommendations can be used to retrieve a ranked list of people at a target company who are most relevant for\na given sales motion (use case), such as prospecting, deal acceleration, or renewal and growth. The recommendations\nare derived from past user interactions and account activity, and are ranked by a machine learning model.\nThese recommendations can be used to build targeted call lists, prioritize outreach, or guide sellers toward the right\nstakeholders within an account.\n\nTo find Contact Recommendations select the appropriate `useCaseType` (for example, PROSPECTING or DEAL_ACCELERATION) and the\ntarget company (`filter[ziCompanyId]`). These inputs tell the model which sales motion you are running and which\naccount you want to focus on, so that it can surface the most relevant personas based on historical past user interactions or engagements.\n\nBehind the scenes, the model leverages data such as the user's past contact views, exports, and copies for the PROSPECTING motion, \nor contacts from a user's CRM related to closed won deals for the DEAL_ACCELERATION motion. \nThe model uses this data to infer which types of people are most likely to drive success for the selected motion. \nIt then finds similar contacts at the target company and scores them using a combination of similarity and propensity signals.\n\nThe endpoint returns up to 100 recommended contacts, ordered from most to least relevant. To control the number of recommendations returned, \nuse the `page[size]` parameter with any integer value between 1 and 100. Each recommendation contains additional metadata (`meta`)\nthat describes the reference person used to form the recommendation. Each recommendation includes the general similarity score (`score`), \na re-ranking score (`reRankingScore`) which uses several propensity signals (such as contact similarity, contact quality, title boosting, etc.)\nto refine relevancy. Returns `-1.0` when the ML reranking model did not run. Explainability metadata (`meta`) describes why this person was recommended (for example, the reference person\nand source of the interaction)." parameters: - name: filter[useCaseType] in: query required: true description: Use case type for the recommendation. This filters recommendations based on the sales motion, such as prospecting, deal acceleration, or renewal and growth. schema: $ref: '#/components/schemas/UseCaseType' explode: false - name: filter[ziCompanyId] in: query required: true description: Unique identifier for a target company (ZoomInfo Company ID) in which to get contact recommendations. schema: type: integer format: int64 explode: false - name: page[size] in: query required: false description: Number of records to return per page. Default is 25, maximum is 100. schema: type: integer format: int32 minimum: 1 maximum: 100 default: 25 explode: false responses: '200': description: Success content: application/vnd.api+json: schema: $ref: '#/components/schemas/ContactRecommendationResponse' '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: - Recommendations security: - OAuth2Auth: - api:recommendations:read x-api-roles: - fea:zia - fea:api x-api-role-requirement: ANY_REQUIRED /copilot/v1/contacts/lookalikes: get: operationId: ContactLookalikesInterface_getContactLookalikes summary: Get Contact Lookalikes description: "Contact Lookalikes can be used to retrieve a ranked list of people who are most similar to a given reference person. \nThe recommendations are generated by a machine learning model that compares the reference person's profile to other contacts. \nThe profile includes person characteristics such as title, seniority, department, as well as company characteristics such as industry and company size.\nThese lookalike contacts can be used to identify additional stakeholders, expand buyer networks, or build targeted prospecting lists based on known high-priority contacts.\n\nTo find Contact Lookalikes, select the `referencePersonId`, which identifies the person whose profile you want to use as the\nbasis for finding lookalikes. You can optionally provide a `targetCompanyId` to constrain the search to a specific\ncompany. If `targetCompanyId` is not provided, the model will search for similar contacts across all companies in the Zoominfo database.\n\nBehind the scenes, the model uses a semantic vector representation of the reference person's profile to efficiently find similar contact profiles in the ZoomInfo database. \nIt then applies a re-ranking algorithm to the set of similar contacts found, in order to boost relevance in the final return list. \n\nThe endpoint returns up to 100 lookalike contacts ordered from the most similar contact to the least similar contact (descending order by similarity score `attributes.score`). \nTo control the number of lookalikes returned, use the `page[size]` parameter with any integer value between 1 and 100. Each lookalike contact contains additional metadata (`meta`)\nthat describes the reference person used as the basis of the lookalike." parameters: - name: filter[targetCompanyId] in: query required: false description: 'Unique identifier (ZoomInfo Company ID) for the target company where lookalike contacts are searched. If not provided, the search is performed within the reference person''s company. Example: * If Apple''s Zoominfo Company ID is provided, the endpoint will search for contacts within Apple that have similar persona attributes to the provided `referencePersonId`. * If `targetCompanyId` **IS NOT** provided, the endpoint will search for contacts across all company that have similar persona attributes to the provided `referencePersonId`.' schema: type: integer format: int64 explode: false - name: filter[referencePersonId] in: query required: true description: 'Unique identifier for the reference person (ZoomInfo Person ID) that is used to search contact lookalikes. This is a required field. Example: * If a `referencePersonId` pointing to a person in Microsoft is provided, and if Apple''s Zoominfo Company ID is provided as `targetCompanyId`, the endpoint will search for contacts within Apple that have similar persona attributes to this reference person from Microsoft. * Using the same example but if `targetCompanyId` **IS NOT** provided, the endpoint will search for contacts across all companies with similar persona attributes to the reference person from Microsoft.' schema: type: integer format: int64 explode: false - name: page[size] in: query required: false description: Number of records to return per page. Default is 25, maximum is 100. schema: type: integer format: int32 minimum: 1 maximum: 100 default: 25 explode: false responses: '200': description: Success content: application/vnd.api+json: schema: $ref: '#/components/schemas/ContactLookalikeResponse' '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: - Recommendations security: - OAuth2Auth: - api:recommendations:read x-api-roles: - fea:zia - fea:api x-api-role-requirement: ANY_REQUIRED components: schemas: CompanyLookalikesResponse: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/CompanyLookalike' description: The primary data of the document description: Response model for company lookalikes ExplainabilityMetadata: type: object properties: sourceType: allOf: - $ref: '#/components/schemas/SourceType' description: Source interaction type used to generate this recommendation, such as copied, exported, viewed, or CRM closed-won contacts. referencePersonId: type: integer format: int64 description: Unique identifier for a reference person (ZoomInfo Person ID). A reference person is someone the salesperson has interacted with through the ZoomInfo platform (e.g. copy, export, view) or a contact found in the tenant's CRM from past closed-won deals. referencePersonBrief: type: string description: Brief description of the reference person's profile that was used to generate this recommendation. description: Explainability metadata for a contact recommendation. 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. ContactRecommendation: 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: ContactRecommendation pattern: ContactRecommendation attributes: allOf: - $ref: '#/components/schemas/ContactRecommendationAttributes' description: The attributes defining the resource meta: allOf: - $ref: '#/components/schemas/ExplainabilityMetadata' description: Non-standard meta information about the resource description: Contact recommendation resource. ContactRecommendationAttributes: type: object required: - rank - score - reRankingScore properties: rank: type: integer format: int32 description: Rank of the recommended contact (1-based, lower is better). Contacts are ordered from most to least relevant. score: type: number format: double description: Similarity score between the reference person and the recommended contact. Higher values indicate greater similarity. Due to the nature of vector store similarity calculations, values may occasionally exceed 1.0. reRankingScore: type: number format: double description: Re-ranking score of the recommended contact, produced by a machine learning model applied after initial retrieval to refine relevancy using propensity signals (contact similarity, quality, title boosting, etc.). Higher values indicate greater relevancy. Returns -1.0 when the ML reranking model did not run. recommendedPersonBrief: type: string description: Brief description of the recommended contact's profile, used to explain why this person was recommended. Absent when profile data is unavailable. description: Attributes for a contact recommendation entity. CompanyLookalike: 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: CompanyLookalike pattern: CompanyLookalike attributes: allOf: - $ref: '#/components/schemas/SimilarCompanyAttributes' description: The attributes defining the resource description: Resource model for a company lookalike result. 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 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 LookalikeMetadata: type: object required: - referencePersonId - referencePersonBrief properties: referencePersonId: type: integer format: int64 description: Unique identifier for the reference person (ZoomInfo Person ID) that is used to search contact lookalikes. referencePersonBrief: type: string description: Brief description of the reference person used to find lookalike contacts. description: Metadata for a lookalike contact entity. ContactLookalikeAttributes: type: object required: - rank - score - lookalikePersonBrief properties: rank: type: integer format: int32 description: Rank of the lookalike contact, with 1 being the most similar to the reference person. score: type: number format: double description: Similarity score between the reference person and the lookalike contact, ranging from 0 to 1. Higher values indicate higher similarity. lookalikePersonBrief: type: string description: Brief description of the lookalike contact. description: Attributes for a contact lookalike entity. ContactRecommendationResponse: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/ContactRecommendation' description: The primary data of the document description: Response model for contact recommendations. ContactLookalikeResponse: type: object required: - data properties: data: type: array items: $ref: '#/components/schemas/ContactLookalike' description: The primary data of the document description: Response model for contact lookalikes. SimilarCompanyAttributes: type: object required: - companyName - score - rank - industry - revenueRange - employeeRange - country properties: companyName: type: string description: Name of the lookalike company. score: type: number format: double description: Similarity score between the input company and the lookalike company, ranging from 0 to 1. Higher values indicate higher similarity. rank: type: integer format: int32 description: Rank of the lookalike company in the results, with 1 being the most similar. industry: type: string description: Primary industry of the lookalike company. revenueRange: type: string description: Revenue range of the lookalike company. employeeRange: type: string description: Employee count range of the lookalike company. country: type: string description: Country where the lookalike company is headquartered. description: Attributes describing a single similar company. UseCaseType: type: string enum: - PROSPECTING - DEAL_ACCELERATION - RENEWAL_AND_GROWTH description: Type of use case for contact recommendations. x-enumDescriptions: PROSPECTING: Prospecting. Used when a sales person is looking to reach out to contacts to establish a connection with a new account/company to pitch their company's product. DEAL_ACCELERATION: Deal acceleration. Used when a sales person has already established a connection and pitched their product with a potential buyer account/company, found potential product fit, and is in the process of confirming interest and negotiating a deal. RENEWAL_AND_GROWTH: Renewal and growth. Used when a sales person is interacting with an existing customer to renew a deal or expand the account (for example, more seats or an upgraded pricing model). ContactLookalike: 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: ContactLookalike pattern: ContactLookalike attributes: allOf: - $ref: '#/components/schemas/ContactLookalikeAttributes' description: The attributes defining the resource meta: allOf: - $ref: '#/components/schemas/LookalikeMetadata' description: Non-standard meta information about the resource description: Contact lookalikes resource SourceType: type: string enum: - AMPLITUDE_COPIED_CONTACTS - AMPLITUDE_EXPORTED_CONTACTS - AMPLITUDE_VIEWED_CONTACTS - CRM_CLOSED_WON_ENGAGED_CONTACTS - CRM_CLOSED_WON_CONTACTS - COLD_START_CONTACTS description: Source interaction type used to generate contact recommendations. x-enumDescriptions: AMPLITUDE_COPIED_CONTACTS: Contacts copied from ZoomInfo during prospecting. AMPLITUDE_EXPORTED_CONTACTS: Contacts exported from ZoomInfo in bulk. AMPLITUDE_VIEWED_CONTACTS: Contacts viewed via contact card/profile in ZoomInfo. CRM_CLOSED_WON_ENGAGED_CONTACTS: Contacts that were engaged with in closed-won deals in the user's CRM. CRM_CLOSED_WON_CONTACTS: Contacts recorded as connected to successful (closed-won) deals in the user's CRM. COLD_START_CONTACTS: Contacts of interest for new users or cold-start scenarios where there is limited interaction history. 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)