Skip to main content

Can I create, update or delete custom fields with the API or MCP?

Manage contact and company fields from a script or an AI assistant: add a field, rename its label, change select options, or remove it, with the same rules as in the app.

Yes. Custom fields on contacts and companies can be created, updated and deleted through the lemlist API, with the same rules as in the app. The lemlist MCP reaches the same endpoints through its Call lemlist API tool, so you can also ask your AI assistant to do it.

This is useful when you set up lemlist by script (for example an agency onboarding a client) or through an AI agent: you don't need to declare each field in the app before writing values into it.


How it works

Create or update a field: POST /fields

  • If no field with that name exists, the field is created and the answer is 201.

  • If a field with that name already exists, it is updated and the answer is 200. The answer lists what changed.

  • Sending the same body twice changes nothing, so a setup script can be run again safely.

  • name is the key you write values to. It must start with a lowercase letter and contain only letters and digits (^[a-z][a-zA-Z0-9]*$).

  • label is the name shown in the app. It is optional and defaults to name.

Field types

All 9 field types are supported: text, multiline text, number, date, URL, select, boolean, phone and user.

Type changes follow the app: any type can become text or multiline text, except phone and user.

A user value written through POST /contacts or POST /companies must be a team member (email or usr_ ID), as in the app.

Select options

Options are managed by value, matched like in the Edit variables window: capital letters and spaces at either end are ignored.

  • upsertOptions adds the options that are missing.

  • renameOptions renames an option. Contacts that hold it get the new value.

  • removeOptions removes an option and clears it on the contacts that hold it.

A select field always keeps at least one option.

Delete a field: DELETE /fields/{entity}/{name}

Deleting a field removes it and clears its value on every contact or company. This can't be undone.

Read fields: GET /fields

GET /fields returns select fields with their options, and user fields as user.


Who can do it

The permissions are the same as in the app:

  • Anyone on the team can create a field.

  • Updating or deleting a field needs the Update contact & companies fields permission.


Exceptions

Can I rename a field's key?

No. name never changes. To change the name shown in the app, update its label. If you need a different key, create a new field.

Why can't I delete this field?

A field can't be deleted while a campaign picks its sender through that field, including deleted campaigns. The API answers 409 FIELD_USED_AS_CAMPAIGN_SENDER. Change the sender setting of those campaigns first.

Which errors can I get?

  • 403 FIELD_PERMISSION_DENIED: you don't have the Update contact & companies fields permission.

  • 409 FIELD_USED_AS_CAMPAIGN_SENDER: a campaign picks its sender through this field.

  • 409 FIELD_CHANGED_RETRY: two option updates arrived at the same time. Send the request again.

  • 400 TYPE_CHANGE_NOT_ALLOWED: this type change is not allowed.


What to do instead

Did this answer your question?