# Choose the columns of the people screen

`PUT /api/v1/vaults/{vault}/contact-list-columns`

Choose the columns the people screen of a vault shows, in one call.

This changes what the screen shows and nothing written on any contact. It is written to your account log.

Asking for the same column twice, or for a field no template carries, answers 422 and leaves the columns as they were.

## 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.
- `columns` (array, optional): Every column after the name, in the order the screen shows them. Sent, it replaces whatever the vault held; left out, the columns stay as they are. An empty array puts the defaults back; to show the name alone, send the columns with is_visible false.
- `columns.*.source` (string, required): One of the sources listed above. The same source may appear once, and the same field once.
- `columns.*.section` (uuid, optional): Required when the source is field: the section holding it, which has to be one of yours.
- `columns.*.field_key` (string, optional): Required when the source is field, up to 64 characters. The field has to be carried by the published version of one of your active contact templates, unless the vault already shows it, which lets a column no template supplies any more be kept.
- `columns.*.heading` (string, optional): Up to 255 characters. Empty or null keeps the default heading.
- `columns.*.is_visible` (boolean, required): Whether the screen shows the column.

## Returns

The columns as they now stand. A vault or a section belonging to somebody else answers 404.

- `data` (array): Every column after the name, in the order the screen shows them.
- `data[]` (object): One column.
- `data[].source` (string): What the column shows: nickname, email, phone, birthday, template, last-spoke, added, or field for a field of a template. The name is not a column: it is always shown, always first, and never listed.
- `data[].section` (uuid): For a field, the id of the section holding it, or null. A section can sit in several templates, so one column covers every template placing it, in every version.
- `data[].field_key` (string): For a field, its key inside the section, or null.
- `data[].heading` (string): The heading somebody wrote, or null for the default.
- `data[].default_heading` (string): What the column is called when nobody renamed it, in the language of the request. Read only.
- `data[].is_visible` (boolean): Whether the screen shows the column. A hidden column keeps its place and its heading.
- `data[].is_supplied` (boolean): False when no active contact template carries the field any more. The column is kept, and the list leaves it out until a template carries the field again. Read only.
- `meta` (object): About the columns as a whole.
- `meta.is_default` (boolean): True when the vault never chose, and these are the defaults.

## 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/contact-list-columns \
  -X PUT \
  -H "Authorization: Bearer $MONICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "columns": [
          {
              "source": "field",
              "section": "5e8b2c17-9f04-4d6a-b3e1-7a20c4d95f18",
              "field_key": "company",
              "heading": "Employer",
              "is_visible": true
          },
          {
              "source": "email",
              "heading": null,
              "is_visible": true
          }
      ]
  }'
```

```javascript
const response = await fetch('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contact-list-columns', {
  method: 'PUT',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    columns: [{"source":"field","section":"5e8b2c17-9f04-4d6a-b3e1-7a20c4d95f18","field_key":"company","heading":"Employer","is_visible":true},{"source":"email","heading":null,"is_visible":true}],
  }),
})
const data = await response.json()
```

```php
$response = Http::withToken($token)->put('https://my.monicahq.com/api/v1/vaults/9d4f1c2e-7b3a-4f88-9a2d-6c1e5b0f7a31/contact-list-columns', [
    'columns' => [['source' => 'field', 'section' => '5e8b2c17-9f04-4d6a-b3e1-7a20c4d95f18', 'field_key' => 'company', 'heading' => 'Employer', 'is_visible' => true], ['source' => 'email', 'heading' => null, 'is_visible' => true]],
]);
```

## Response

`200`

```json
{
    "data": [
        {
            "source": "field",
            "section": "5e8b2c17-9f04-4d6a-b3e1-7a20c4d95f18",
            "field_key": "company",
            "heading": "Employer",
            "default_heading": "Company",
            "is_visible": true,
            "is_supplied": true
        },
        {
            "source": "email",
            "section": null,
            "field_key": null,
            "heading": null,
            "default_heading": "Email",
            "is_visible": true,
            "is_supplied": true
        },
        {
            "source": "template",
            "section": null,
            "field_key": null,
            "heading": null,
            "default_heading": "Template",
            "is_visible": false,
            "is_supplied": true
        }
    ],
    "meta": {
        "is_default": false
    }
}
```
