# 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

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

## Request

```sh
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"
  }'
```

```javascript
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()
```

```php
$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`

```json
{
    "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"
        }
    }
}
```
