API v1
v1
View as Markdown

Set your contact list view

PUT /api/v1/me/contact-list-view

Set the view the contact list opens on for the user the token belongs to.

The three choices make one view. A choice left out keeps the one stored, so sending a grouping alone changes the grouping and keeps the order. None of the three can be null.

It applies to every vault the user reaches, and it changes what the interface opens on rather than what this API answers: reading a contact list here takes its own filter, sort and direction, and neither reads nor writes this.

Body parameters

Sent as JSON. Anything not listed here is ignored.

grouping string Optional

Which people the list shows: all, favourites or names-only.

sort string Optional

What the list is ordered by: name, nickname, last-spoke or added.

direction string Optional

Which way round that order runs: asc or desc.

Returns

The updated user object.

data object

The person the token acts as.

data.type string

Always user. 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.first_name string

The given name, up to 255 characters. Which of the two names is shown first is name_order rather than this.

data.attributes.last_name string

The family name, up to 255 characters.

data.attributes.email string

The address the account signs in with, up to 255 characters, always in lower case. It is unique across the instance.

data.attributes.email_verified boolean

Whether the address has been confirmed. Worked out from when it was confirmed rather than stored as a flag, so the moment itself is not something the API hands out.

data.attributes.locale string

The language the product speaks to this person: one of bn_BD, ca_ES, da_DK, de_DE, el_GR, en, es_ES, fi_FI, fil_PH, fr_FR, ga_IE, hi_IN, hu_HU, is_IS, it_IT, ja_JP, ko_KR, lt_LT, nb_NO, nl_NL, pl_PL, pt_BR, pt_PT, ru_RU, si_LK, sv_SE, ta_IN, th_TH, tr_TR, uz_UZ, vi_VN or zh_CN. It never affects anything the person themselves wrote.

data.attributes.timezone string

The zone their times are shown in, as an identifier such as Europe/Paris, up to 64 characters. Every timestamp in this API is a count of seconds regardless, so this is about what a screen shows rather than about what you receive.

data.attributes.time_format string

Either 24 or 12, saying which clock they read.

data.attributes.date_format string

How a date is written for them: one of d/m/Y, m/d/Y, Y-m-d or j F Y, or null when they have not chosen and the language decides.

data.attributes.name_order string

Either given_first or family_first. Which name comes first varies by culture, so it is a setting rather than an assumption.

data.attributes.number_format string

How a number is grouped and pointed: one of comma_dot, dot_comma, space_comma or no_separator, or null when they have not chosen and the language decides.

data.attributes.contact_list_grouping string

Which people the contact list was last showing them: one of all, favourites or names-only, or null until they have opened the list.

data.attributes.contact_list_sort string

What the contact list was last ordered by: one of name, nickname, last-spoke or added, or null until they have opened the list.

data.attributes.contact_list_direction string

Which way round that order ran: asc or desc, or null until they have opened the list.

data.attributes.shows_vault_list boolean

Whether the person lands on the list of their vaults, or goes straight to their default vault. True until they turn it off. While it is false, their default vault cannot be deleted.

data.attributes.welcomed_at timestamp

When the user dismissed the welcome screen, as a count of seconds, or null if they have not.

data.attributes.full_access_offer_dismissed_at timestamp

When the user hid the banner offering full access, as a count of seconds, or null if they have not.

data.attributes.created_at timestamp

When the account was opened, as a count of seconds since 1970 rather than a written date.

data.attributes.updated_at timestamp

When the profile 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.

Rate limit

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

PUT
curl https://my.monicahq.com/api/v1/me/contact-list-view \
-X PUT \
-H "Authorization: Bearer $MONICA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"grouping": "favourites",
"sort": "last-spoke",
"direction": "desc"
}'
const response = await fetch('https://my.monicahq.com/api/v1/me/contact-list-view', {
method: 'PUT',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
grouping: 'favourites',
sort: 'last-spoke',
direction: 'desc',
}),
})
const data = await response.json()
$response = Http::withToken($token)->put('https://my.monicahq.com/api/v1/me/contact-list-view', [
'grouping' => 'favourites',
'sort' => 'last-spoke',
'direction' => 'desc',
]);
Response 200
{
"data": {
"type": "user",
"id": "1",
"attributes": {
"first_name": "Michael",
"last_name": "Scott",
"email": "[email protected]",
"email_verified": true,
"locale": "en",
"timezone": "America/New_York",
"time_format": "24",
"date_format": null,
"name_order": "given_first",
"number_format": null,
"contact_list_grouping": "favourites",
"contact_list_sort": "last-spoke",
"contact_list_direction": "desc",
"shows_vault_list": true,
"welcomed_at": 1756252860,
"full_access_offer_dismissed_at": null,
"created_at": 1756252800,
"updated_at": 1756339200
},
"links": {
"self": "https://my.monicahq.com/api/v1/me"
}
}
}

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