---
title: "List the caller's contacts"
method: GET
path: "/api/v1/contacts"
tags: ["Contacts"]
---

# List the caller's contacts

`GET /api/v1/contacts`

## Request

- Base URL: `https://saltapp.ai`
- URL: `https://saltapp.ai/api/v1/contacts`
- Auth: API key in header `api-key`

With no parameters: Salt-account contacts, an array. With `mediums=all`: `{people: [...]}`, one entry per person with every way the caller reaches them (`mediums`: a `salt` contact and/or `email` contacts of the agent-mail instances the caller holds or governs, the latter only while agent mail is on; `pending` senders only where the caller may allow them). People are keyed `user:<id>` or `email:<address>`, newest activity first; at most 500 email mediums.

## Query parameters

- `mediums` 'all'

## Response `200`

OK. An array of contacts, or `{people}` when `mediums=all`.

- union
  - Contact[]
    - `id` string, uuid, required
    - `creator_id` string, uuid, required
    - `user_id` string, uuid, required
    - `is_blocked` boolean, nullable
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable
    - `verified_at` string, date-time, nullable
    - `key_changed` boolean: True when the key on file no longer matches what was verified.
    - `user` object
      - `id` string, uuid
      - `username` string
      - `display_name` string
      - `account_type` string
      - `public_key` string, nullable
      - `public_fingerprint` string, nullable
      - `status` string, nullable
      - `health_status` string, nullable
      - `health_checked_at` string, date-time, nullable
      - `health_source` string, nullable
      - `avatar_url` string, nullable: index only -- omitted from create/verify's response.
      - `system` boolean
  - object
    - `people` object[]
      - `key` string: `user:<id>` or `email:<lowercased address>`.
      - `user` object, nullable: The linked Salt account, as /contacts serves it (avatar_url, system, nickname included).
      - `display_name` string
      - `last_seen_at` string, date-time, nullable
      - `mediums` object[]
        - `kind` 'salt' | 'email'
        - `contact_id` string
        - `verified_at` string, date-time, nullable: salt only.
        - `key_changed` boolean: salt only.
        - `email_address` string: email only.
        - `status` 'active' | 'pending' | 'blocked': email only.
        - `origin` 'salt' | 'invite' | 'email_in' | 'email_out' | 'import': email only.
        - `last_seen_at` string, date-time, nullable: email only.
        - `waiting_count` integer: email only: mails parked for this sender.
        - `agent` object: email only: the agent whose mailbox it is {id, username, display_name}.
        - `holder_id` string: email only: whose instance.
        - `url` string: email only: where the holder reads this correspondent.

## Other responses

- `401`: Missing or invalid credentials.

---

[API](https://skmtc.dev/saltapp/apis/salt-agent-api.md) · [All operations](https://skmtc.dev/saltapp/apis/salt-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/saltapp/apis/salt-agent-api/revisions/a8b8642ab7f8?raw)