API v1
v1
View as Markdown

Replace the ways a name is written

PUT /api/v1/vaults/{vault}/contacts/{contact}/name-representations

Send the list of ways the name is written, and say which one the contact is shown under.

The list is sent whole. Left out of the body, the ways of writing the name stay as they are. Sent, the list sent is the list kept: a way of writing the name that carries an id is updated, one without is added, and one left out is deleted. An empty list leaves the contact with no name, which still sorts, searches and draws initials.

Changing a way of writing the name other than the one shown leaves the readable address and the place in the list alone, and the contact is found by the new text at once.

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.

contact string Required

The contact, named either by the readable name it reports as slug or by its id. Both answer. A readable name is rebuilt whenever the record is renamed, and the previous one stops answering, so a client that stores a reference stores the id. A name a record has released is never given to another. The contact has to be in the vault the path names: a contact of yours addressed through the wrong vault answers 404, the same as one that never existed. A contact absorbed by a merge answers 404 here, and the merge endpoints say what became of them.

name_representations array Optional

Every way the name is written, in order, at most 20. Each has the fields listed above except position and is_display, and needs a formatted name or at least one part. An id that is not one of this contact's is refused.

display integer Optional

The position in the list, from 0, of the way the contact is shown under. Required when a list is sent and is not empty. Left out with no list, the way shown stays the same. It cannot be a pronunciation.

nickname string Optional

Up to 255 characters, or null.

maiden_name string Optional

Up to 255 characters, or null.

Returns

The contact object as it now reads. A pronunciation with no system or with a full name, a pronunciation chosen for display, a malformed language or script, the same id sent twice, or an id belonging to another contact answers 422 and changes nothing. A contact belonging to somebody else, or reached through the wrong vault, answers 404.

data object

The 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.

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/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contacts/c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364/name-representations \
-X PUT \
-H "Authorization: Bearer $MONICA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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
},
{
"id": "4b91f2c8-6d03-4e57-a9b1-3c8e0d7f5a26",
"kind": "transliteration",
"language": "ja",
"script": "Kana",
"phonetic_system": null,
"formatted_name": "\u30d1\u30e0\u30fb\u30d3\u30fc\u30ba\u30ea\u30fc",
"prefix": null,
"given_name": null,
"additional_name": null,
"family_name": null,
"suffix": null,
"name_order": null,
"position": 2,
"is_display": false
}
],
"display": 0,
"nickname": "Pammy"
}'
const response = await fetch('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contacts/c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364/name-representations', {
method: 'PUT',
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
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},{"id":"4b91f2c8-6d03-4e57-a9b1-3c8e0d7f5a26","kind":"transliteration","language":"ja","script":"Kana","phonetic_system":null,"formatted_name":"パム・ビーズリー","prefix":null,"given_name":null,"additional_name":null,"family_name":null,"suffix":null,"name_order":null,"position":2,"is_display":false}],
display: 0,
nickname: 'Pammy',
}),
})
const data = await response.json()
$response = Http::withToken($token)->put('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contacts/c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364/name-representations', [
'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], ['id' => '4b91f2c8-6d03-4e57-a9b1-3c8e0d7f5a26', 'kind' => 'transliteration', 'language' => 'ja', 'script' => 'Kana', 'phonetic_system' => null, 'formatted_name' => 'パム・ビーズリー', 'prefix' => null, 'given_name' => null, 'additional_name' => null, 'family_name' => null, 'suffix' => null, 'name_order' => null, 'position' => 2, 'is_display' => false]],
'display' => 0,
'nickname' => 'Pammy',
]);
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
},
{
"id": "4b91f2c8-6d03-4e57-a9b1-3c8e0d7f5a26",
"kind": "transliteration",
"language": "ja",
"script": "Kana",
"phonetic_system": null,
"formatted_name": "パム・ビーズリー",
"prefix": null,
"given_name": null,
"additional_name": null,
"family_name": null,
"suffix": null,
"name_order": null,
"position": 2,
"is_display": false
}
],
"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"
}
}
}

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