API v1
v1
View as Markdown

List value lists

GET /api/v1/value-lists

List the value lists of your account, each with its choices, so a field offering choices can name the one it takes them from.

A value list is a named set of choices defined once for the account and reused by any number of fields: genders, phone labels, contact categories. The lists are in the order the settings show them, and the choices of each in their own order.

Only the shared lists are here. The choices somebody typed into a single field belong to that field and are not listed.

This endpoint also answers QUERY, with the same parameters sent in the request body. How QUERY works.

Query parameters

Sent as JSON. Anything not listed here is ignored.

page integer Optional default: 1

Which page to answer with.

per_page integer Optional default: 25

How many one page holds, between 1 and 100. A number outside the range is brought back into it rather than refused.

Returns

A page of value lists, and how many there are in all. The lists of another account are never included.

data array

The value lists on this page. An empty list rather than an error when there are none.

data[] object

One value list.

data[].type string

Always value_list.

data[].id integer

The id of the list, which is what value_list_id takes when a field is added or configured.

data[].attributes object

What the list holds.

data[].attributes.name string

What the list is called.

data[].attributes.items array

The choices the list offers, in their order. An empty list when it offers none yet.

data[].attributes.items[] object

One choice.

data[].attributes.items[].id integer

The id of the choice, which is what a field offering this list stores as its value.

data[].attributes.items[].label string

What the choice says.

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 value lists 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.

GET
curl https://my.monicahq.com/api/v1/value-lists \
-H "Authorization: Bearer $MONICA_TOKEN"
const response = await fetch('https://my.monicahq.com/api/v1/value-lists', {
headers: { Authorization: `Bearer ${token}` },
})
const data = await response.json()
$response = Http::withToken($token)->get('https://my.monicahq.com/api/v1/value-lists');
Response 200
{
"data": [
{
"type": "value_list",
"id": 3,
"attributes": {
"name": "Genders",
"items": [
{
"id": 11,
"label": "Woman"
},
{
"id": 12,
"label": "Man"
},
{
"id": 13,
"label": "Non-binary"
}
]
}
}
],
"meta": {
"page": 1,
"per_page": 25,
"total": 1
}
}

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