# 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](https://my.monicahq.com/docs/api/query-method).

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

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

## Request

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

```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', {
  headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
```

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

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