API v1
v1
View as Markdown

List the ways a name is written

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

Retrieve every way the current name of a contact is written, and which one it is shown under.

김민지, Kim Min-ji and 金敏智 are three ways of writing one name, not three names. Former names and nicknames are not here.

This endpoint also answers QUERY, with the same parameters sent in the request body. How QUERY works.

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

Returns

The list, possibly empty. A contact belonging to somebody else, or reached through the wrong vault, answers 404.

data array

Every way the name is written, in order.

data[] object

One way of writing the name.

data[].id uuid

The id of this way of writing the name. Send it back to keep it when the list is replaced.

data[].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[].language string

A BCP 47 language tag such as ko or ja, or null.

data[].script string

An ISO 15924 script code such as Hang, Hani or Latn, or null.

data[].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[].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[].prefix string

Up to 50 characters, or null.

data[].given_name string

Up to 255 characters, or null.

data[].additional_name string

Other given names, up to 255 characters, or null.

data[].family_name string

Up to 255 characters, or null.

data[].suffix string

Up to 50 characters, or null.

data[].name_order string

Either given_first or family_first, or null to leave it to the reader.

data[].position integer

Where it stands in the list, from 1.

data[].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.

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/c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364/name-representations \
-H "Authorization: Bearer $MONICA_TOKEN"
const response = await fetch('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contacts/c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364/name-representations', {
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/c4a1f7b2-8e36-4d59-b0a7-2f5c9d81e364/name-representations');
Response 200
{
"data": [
{
"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
}
]
}

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