---
title: "Get Contact Recommendations"
method: GET
path: "/copilot/v1/contacts/recommendations"
tags: ["Recommendations"]
---

# Get Contact Recommendations

`GET /copilot/v1/contacts/recommendations`

## Request

- Base URL: `https://api.zoominfo.com/gtm`
- URL: `https://api.zoominfo.com/gtm/copilot/v1/contacts/recommendations`
- Auth: OAuth 2
  - Authorization code: `https://login.zoominfo.com`
  - Token URL: `https://okta-login.zoominfo.com/oauth2/default/v1/token` scopes: `api:recommendations:read`

Contact Recommendations can be used to retrieve a ranked list of people at a target company who are most relevant for
a given sales motion (use case), such as prospecting, deal acceleration, or renewal and growth. The recommendations
are derived from past user interactions and account activity, and are ranked by a machine learning model.
These recommendations can be used to build targeted call lists, prioritize outreach, or guide sellers toward the right
stakeholders within an account.

To find Contact Recommendations select the appropriate `useCaseType` (for example, PROSPECTING or DEAL_ACCELERATION) and the
target company (`filter[ziCompanyId]`). These inputs tell the model which sales motion you are running and which
account you want to focus on, so that it can surface the most relevant personas based on historical past user interactions or engagements.

Behind the scenes, the model leverages data such as the user's past contact views, exports, and copies for the PROSPECTING motion, 
or contacts from a user's CRM related to closed won deals for the DEAL_ACCELERATION motion. 
The model uses this data to infer which types of people are most likely to drive success for the selected motion. 
It then finds similar contacts at the target company and scores them using a combination of similarity and propensity signals.

The endpoint returns up to 100 recommended contacts, ordered from most to least relevant. To control the number of recommendations returned, 
use the `page[size]` parameter with any integer value between 1 and 100. Each recommendation contains additional metadata (`meta`)
that describes the reference person used to form the recommendation. Each recommendation includes the general similarity score (`score`), 
a re-ranking score (`reRankingScore`) which uses several propensity signals (such as contact similarity, contact quality, title boosting, etc.)
to 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
and source of the interaction).

## Query parameters

- `filter[useCaseType]` 'PROSPECTING' | 'DEAL_ACCELERATION' | 'RENEWAL_AND_GROWTH', required: Type of use case for contact recommendations.
- `filter[ziCompanyId]` integer, required
- `page[size]` integer

## Response `200`

Success

- ContactRecommendationResponse: Response model for contact recommendations.
  - `data` ContactRecommendation[], required: The primary data of the document
    - `id` string, required: The unique identifier for the resource
    - `type` string, required: The type of the resource
    - `attributes` ContactRecommendationAttributes, required: Attributes for a contact recommendation entity.
      - `rank` integer, required: Rank of the recommended contact (1-based, lower is better). Contacts are ordered from most to least relevant.
      - `score` number, double, required: 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` number, double, required: 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` string: Brief description of the recommended contact's profile, used to explain why this person was recommended. Absent when profile data is unavailable.
    - `meta` ExplainabilityMetadata: Explainability metadata for a contact recommendation.
      - `sourceType` 'AMPLITUDE_COPIED_CONTACTS' | 'AMPLITUDE_EXPORTED_CONTACTS' | 'AMPLITUDE_VIEWED_CONTACTS' | 'CRM_CLOSED_WON_ENGAGED_CONTACTS' | 'CRM_CLOSED_WON_CONTACTS' | 'COLD_START_CONTACTS': Source interaction type used to generate contact recommendations.
      - `referencePersonId` integer: 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` string: Brief description of the reference person's profile that was used to generate this recommendation.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `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)