# List contacts

`GET /api/v1/vaults/{vault}/contacts`

List the people one of your vaults holds, narrowed and ordered the way the people screen narrows and orders them.

The default order is by name, not by when somebody was written down, so that a program and a person looking at the same vault are looking at the same list. The order always ends on the id, which is what stops a contact being skipped or repeated by a page boundary moving while you page through.

Three groups of people are never in the list you asked for. Partial contacts, somebody mentioned in a relationship and reduced to a first name, are only in names-only until they are filled in. Archived contacts and deleted contacts are in none of them at all.

A vault holding nobody answers with an empty list rather than an error.

Each contact also carries columns: what the people screen of this vault shows beside the name, in its order, and the values each one holds for this person. A column holding several values, somebody with two email addresses, lists them all. A column holding nothing lists nothing. The values are written the way the screen writes them, dates included, and the raw dates stay in the attributes. The columns are the ones chosen with the endpoints below, or the defaults until somebody chooses.

This endpoint also answers QUERY, with the same parameters sent in the request body. [How QUERY works](https://my.monicahq.com/docs/api/query-method).

## Parameters

- `vault` (string, required): The vault the contact lives in, named either by the readable name it reports as slug or by its id. Both answer.
- `filter` (string, optional, defaults to all): Which people to list: all, favourites or names-only. Partial contacts are only in names-only, so all does not mean everybody the vault holds.
- `query` (string, optional): A search term, up to 255 characters. It is matched against the whole name, ignoring what the language of the account calls a minor difference, so elodie finds Élodie in French. It is also matched against the nickname as it was typed, ignoring case.
- `sort` (string, optional, defaults to name): Which order to answer in: name, nickname, last-spoke or added. A contact the order knows nothing about, somebody with no nickname when sorting by nickname, is at the end whichever direction is asked for.
- `direction` (string, optional, defaults to asc): Either asc or desc.
- `page` (integer, optional, defaults to 1): Which page to answer with.
- `per_page` (integer, optional, defaults to 25): How many contacts one page holds, between 1 and 100. A number outside the range is brought back into it rather than refused.
- `categories[]` (integer, optional): Narrow the list to the people holding any of these categories, by the ids the list of categories below gives. It narrows together with the filter. An id that is not one of your contact categories answers 422.

## Returns

A page of contact objects, and how many there are in all. A vault belonging to somebody else answers 404.

- `data` (array): The contacts on this page. An empty list rather than an error when there are none.
- `data[]` (object): One contact.
- `data[].type` (string): Always contact. It names the kind of record, so a caller holding several kinds can tell them apart without looking at where they came from.
- `data[].id` (string): The id of this record, as a string even when it reads as a number. It is what every endpoint naming this record takes.
- `data[].attributes` (object): Everything the record holds.
- `data[].attributes.slug` (string): The readable name the contact is addressed by, built from the whole name above and unique within the vault. It keeps the alphabet the name is written in, so a name in Japanese is addressed in Japanese, sent as its own characters or percent encoded. It is not stable: correcting the name rebuilds it and the previous one stops answering, which is why a stored reference should be the id. Nothing lets you choose or edit it.
- `data[].attributes.name` (string): The name the contact is shown under: the formatted name of the way of writing it chosen for display, else its parts in the order it reads in. It is what the lists sort on, and it is built rather than stored, so it cannot be written directly.
- `data[].attributes.formatted_name` (string): The full name exactly as written for the way of writing it chosen for display, or null when that way is only parts.
- `data[].attributes.name_representations` (array): Every way the current name is written: in its own script, transliterated into another, or as it is pronounced, in the order the owner put them. Every one of them finds the contact in a search. Nothing is transliterated for you.
- `data[].attributes.name_representations[]` (object): One way of writing the name.
- `data[].attributes.name_representations[].id` (uuid): The id of this way of writing the name. Send it back to keep it when the list is replaced.
- `data[].attributes.name_representations[].kind` (string): written for the name in a script of its own, transliteration for the name carried into another script, phonetic for how it is pronounced.
- `data[].attributes.name_representations[].language` (string): A BCP 47 language tag such as ko or ja, or null.
- `data[].attributes.name_representations[].script` (string): An ISO 15924 script code such as Hang, Hani or Latn, or null.
- `data[].attributes.name_representations[].phonetic_system` (string): For a pronunciation, the system it is written in, as the vCard PHONETIC parameter names it: ipa, piny, x-romaji, x-rr, x-other, or a token a device sent. Null for any other kind.
- `data[].attributes.name_representations[].formatted_name` (string): The full name exactly as it should appear, up to 255 characters, or null to build it from the parts. Always null for a pronunciation, which is written in its parts.
- `data[].attributes.name_representations[].prefix` (string): Up to 50 characters, or null.
- `data[].attributes.name_representations[].given_name` (string): Up to 255 characters, or null.
- `data[].attributes.name_representations[].additional_name` (string): Other given names, up to 255 characters, or null.
- `data[].attributes.name_representations[].family_name` (string): Up to 255 characters, or null.
- `data[].attributes.name_representations[].suffix` (string): Up to 50 characters, or null.
- `data[].attributes.name_representations[].name_order` (string): Either given_first or family_first, or null to leave it to the reader.
- `data[].attributes.name_representations[].position` (integer): Where it stands in the list, from 1.
- `data[].attributes.name_representations[].is_display` (boolean): Whether this is the way the contact is shown under, in lists, titles, notifications and initials. Exactly one is, whenever the contact has a name.
- `data[].attributes.prefix` (string): What comes before the name, up to 50 characters, or null. Dr and Sir are prefixes.
- `data[].attributes.first_name` (string): The given name of the way of writing the name chosen for display, up to 255 characters, or null. Like the prefix, the middle name, the last name, the suffix and the name order, it is a copy read from that way of writing it.
- `data[].attributes.middle_name` (string): Up to 255 characters, or null.
- `data[].attributes.last_name` (string): The family name, up to 255 characters, or null.
- `data[].attributes.suffix` (string): What comes after the name, up to 50 characters, or null. Jr and PhD are suffixes.
- `data[].attributes.maiden_name` (string): Up to 255 characters, or null.
- `data[].attributes.nickname` (string): What this person is actually called, up to 255 characters, or null. It is searched as it was typed rather than folded, and it is what the whole name falls back to when no other part is set.
- `data[].attributes.name_order` (string): Either given_first or family_first, or null to leave it to the reader. It is a fact about this person rather than a preference of yours, which is what lets a Japanese name keep its order in a list of western ones.
- `data[].attributes.initials` (string): The one or two letters drawn when the contact has no picture. Built from the name, so it cannot be written.
- `data[].attributes.avatar_colour` (string): The background those initials are drawn on, as a hex colour. It is chosen when the contact is written down and never changes afterwards, so somebody who has learnt to spot a face in a list does not have it move.
- `data[].attributes.avatar` (object): The picture, or null when the contact is drawn as its initials.
- `data[].attributes.avatar.id` (uuid): The id of the file the picture was stored as. It is a file of the vault like any other, so it counts against your storage.
- `data[].attributes.avatar.url` (string): Where the picture is served from. This address is served by the application and needs a signed in session rather than a token: no endpoint here streams a vault's files yet, and a document is as private as the record it sits on.
- `data[].attributes.is_favourite` (boolean): Whether the contact sits at the top of the list.
- `data[].attributes.is_archived` (boolean): Whether the contact has been put away. An archived contact is left out of every list. Reading this is possible here; changing it is not, because no screen offers the gesture either.
- `data[].attributes.is_partial` (boolean): Whether the contact is somebody mentioned in a relationship and reduced to a first name. A partial contact is off every list until somebody fills them in, so it is listed by no filter at all.
- `data[].attributes.is_me` (boolean): Whether this contact represents you. Exactly one contact per vault is, it cannot be deleted, and nothing here hands the title to somebody else.
- `data[].attributes.age` (integer): How old the contact is in whole years, on your current day in your time zone. Null when the birthday is not recorded, when its year or its month is unknown, or when its date lies in the future. Null too when the birthday field is sensitive and the key lacks the sensitive-fields ability. It is worked out on every read and never stored.
- `data[].attributes.next_birthday_on` (string): The next birthday as a date written Y-m-d, on or after your current day in your time zone, so it is today's date on the birthday itself. A birthday on 29 February falls on 28 February in a year without one. Null when the birthday is not recorded, when its month is unknown, or when the birthday field is sensitive and the key lacks the sensitive-fields ability.
- `data[].attributes.structure_version_id` (integer): The published version of the template this contact renders from. It says what pages the contact has and what is written on them. Publishing a new version moves nobody: a contact stays on the version it points at until it is moved.
- `data[].attributes.template_name` (string): What that template is called, which is what the lists show beside a contact.
- `data[].attributes.categories` (array): The categories the contact holds, in the order of your list of contact categories. A category is a choice of that list held in any field of the template drawing on it. Empty when the contact holds none.
- `data[].attributes.categories[]` (object): One category.
- `data[].attributes.categories[].id` (integer): The id of the category, which is what the list of contacts filters on.
- `data[].attributes.categories[].label` (string): What the category is called, in the language of the request for a category the application supplied.
- `data[].attributes.last_life_event_at` (timestamp): When the contact last took part in a life event, as a count of seconds since 1970, or null when they never have. It says nothing about whether you were there.
- `data[].attributes.last_interaction_at` (timestamp): The Last in touch date: the day of the latest life event the contact took part in that has already happened and whose nature has updates_last_in_touch, as a count of seconds since 1970, or null when there is none. This is what Last in touch and Last spoke read.
- `data[].attributes.last_consulted_at` (timestamp): When the contact was last consulted on their own, as a count of seconds since 1970, or null when they never have been: their page opened in Monica, the contact read through this endpoint, or read by an assistant connected over MCP. Listing contacts does not change it.
- `data[].attributes.created_at` (timestamp): When the contact was written down, as a count of seconds since 1970 rather than a written date.
- `data[].attributes.updated_at` (timestamp): When the contact last changed, as a count of seconds. Equal to created_at until it first changes.
- `data[].links` (object): Where to find this record.
- `data[].links.self` (string): The absolute address this record is read from.
- `data[].links.web` (string): The page of the contact in the application, which opens for somebody signed in rather than for a key. It is the link to give a person.
- `meta` (object): Where you are in the collection.
- `meta.page` (integer): The page this is, counting from 1.
- `meta.per_page` (integer): How many one page holds, which is the size that was asked for once it has been brought into the allowed range.
- `meta.total` (integer): How many contacts there are in all, not how many are on this page.
- `data[].columns` (array): What the people screen of this vault shows beside the name, in its order. Hidden columns, and columns no template supplies any more, are left out.
- `data[].columns[]` (object): One column.
- `data[].columns[].source` (string): What the column shows, one of the sources the column endpoints below list.
- `data[].columns[].section` (uuid): For a field of a template, the section holding it, or null.
- `data[].columns[].field_key` (string): For a field of a template, its key inside the section, or null.
- `data[].columns[].values` (array): What this person holds in the column, written the way the screen writes it. Empty when they hold nothing.
- `data[].columns[].values[]` (string): One value.

## Rate limit

Sixty requests per minute, per user, shared by every key and device. Every answer carries the budget left in `X-RateLimit-Remaining`.

## Request

```sh
curl https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contacts \
  -H "Authorization: Bearer $MONICA_TOKEN"
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contacts', {
  headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contacts');
```

## Response

`200`

```json
{
    "data": [
        {
            "type": "contact",
            "id": "c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364",
            "attributes": {
                "slug": "pam-beesly",
                "name": "Pam Beesly",
                "formatted_name": null,
                "name_representations": [
                    {
                        "id": "0e6d3b1a-52c7-4f9e-8a41-b7d2c96f0e13",
                        "kind": "written",
                        "language": null,
                        "script": null,
                        "phonetic_system": null,
                        "formatted_name": null,
                        "prefix": null,
                        "given_name": "Pam",
                        "additional_name": null,
                        "family_name": "Beesly",
                        "suffix": null,
                        "name_order": "given_first",
                        "position": 1,
                        "is_display": true
                    }
                ],
                "prefix": null,
                "first_name": "Pam",
                "middle_name": null,
                "last_name": "Beesly",
                "suffix": null,
                "maiden_name": null,
                "nickname": "Pammy",
                "name_order": "given_first",
                "initials": "PB",
                "avatar_colour": "#0ea5e9",
                "avatar": {
                    "id": "3f6c1d90-4b27-4e85-a1c3-9d720f5b8e46",
                    "url": "https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/files/3f6c1d90-4b27-4e85-a1c3-9d720f5b8e46"
                },
                "is_favourite": true,
                "is_archived": false,
                "is_partial": false,
                "is_me": false,
                "age": 36,
                "next_birthday_on": "2026-03-14",
                "structure_version_id": 4,
                "template_name": "Default contact",
                "categories": [
                    {
                        "id": 12,
                        "label": "Colleague"
                    }
                ],
                "last_life_event_at": null,
                "created_at": 1756252800,
                "last_interaction_at": null,
                "last_consulted_at": 1756339200,
                "updated_at": 1756339200
            },
            "links": {
                "self": "https://my.monicahq.com/api/v1/vaults/dunder-mifflin/contacts/pam-beesly",
                "web": "https://my.monicahq.com/vaults/dunder-mifflin/contacts/pam-beesly"
            },
            "columns": [
                {
                    "source": "email",
                    "section": null,
                    "field_key": null,
                    "values": [
                        "pam@dundermifflin.com",
                        "pambeesly@gmail.com"
                    ]
                },
                {
                    "source": "phone",
                    "section": null,
                    "field_key": null,
                    "values": [
                        "+1 570 555 0162 (Work)"
                    ]
                },
                {
                    "source": "last-spoke",
                    "section": null,
                    "field_key": null,
                    "values": []
                }
            ]
        },
        {
            "type": "contact",
            "id": "7b2e9034-5c18-4af6-9d21-0e83b6c47a5f",
            "attributes": {
                "slug": "dwight-kurt-schrute",
                "name": "Dwight Kurt Schrute",
                "formatted_name": null,
                "name_representations": [
                    {
                        "id": "9a27c5e1-3f84-4b6d-8e02-d1b7a4c96f38",
                        "kind": "written",
                        "language": null,
                        "script": null,
                        "phonetic_system": null,
                        "formatted_name": null,
                        "prefix": null,
                        "given_name": "Dwight",
                        "additional_name": "Kurt",
                        "family_name": "Schrute",
                        "suffix": null,
                        "name_order": null,
                        "position": 1,
                        "is_display": true
                    }
                ],
                "prefix": null,
                "first_name": "Dwight",
                "middle_name": "Kurt",
                "last_name": "Schrute",
                "suffix": null,
                "maiden_name": null,
                "nickname": null,
                "name_order": null,
                "initials": "DS",
                "avatar_colour": "#22c55e",
                "avatar": null,
                "is_favourite": false,
                "is_archived": false,
                "is_partial": false,
                "is_me": false,
                "age": null,
                "next_birthday_on": null,
                "structure_version_id": 4,
                "template_name": "Default contact",
                "categories": [],
                "last_life_event_at": 1756166400,
                "created_at": 1756080000,
                "last_interaction_at": 1756166400,
                "last_consulted_at": null,
                "updated_at": 1756080000
            },
            "links": {
                "self": "https://my.monicahq.com/api/v1/vaults/dunder-mifflin/contacts/dwight-kurt-schrute",
                "web": "https://my.monicahq.com/vaults/dunder-mifflin/contacts/dwight-kurt-schrute"
            },
            "columns": [
                {
                    "source": "email",
                    "section": null,
                    "field_key": null,
                    "values": [
                        "dwight@schrutefarms.com"
                    ]
                },
                {
                    "source": "phone",
                    "section": null,
                    "field_key": null,
                    "values": []
                },
                {
                    "source": "last-spoke",
                    "section": null,
                    "field_key": null,
                    "values": [
                        "3 weeks ago"
                    ]
                }
            ]
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 2
    }
}
```
