API v1
v1
View as Markdown

List the categories held in a vault

GET /api/v1/vaults/{vault}/contact-categories

List the categories somebody in a vault holds, with how many people hold each, which is what the people screen offers to narrow its list with.

A category is a choice of your list of contact categories, which every vault of the account shares. Only the categories somebody in the vault holds are listed, in the order of the list, and a category that is no longer offered is still listed while somebody holds it. A person holding a category in two fields counts once.

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

Count only the people of one grouping: all, favourites or names-only.

Returns

Every category held in the vault, with how many people hold it. A vault belonging to somebody else answers 404.

data array

The categories, in the order of the list.

data[] object

One category.

data[].type string

Always contact_category.

data[].id integer

The id of the category, which the list of contacts filters on.

data[].attributes object

What the category is.

data[].attributes.label string

What the category is called.

data[].attributes.is_active boolean

False when the category is no longer offered. It stays on the people who hold it.

data[].attributes.contacts_count integer

How many people of the vault hold it.

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/contact-categories \
-H "Authorization: Bearer $MONICA_TOKEN"
const response = await fetch('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contact-categories', {
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/contact-categories');
Response 200
{
"data": [
{
"type": "contact_category",
"id": 12,
"attributes": {
"label": "Colleague",
"is_active": true,
"contacts_count": 4
}
},
{
"type": "contact_category",
"id": 31,
"attributes": {
"label": "Finer Things Club",
"is_active": true,
"contacts_count": 2
}
}
]
}

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