API v1
v1
View as Markdown

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

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.

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.

PUT
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
}
]
}'
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()
$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
{
"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
}
}

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