---
title: "List or search contacts"
method: GET
path: "/api/me/contacts"
tags: ["Contacts"]
---

# List or search contacts

`GET /api/me/contacts`

## Request

- Base URL: `https://api.wondercal.com`
- URL: `https://api.wondercal.com/api/me/contacts`
- Auth: HTTP bearer

Returns the authenticated user's contacts. When the 'q' parameter is provided, searches contacts by name (case-insensitive prefix matching). Without 'q', returns all contacts sorted by most recently met.

## Query parameters

- `q` string
- `limit` integer
- `cursor` string

## Response `200`

List of contacts (with optional pagination cursor)

- object
  - `data` union: When 'q' is provided: array of matching contacts. When 'q' is not provided: object with contacts array and pagination cursor.
    - Contact[]: Search results (when 'q' is provided)
      - `id` string: Contact record ID
      - `userId` string: User ID of the contact person
      - `name` string, nullable: Contact's display name
      - `email` string, nullable: Contact's email address
      - `firstMet` string, date-time: ISO 8601 timestamp of first shared meeting
      - `lastMet` string, date-time: ISO 8601 timestamp of most recent shared meeting
      - `meetingCount` integer: Number of meetings shared with this contact
    - object: Paginated list (when 'q' is not provided). Always includes nextCursor (null when no more pages).
      - `contacts` Contact[], required
        - `id` string: Contact record ID
        - `userId` string: User ID of the contact person
        - `name` string, nullable: Contact's display name
        - `email` string, nullable: Contact's email address
        - `firstMet` string, date-time: ISO 8601 timestamp of first shared meeting
        - `lastMet` string, date-time: ISO 8601 timestamp of most recent shared meeting
        - `meetingCount` integer: Number of meetings shared with this contact
      - `nextCursor` string, nullable, required: Cursor for next page, or null if no more results. Always present in list mode.

## Other responses

- `400`: Validation error (invalid q, limit, or cursor)
- `401`: Not authenticated
- `429`: Rate limit exceeded. The Retry-After header indicates how many seconds to wait before retrying.

---

[API](https://skmtc.dev/wondercal/apis/wondercal-api.md) · [All operations](https://skmtc.dev/wondercal/apis/wondercal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wondercal/apis/wondercal-api/revisions/4889176a380f?raw)