> ## Documentation Index
> Fetch the complete documentation index at: https://cal.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List suggested contacts

> Returns people the authenticated user keeps meeting but hasn't added as personal contacts: attendees of at least 4 accepted, past bookings the user hosted in the last 12 months. Existing contacts, the user's own emails, dismissed suggestions and blocked emails are left out. Ordered by meeting count, then most recent meeting, with limit/cursor pagination; when pagination.hasMore is true, pass pagination.nextCursor as cursor. To accept a suggestion, add it with `POST /v2/contacts` using its email and name. To hide it for good, dismiss it with `POST /v2/contacts/suggestions/dismissals`. If accessed using an OAuth access token, the `CONTACT_READ` scope is required.



## OpenAPI

````yaml /api-reference/v2/openapi.json get /v2/contacts/suggestions
openapi: 3.0.0
info:
  title: Cal.com API v2
  description: ''
  version: 1.0.0
  contact: {}
servers: []
security: []
tags: []
paths:
  /v2/contacts/suggestions:
    get:
      tags:
        - Contacts
      summary: List suggested contacts
      description: >-
        Returns people the authenticated user keeps meeting but hasn't added as
        personal contacts: attendees of at least 4 accepted, past bookings the
        user hosted in the last 12 months. Existing contacts, the user's own
        emails, dismissed suggestions and blocked emails are left out. Ordered
        by meeting count, then most recent meeting, with limit/cursor
        pagination; when pagination.hasMore is true, pass pagination.nextCursor
        as cursor. To accept a suggestion, add it with `POST /v2/contacts` using
        its email and name. To hide it for good, dismiss it with `POST
        /v2/contacts/suggestions/dismissals`. If accessed using an OAuth access
        token, the `CONTACT_READ` scope is required.
      operationId: ContactSuggestionsController_list
      parameters:
        - name: limit
          required: false
          in: query
          description: Maximum number of suggestions to return.
          schema:
            minimum: 1
            maximum: 50
            default: 50
            example: 50
            type: number
        - name: cursor
          required: false
          in: query
          description: Opaque cursor from pagination.nextCursor. Omit for the first page.
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            value must be `Bearer <token>` where `<token>` is api key prefixed
            with cal_, managed user access token, or OAuth access token
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListContactSuggestionsOutputResponseDto'
        '400':
          description: Invalid cursor
        '401':
          description: Unauthenticated
        '403':
          description: Insufficient permissions
        '429':
          description: Too many contact lookups
components:
  schemas:
    ListContactSuggestionsOutputResponseDto:
      type: object
      properties:
        status:
          enum:
            - success
            - error
          type: string
          example: success
        data:
          type: array
          items:
            $ref: '#/components/schemas/ContactSuggestionOutput'
        pagination:
          $ref: '#/components/schemas/ContactsCursorPaginationMetaDto'
      required:
        - status
        - data
        - pagination
    ContactSuggestionOutput:
      type: object
      properties:
        email:
          type: string
          description: The attendee's email, lowercased.
          example: jamie.rivera@example.com
        name:
          type: string
          description: The attendee's name on the most recent booking with them.
          example: Jamie Rivera
        meetingCount:
          type: number
          description: >-
            How many accepted, past bookings the user hosted with this attendee
            in the last 12 months.
          example: 6
        lastMetAt:
          type: string
          description: When the most recent of those bookings was made, in ISO 8601 UTC.
          example: '2026-10-02T09:30:00.000Z'
      required:
        - email
        - name
        - meetingCount
        - lastMetAt
    ContactsCursorPaginationMetaDto:
      type: object
      properties:
        nextCursor:
          type: string
          nullable: true
          description: >-
            Opaque cursor to fetch the next page. Pass this value as the cursor
            query parameter with the same filters. null when hasMore is false.
        hasMore:
          type: boolean
          description: Whether more pages are available after this one.
      required:
        - nextCursor
        - hasMore

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.