> ## Documentation Index > Fetch the complete documentation index at: https://developer.lemlist.com/llms.txt > Use this file to discover all available pages before exploring further. > Creates a new company or updates an existing one based on domain or LinkedIn URL. # Add and update company export const SnippetObjectReference = ({objectName, objectPath = null}) => { const lowerCaseObjectName = objectName.toLowerCase(); if (lowerCaseObjectName === 'lead' || lowerCaseObjectName === 'leads') { return This endpoint uses the {objectName} object. Make sure to also check the {lowerCaseObjectName === 'lead' ? 'Contact' : 'Lead'} object to understand the distinction between the two. ; } return This endpoint uses the {objectName} object. ; }; 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: | Identifier | Description | | - | - | | `companyId` | Existing company ID — updates a specific company directly, bypassing domain/LinkedIn matching | | `domain` | Company website domain (e.g. `lemlist.com`) — primary unique key | | `linkedinUrl` | LinkedIn company page URL — alternative unique key | | `linkedinUrlSalesNav` | LinkedIn Sales Navigator company URL — alternative unique key | If a company with the same `domain`, `linkedinUrl`, or `linkedinUrlSalesNav` already exists, the endpoint updates it instead of creating a duplicate. 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: | Value | Stored value | Empty string sent | | - | - | - | | `overwriteIgnoreEmpty` (default) | Replaced | Ignored | | `overwrite` | Replaced | Cleared | | `fillEmptyOnly` | Kept | Ignored | `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`. ```bash theme={"theme":"dracula"} curl -X POST "https://api.lemlist.com/api/companies?updateStrategy=fillEmptyOnly" \ -u ":YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "Acme Inc", "domain": "acme.com", "industry": "Retail"}' ``` 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. ```json theme={"theme":"dracula"} { "success": true, "data": { "_id": "cpn_2aB3cD4eF5gH6iJ7k", "industry": "Software", "location": "Lyon", "created": false, "updated": true }, "warnings": [ { "code": "FIELDS_KEPT", "message": "Fields kept: the record already holds a different value, left unchanged by the update strategy", "params": { "fields": ["industry"] } } ] } ``` ## Owner assignment You can assign an owner to the company using the `companyOwner` field. Accepted formats: | Format | Example | | - | - | | User ID | `usr_2aB3cD4eF5gH6iJ7k` | | Team member email | `john@yourcompany.com` | 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: | Strategy | Current owner set | No current owner | | - | - | - | | `overwriteIgnoreEmpty` (default) and `overwrite` | Replaced by `companyOwner` | Set to `companyOwner` | | `fillEmptyOnly` | Kept, reported as `ownerId` under `warnings` (`FIELDS_KEPT`) | Set to `companyOwner` | Without `companyOwner`, the owner is never touched. ## OpenAPI ````yaml post /companies openapi: 3.0.0 info: title: lemlist API version: 1.0.0 description: >- Welcome to the lemlist Developer Documentation. lemlist is very customizable and open. You'll find on this page all the API and integration you can do with lemlist. # Rate Limit lemlist's API rate limits requests in order to prevent abuse and overload of our services. Rate limits are applied on all routes and per API key performing the request. The rate limits are **20** requests per **2** seconds. The response provides any information you may need about it: | Header | Description | | --- | --- | | Retry-After | The number of seconds in which you can retry | | X-RateLimit-Limit | The maximum requests in that time | | X-RateLimit-Remaining | The number of remaining requests you can make | | X-RateLimit-Reset | The date when the rate limit will reset | _Example of values for the rate limit headers_ ``` json { "Retry-After": 2, "X-RateLimit-Limit": 20, "X-RateLimit-Remaining": 7, "X-RateLimit-Reset" : "Tue Feb 16 2021 09:02:42 GMT+0100 (Central European Standard Time)" } ``` # Definitions ## Team A team is the entity of lemlist that can handle users and billing. ## Credits Credits are the coins a team uses to enrich emails, LinkedIn URLs, etc. via the enrich route. Each enrichment feature needs a certain amount of credits to run. ## User You use a user account to connect to lemlist and send messages via the connected emails or LinkedIn account. ## Campaign A campaign is the entity to automate outreach. A campaign has multiple sequences composed of steps. ## Lead A lead is a person that you try to contact via a campaign. ## Activity An activity is the history of all the steps. ## Unsubscribe An unsubscribe occurs when a person decides they don't want to receive emails from you anymore. # Authentication All API routes use the dedicated subdomain `api.lemlist.com`. lemlist uses API keys to allow access to the API. You can get your lemlist API key at our [integration page](https://app.lemlist.com/settings/integrations). You need to add the `Authorization` header using the `Basic` authentication type. `login:password` **where the login is always empty and the password is the API key**. ⚠️ **Don't forget to add the semicolon (**`:`**) before your API key in curl command.** > To authorize, use this code: ``` shell curl https://api.lemlist.com/api/team \ --user ":YourApiKey" ``` **Make sure to replace** **`YourApiKey`** **with your API key.** # Give feedback If you want to report a bug, ask for data, or share with us a use case, please fill this [form](https://lemlist.typeform.com/to/mfVlkyGf). It will help us centralize your needs! servers: - url: https://api.lemlist.com/api security: - basicAuth: [] tags: - name: Enrichment Providers description: >- The data providers lemlist can call to find an email or a phone. Internal providers are paid with lemlist credits and always available. External providers run on your own account: connect one by saving its API key, and it becomes available to your waterfalls. `GET /enrichments/providers` is the catalog of provider ids accepted by the waterfall endpoints. - name: Enrichment Waterfalls description: >- Control which data providers lemlist calls when enriching a contact, and in which order. A waterfall is an ordered list of providers for one enrichment `type` (`email` or `phone`). Providers are tried one after the other until one returns a result. Every team has exactly one default waterfall per type (`isDefault: true`). While its `editor` is `lemlist` it follows the lemlist behaviour: providers you connected with your own API key are tried first, then internal providers in a random order. Once a team member edits its provider list, `editor` becomes that user's id and the list is followed as is; resetting it hands it back to `lemlist`. Custom waterfalls (`isDefault: false`) carry `conditions` on the contact being enriched, keyed by contact property; every key present must match. When a contact is enriched, lemlist runs a single waterfall: the custom waterfall of the requested type whose conditions match the contact, or the default waterfall when none does. If several match, the one with the most condition keys wins, then the most recently updated. Only that waterfall runs; when it finds nothing, the enrichment ends without falling back to another one. paths: /companies: post: tags: - Companies summary: Add and update company description: >- Creates a new company or updates an existing one (upsert). If a company with the same domain, LinkedIn URL, or Sales Navigator URL already exists, it is updated as the `updateStrategy` query parameter says (by default, sent values replace stored ones and empty values are ignored). You can target an existing company directly by providing `companyId`, bypassing domain/LinkedIn matching, in which case `name` and the identifiers become optional. Without `companyId`, `name` is required together with at least one identifier: `domain`, `linkedinUrl` or `linkedinUrlSalesNav`. parameters: - name: updateStrategy in: query required: false description: >- 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`. example: fillEmptyOnly schema: type: string enum: - overwrite - overwriteIgnoreEmpty - fillEmptyOnly default: overwriteIgnoreEmpty requestBody: required: true content: application/json: schema: type: object properties: companyId: type: string description: >- 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: type: string description: Company name. Required unless `companyId` is provided. domain: type: string description: >- 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: type: string description: >- LinkedIn company page URL. Used as an alternative unique key for upsert matching, and accepted as the sole identifier of a new company. linkedinUrlSalesNav: type: string description: >- 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: type: string description: >- 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: type: string description: Industry sector of the company. location: type: string description: Geographic location of the company. size: type: string description: Company size. specialties: type: string description: Company specialties. tagline: type: string description: Company tagline. type: type: string description: Company type. description: type: string description: Company description. foundedOn: type: string description: Company founding date. headquarters: type: string description: Company headquarters location. picture: type: string description: URL of the company logo or picture. source: type: string description: >- Origin of the company record. Set on creation only and cannot be updated afterwards. Defaults to `api`. default: api additionalProperties: description: >- Any additional key is treated as a custom field. Custom fields must be registered in the team's CRM field registry beforehand. example: name: Acme Corp domain: acme.com linkedinUrl: https://linkedin.com/company/acme industry: Technology location: San Francisco, CA responses: '200': description: Existing company updated (upsert matched by domain or LinkedIn URL) content: application/json: schema: type: object properties: success: type: boolean data: type: object description: >- Same shape as the 201 response, with `created: false` and `updated: true`. warnings: type: array description: >- Non-blocking notices: owner or company not resolved, or `FIELDS_KEPT` when the update strategy kept values you sent (`params.fields` names them). items: type: object properties: code: type: string description: >- `OWNER_NOT_FOUND` or `INVALID_OWNER_FORMAT` (`companyOwner` matches no team member); `FIELDS_KEPT` (values the update strategy kept); `COMPANY_DOMAIN_IGNORED` (`domain` is a personal email provider or a platform host such as `gmail.com` or a `facebook.com` page: the company is written without it, `params.companyDomain` names it). message: type: string params: type: object additionalProperties: anyOf: - type: string - type: array items: type: string description: >- Details: the input echoed back, or `fields` for `FIELDS_KEPT`. example: success: true data: _id: cpn_gG7PsmZFpEAnpMCHO teamId: tea_8QvkOiBfPdb2ZRhHi domain: acme.com fields: name: Acme Corp industry: Technology location: San Francisco, CA ownerId: usr_ahfFktBBHUIxbVG5P source: api createdAt: '2025-10-28T00:40:37.917Z' createdBy: usr_ahfFktBBHUIxbVG5P created: false updated: true '201': description: Company created successfully content: application/json: schema: type: object properties: success: type: boolean data: type: object properties: _id: type: string description: Unique company identifier teamId: type: string description: Team ID domain: type: string description: Company domain linkedinUrl: type: string description: LinkedIn URL fields: type: object description: >- Key/value fields (name, picture, industry, location, custom fields, etc.) additionalProperties: true ownerId: type: string description: Owner user ID source: type: string description: Record origin createdAt: type: string format: date-time description: Creation timestamp createdBy: type: string description: User ID who created the record created: type: boolean description: >- `true` when a new company was created, `false` when an existing company was updated. updated: type: boolean description: >- Present and set to `true` only when an existing company was updated (i.e. `created` is `false`). warnings: type: array description: >- Non-blocking notices: owner or company not resolved, or `FIELDS_KEPT` when the update strategy kept values you sent (`params.fields` names them). items: type: object properties: code: type: string description: >- `OWNER_NOT_FOUND` or `INVALID_OWNER_FORMAT` (`companyOwner` matches no team member); `FIELDS_KEPT` (values the update strategy kept); `COMPANY_DOMAIN_IGNORED` (`domain` is a personal email provider or a platform host such as `gmail.com` or a `facebook.com` page: the company is written without it, `params.companyDomain` names it). message: type: string params: type: object additionalProperties: anyOf: - type: string - type: array items: type: string description: >- Details: the input echoed back, or `fields` for `FIELDS_KEPT`. example: success: true data: _id: cpn_gG7PsmZFpEAnpMCHO teamId: tea_8QvkOiBfPdb2ZRhHi domain: acme.com linkedinUrl: https://www.linkedin.com/company/acme fields: name: Acme Corp industry: Technology location: San Francisco, CA ownerId: usr_ahfFktBBHUIxbVG5P source: api createdAt: '2025-10-28T00:40:37.917Z' createdBy: usr_ahfFktBBHUIxbVG5P created: true '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean error: type: object properties: code: type: string description: >- Error code: `MISSING_REQUIRED_FIELD`, `INVALID_COMPANY_ID`, `INVALID_DOMAIN`, `INVALID_LINKEDIN_URL`, `INVALID_FIELD`, `INVALID_USER_FIELD_FORMAT`, `USER_FIELD_NOT_FOUND`, `COMPANY_VALIDATION_FAILED`, or `INVALID_UPDATE_STRATEGY`. message: type: string example: success: false error: code: MISSING_REQUIRED_FIELD message: 'A required field is missing: name' '401': description: The authentication you supplied is incorrect content: text/plain: example: The authentication you supplied is incorrect '404': description: >- No company of the team matches `companyId` (`COMPANY_NOT_FOUND_BY_ID`). content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' examples: not-found: value: success: false error: code: COMPANY_NOT_FOUND_BY_ID message: No company found with id '409': description: >- A domain, LinkedIn or Sales Navigator URL already belongs to another company (`COMPANY_IDENTIFIER_CONFLICT`); retrying as is fails again. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' examples: conflict: value: success: false error: code: COMPANY_IDENTIFIER_CONFLICT message: >- An identifier (domain, linkedinUrl or salesnavUrl) already belongs to another company components: schemas: ApiErrorEnvelope: type: object description: Error envelope of the contact and company endpoints. properties: success: type: boolean example: false error: type: object properties: code: type: string description: Machine-readable error code, stable across releases. message: type: string description: Human-readable explanation. required: - code - message required: - success - error securitySchemes: basicAuth: type: http scheme: basic ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.