API v1
v1
View as Markdown

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.

Parameters

Sent as JSON. Anything not listed here is ignored.

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 default: 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 default: 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 default: asc

Either asc or desc.

page integer Optional default: 1

Which page to answer with.

per_page integer Optional default: 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.

GET
curl https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contacts \
-H "Authorization: Bearer $MONICA_TOKEN"
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()
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contacts');
Response 200
{
"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": [
]
},
{
"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": [
]
},
{
"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
}
}

Keys act as you, with exactly the access you have. Make one per integration so you can revoke it alone.