Lists#

The methods in this section create and delete lists, change their fields and manage records: add, read, update and delete them. For example, your website can keep a "Coffee shop menu" list up to date, and the bot shows it to people.

How a list is structured#

A list has two parts:

• The schema — the list's name and its fields. The methods on the Lists and fields page work with it. Method names call it exactly that: getListSchema, createListSchema.
• Records — the rows of the list with field values. The methods on the Records page work with them.

Lists belong to a project. A list can be created in a project or in a bot — in that case it also goes to the project of that bot. The API gives access to all lists in the projects owned by the key holder: both those created in bots and those created directly in the project.

Identifiers#

The slug is the field's name in templates: the value is stored in the record under it, and the bot's blocks read it by the same name. Fields created in your account get it automatically; through the API you set it yourself.

Field types#

The type is set in the type parameter when the field is created and cannot be changed later.

An empty field comes back as null.

Date and time#

A time without a time zone is treated as UTC: "2026-10-15 14:30" is saved as 14:30 UTC. To send local time, add the offset: "2026-10-15T14:30:00-05:00". A date field does not cut off the time: if you send a date with a time, the time is kept.

Money#

The currency is set on the field when the field is created (currency) and is not sent with records. It is a three-letter ISO 4217 code: USD, EUR, GBP. In createListSchema the currency can be omitted — then it is USD; in addListSchemaField it is required. An unknown code — 422.

Send amounts in main units — dollars, not cents. An amount is rounded to the currency's decimal places (two for the dollar and the euro), halves rounded up: 0.295 is saved as 0.30.

Files and images#

The value of a file or image field is an object. Through the API you can only store a link to a file that is available on the internet:

{
  "url": "https://example.com/menu/cappuccino.jpg",
  "storage": "url",
  "name": "cappuccino.jpg",
  "type": "image"
}

Warning

Without "storage": "url", or with a link of another kind (not http/https), the value is silently not saved — the field ends up null, and there is no error.

Other keys (such as uuid or path) are ignored: the field stores only the external link, and the response returns it exactly as you sent it. A link to a file in the platform's storage — the kind that responses contain for files uploaded in your account — can only be stored within your own account; a link to another account's file is not saved, and the field ends up null. If you send updateListItem the file that is already in the record, for example a whole record from getListItems, it stays as it was.

In responses, a file is described by an object with the keys type, mime_type, created_at, name, size, storage, caption, meta (width, height, duration, codec) and url. Links to files uploaded in your account are temporary: download the file right away or request the record again.

Contact and bot#

contact and bot fields take an ID. The contact must belong to your bot and the bot must be yours, otherwise the response is 403. An ID that does not exist fails validation — 422.

Besides the value of the field itself, the record gets the service keys contact_id or bot_id — the filter in getListItems works on them. If a list has several such fields, they hold the value of the last one.

Field settings#

Important

By default, a field created through the API is required — unlike in your account. If a field may stay empty, send "is_required": false.

Limits#

• Up to 5000 lists per project.
• From 1 to 30 fields when a list is created.
• List and field names — up to 255 characters.
• Service field names cannot be used: id, _id, contact, contact_id, bot, bot_id, user, user_id, project, project_id, data, schema_id, created_at, updated_at, deleted_at and any name starting with __. For such a slug the API responds with 422 and the text "The slug is reserved.".

General rules — the key, request rate, error codes — are described on the API page.

Methods#