Skip to main content
POST
Add Custom Variables on Leads
To add custom fields, you can add as many as you want in the body of your request with the desired value for these new fields.
The purpose of this endpoint is first and foremost to create new variables, even though we have to give them specific values on a specific lead. That’s why you’ll get errors if you give variable names that already exist on a lead.By default, lemlist includes several variables related to leads: email, firstName, lastName, picture, phone, linkedinUrl, companyName, companyDomain, and icebreaker.Beware, you cannot add a new variable with the same name as an existing variable (default or custom).
Company fields — companyName, companyDomain, companyIndustry, any company-prefixed key — are written on the company record the lead is linked to, the same record every other lead linked to it reads, not on that lead alone. The response says so: warnings carries a company-fields-write-company-record entry naming those keys in params.fields. It is informational, your request went through. To edit a company on purpose, use Upsert Company.
A write that would create a company not yet in lemlist requires the “Create companies” permission on the API key’s user, otherwise it fails with 403 COMPANY_CREATE_NOT_ALLOWED and nothing is written. On a lead with no linked contact, a write that would create one requires the “Create contacts” permission on the API key’s user, otherwise it fails with 403 CONTACT_CREATE_NOT_ALLOWED and nothing is written. The error names that user (The user jane@acme.com does not have the permission to create contacts [CONTACT_CREATE_NOT_ALLOWED]). When the API key’s user is no longer in the team, it fails with 403 API_USER_NOT_IN_TEAM instead (The user jane@acme.com is no longer in this team: ask a current member to create a new API key or reconnect [API_USER_NOT_IN_TEAM]).

Authorizations

Authorization
string
header
required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Path Parameters

leadId
string
required

The unique identifier of the lead

Query Parameters

customField1
string

Example custom variable

customField2
string

Example custom variable

customField3
string

Example custom variable

Response

Success

ok
boolean
Example:

true

warnings
object[]

Optional warnings, never a failure — the request went through. They tell you what happened to the company part: written, or skipped and why. See code.