Skip to main content
POST
Add and update company
Creates a new company in your CRM, or updates an existing one if a company with the same domain, linkedinUrl, or linkedinUrlSalesNav already exists (upsert). On update, the updateStrategy query parameter decides what the existing record keeps (see below). By default, sent values replace stored ones and empty values are ignored.

Upsert matching

The endpoint matches existing companies by: If a company with the same domain, linkedinUrl, or linkedinUrlSalesNav already exists, the endpoint updates it instead of creating a duplicate. Creating a company requires the “Create companies” permission on the API key’s user, otherwise the request fails with 403 COMPANY_CREATE_NOT_ALLOWED and nothing is written. Updating an existing company does not require it. The error names that user (The user jane@acme.com does not have the permission to create companies); when the API key’s user is no longer in the team, it fails with 403 API_USER_NOT_IN_TEAM instead. Without companyId, name is required together with at least one identifier: domain, linkedinUrl or linkedinUrlSalesNav. A company known only by its LinkedIn page can be created with name and linkedinUrl; a name alone is refused with 400 MISSING_REQUIRED_FIELD. A domain that designates no single company is not stored: a personal email provider (gmail.com) or a platform host (facebook.com, linkedin.com, a bare wordpress.com). The company is still written, without it, and warnings carries a COMPANY_DOMAIN_IGNORED entry naming the domain in params.companyDomain. A site hosted on a site builder keeps its own address (acme.wordpress.com). When companyId is provided, the company is matched by its ID directly. name and the identifiers are not required and are not used for matching (they are stored as data if provided).
companyId can only be used to update an existing company. It cannot be used to create a new company: use name and an identifier for creation.

Update strategy

The updateStrategy query parameter decides what an existing company keeps: null and absent keys never touch a field. Identifiers (name, domain, linkedinUrl, linkedinUrlSalesNav) are never cleared. Under fillEmptyOnly, the owner and the status are kept when set and filled when missing. A new company receives every value sent. Any other value answers 400 INVALID_UPDATE_STRATEGY.
Kept values are reported: warnings carries a FIELDS_KEPT entry with the field names in params.fields. It appears under fillEmptyOnly on a stored value, and under the default when an empty string is ignored on a filled field, never for an identical value.

Linking to a CRM record

Send crmId with the id of a record in your connected CRM to link the company to that record. lemlist links it without searching the CRM, then runs a first sync that follows your field mapping (the CRM wins conflicts by default).
crmId is in closed beta. Unless the CRM ID remap beta is enabled for your team, it is refused like any unknown field, with 400 INVALID_FIELD. It also requires an admin API key.
What happens depends on the company and on who already holds the id:
Several companies can share a domain. The domain then confirms the company holding the id even when the body’s name is another company’s: send companyId (or the LinkedIn URL) when your companies share a domain.
The crmSync block of the response shows the link the company ends up with.
Every check runs before anything is written, so a refused call leaves the company as it was:

Owner assignment

You can assign an owner to the company using the companyOwner field. Accepted formats:
If the provided value does not match a team member (invalid format, unknown email, or unknown user ID), the company is still written and the response carries an OWNER_NOT_FOUND or INVALID_OWNER_FORMAT entry in warnings. On creation, the company defaults to the API key owner; on update, the current owner is unchanged.
On an existing company, updateStrategy decides the owner: Without companyOwner, the owner is never touched.

Authorizations

Authorization
string
header
required

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

Query Parameters

updateStrategy
enum<string>
default:overwriteIgnoreEmpty

What an existing record keeps. overwriteIgnoreEmpty (default): sent values replace stored ones, empty values are ignored. overwrite: an empty string clears the field. fillEmptyOnly: only empty fields are filled, identifiers, links, owner and status kept. A new record receives every value sent. Other values: 400 INVALID_UPDATE_STRATEGY.

Available options:
overwrite,
overwriteIgnoreEmpty,
fillEmptyOnly

Body

application/json
companyId
string

Existing company ID. Updates a specific company by ID, bypassing domain/LinkedIn matching. Can only be used to update an existing company, not to create a new one. When provided, name and the identifiers become optional.

name
string

Company name. Required unless companyId is provided.

domain
string

Company website domain (e.g. lemlist.com). Used as a unique key for upsert matching. Without companyId, at least one identifier is required among domain, linkedinUrl and linkedinUrlSalesNav. A personal email provider or a platform host (gmail.com, facebook.com, linkedin.com, a bare wordpress.com) is not stored: the company is written without it and warnings reports COMPANY_DOMAIN_IGNORED.

linkedinUrl
string

LinkedIn company page URL. Used as an alternative unique key for upsert matching, and accepted as the sole identifier of a new company.

linkedinUrlSalesNav
string

LinkedIn Sales Navigator company URL. Used as an alternative unique key for upsert matching, and accepted as the sole identifier of a new company.

companyOwner
string

Owner of the company. Can be a user ID (e.g. usr_...) or a team member's email address. If the provided value does not match a team member, the company is still written with an OWNER_NOT_FOUND or INVALID_OWNER_FORMAT entry in warnings: the owner defaults to the API key owner on creation and is unchanged on update. On update it replaces the current owner, except under fillEmptyOnly where it is only set when the company has none.

industry
string

Industry sector of the company.

location
string

Geographic location of the company.

size
string

Company size.

specialties
string

Company specialties.

tagline
string

Company tagline.

type
string

Company type.

description
string

Company description.

foundedOn
string

Company founding date.

headquarters
string

Company headquarters location.

picture
string

URL of the company logo or picture.

source
string
default:api

Origin of the company record. Set on creation only and cannot be updated afterwards. Defaults to api.

crmId
string

Closed beta: refused as an unknown field (400 INVALID_FIELD) unless the CRM ID remap beta is enabled for your team. Id of the record of the connected CRM to link the company to: a HubSpot, Pipedrive or Zoho numeric id (send a Zoho id as a string: its 19 digits are too long for a JSON number), an Attio record id, or a Salesforce Account (001…) id of 15 or 18 characters. Requires an admin API key. A new company is created already linked; an existing one has its link moved to this record, and its contacts’ associations follow. An id another company holds updates that company when the body carries its domain, LinkedIn URL or Sales Navigator URL, and is refused otherwise. See the endpoint page for the refusals.

Example:

"123456789"

{key}
any

Any additional key is treated as a custom field. Custom fields must be registered in the team's CRM field registry beforehand.

Response

Existing company updated (upsert matched by domain or LinkedIn URL)

success
boolean
data
object

Same shape as the 201 response, with created: false and updated: true.

warnings
object[]

Non-blocking notices: owner or company not resolved, or FIELDS_KEPT when the update strategy kept values you sent (params.fields names them).