# List the records naming a contact

`GET /api/v1/vaults/{vault}/contacts/{contact}/entities`

List the records of any kind, such as an animal, that name one contact in one of their relation fields, by name.

A record is listed when one of its relation fields names the contact, inside a repeating group or not. A value set aside by a change of template does not count. Only records of the contact’s own vault are listed, since a relation never crosses vaults.

This is what the contact’s page shows under Profiles.

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

## 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 its slug or by its id.
- `page` (integer, optional, defaults to 1): Which page to answer with.
- `per_page` (integer, optional, defaults to 25): How many types one page holds, between 1 and 100. A number outside the range is brought back into it rather than refused.

## Returns

A page of entity objects, and how many there are in all. A vault or a contact belonging to somebody else answers 404.

- `data` (array): The records on this page. An empty list rather than an error when there are none.
- `data[]` (object): One record.
- `data[].type` (string): Always entity. 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.name` (string): What the record is called, up to 255 characters. It is how the record is listed and sorted, and it is reduced to plain text when it is written down.
- `data[].attributes.entity_type_id` (uuid): The kind of record it is. It never changes.
- `data[].attributes.initials` (string): The first letter of the first two words of the name, drawn on the generated avatar.
- `data[].attributes.avatar_colour` (string): The background the generated avatar is drawn on. It is picked when the record is written down and kept afterwards.
- `data[].attributes.avatar` (object): The picture standing in for the record, with its id and url, or null when it is drawn as its initials.
- `data[].attributes.is_archived` (boolean): Whether the record was put away. An archived record is still listed.
- `data[].attributes.structure_version_id` (integer): The exact version of the template the record was written on. A record stays on that version until somebody moves it.
- `data[].attributes.template_name` (string): The name of the template that version belongs to.
- `data[].attributes.fields` (array): The values the record holds, in no particular order. A field left empty is not listed.
- `data[].attributes.fields[]` (object): One value.
- `data[].attributes.fields[].field_id` (string): The id of the field, which is the key a value is written under when the record is updated.
- `data[].attributes.fields[].key` (string): How the field is named in an import or an export. It is unique inside its section only.
- `data[].attributes.fields[].label` (string): What the field is called on the record.
- `data[].attributes.fields[].type` (string): The kind of field: text, date, select, address and so on.
- `data[].attributes.fields[].row` (integer): For a field inside a repeating group, the id of the repetition it belongs to, which is the id an update keeps that repetition by. Null otherwise.
- `data[].attributes.fields[].value` (string): The value, written as the page of the record shows it. A file field gives the name of the file. Null when hidden.
- `data[].attributes.fields[].is_hidden` (boolean): Whether the value was held back because the field is sensitive and the key does not hold the sensitive-fields scope.
- `data[].attributes.created_at` (timestamp): When the record was written down, as a count of seconds since 1970.
- `data[].attributes.updated_at` (timestamp): When it last changed, as a count of seconds, or null.
- `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 record in the application, which opens for somebody signed in rather than for a key. It is the link to give a person.
- `meta` (object): Where you are in the collection.
- `meta.page` (integer): The page this is, counting from 1.
- `meta.per_page` (integer): How many one page holds, which is the size that was asked for once it has been brought into the allowed range.
- `meta.total` (integer): How many records there are in all, not how many are on this page.

## 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/schrute-farms/contacts/dwight-schrute/entities \
  -H "Authorization: Bearer $MONICA_TOKEN"
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/schrute-farms/contacts/dwight-schrute/entities', {
  headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/vaults/schrute-farms/contacts/dwight-schrute/entities');
```

## Response

`200`

```json
{
    "data": [
        {
            "type": "entity",
            "id": "9b1e6c42-7a35-4f08-b2d9-5c8e41a7f031",
            "attributes": {
                "name": "Mose’s goat",
                "entity_type_id": "4c2b9f10-5e37-4a6d-8b91-0f7c3d2a8e64",
                "initials": "MG",
                "avatar_colour": "#22c55e",
                "avatar": null,
                "is_archived": false,
                "structure_version_id": 12,
                "template_name": "Basic animal",
                "fields": [
                    {
                        "field_id": "381",
                        "key": "species",
                        "label": "Species",
                        "type": "text",
                        "row": null,
                        "value": "Goat",
                        "is_hidden": false
                    }
                ],
                "created_at": 1758844800,
                "updated_at": 1758844800
            },
            "links": {
                "self": "https://my.monicahq.com/api/v1/vaults/schrute-farms/entities/9b1e6c42-7a35-4f08-b2d9-5c8e41a7f031",
                "web": "https://my.monicahq.com/vaults/schrute-farms/entities/animals/9b1e6c42-7a35-4f08-b2d9-5c8e41a7f031"
            }
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 1
    }
}
```
