lemlist Companies API

openapi: 3.2.0
info:
  title: Lemlist Companies API
  version: 1.0.0
  description: 'Operations tagged Companies across 2 of this provider''s published API definitions: lemlist-openapi-v1-legacy.json, lemlist-openapi-v2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.lemlist.com/api
tags:
- name: Companies
paths:
  /companies:
    parameters: []
    get:
      summary: Retrieve Companies
      tags:
      - Companies
      parameters:
      - name: page
        in: query
        required: false
        description: (Optional) Page to show
        example: '1'
        schema:
          type: integer
      - name: sortBy
        in: query
        required: false
        description: '(Optional): The field by which to sort the schedules. Currently, only "createdAt" is supported'
        example: createdAt
        schema:
          type: string
      - name: sortOrder
        in: query
        required: false
        description: '(Optional): The sort direction. Use "desc" for descending order; any other value (or omission) will sort in ascending order'
        example: desc
        schema:
          type: string
      - name: search
        in: query
        required: false
        description: '(Optional): Search by company name, case insensitive'
        example: lemlist
        schema:
          type: string
      - name: fields
        in: query
        required: false
        description: "(Optional): Returns selected fields, returns all fields if empty, each field is separated by a coma. \n"
        example: _id,fields.name,domain
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: (Optional) Number of companies to retrieve. 100 per default ( and 100 max ).
        example: '10'
        schema:
          type: integer
      responses:
        '200':
          description: Success
      operationId: getCompanies
      x-operation-id-source: derived
    post:
      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 will be updated with the provided non-empty fields. Null or empty values are ignored during updates to preserve existing data. You can target an existing company directly by providing `companyId`, bypassing domain/LinkedIn matching — in that case `name` and `domain` become optional.
      tags:
      - Companies
      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 `domain` 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. Required unless `companyId` is provided.
                linkedinUrl:
                  type: string
                  description: LinkedIn company page URL. Used as an alternative unique key for upsert matching.
                linkedinUrlSalesNav:
                  type: string
                  description: LinkedIn Sales Navigator company URL. Used as an alternative unique key for upsert matching.
                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 owner defaults to the API key owner.
                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:
        '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: Optional warnings (e.g. owner resolution issues).
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
              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
        '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`.'
              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
        '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`, `COMPANY_NOT_FOUND_BY_ID`, `INVALID_DOMAIN`, `INVALID_LINKEDIN_URL`, or `INVALID_FIELD`.'
                      message:
                        type: string
              example:
                success: false
                error:
                  code: MISSING_REQUIRED_FIELD
                  message: 'Missing required field: name'
        '401':
          description: The authentication you supplied is incorrect
          content:
            text/plain:
              example: The authentication you supplied is incorrect
      parameters: []
      operationId: postCompanies
      x-operation-id-source: derived
    servers:
    - url: https://api.lemlist.com/api
  /companies/{companyId}/notes:
    parameters:
    - name: companyId
      in: path
      required: true
      example: '{{companyId}}'
      schema:
        type: string
    post:
      summary: Create company note
      tags:
      - Companies
      parameters: []
      responses:
        '200':
          description: Success
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                note:
                  type: string
            example:
              note: Note created from the Api !
      operationId: postCompaniesByCompanyIdNotes
      x-operation-id-source: derived
    get:
      summary: Retrieve company notes
      tags:
      - Companies
      parameters:
      - name: limit
        in: query
        required: false
        description: (Optional) Number of notes to retrieve. 100 per default ( and 100 max ).
        example: '2'
        schema:
          type: integer
      - name: page
        in: query
        required: false
        description: (Optional) Page to show
        example: '1'
        schema:
          type: integer
      - name: sortBy
        in: query
        required: false
        description: '(Optional): The field by which to sort the schedules. Currently, only "createdAt" is supported'
        example: createdAt
        schema:
          type: string
      - name: sortOrder
        in: query
        required: false
        description: '(Optional): The sort direction. Use "desc" for descending order; any other value (or omission) will sort in ascending order'
        example: desc
        schema:
          type: string
      responses:
        '200':
          description: Success
      operationId: getCompaniesByCompanyIdNotes
      x-operation-id-source: derived
    servers:
    - url: https://api.lemlist.com/api
  /companies/{companyId}:
    delete:
      summary: Delete Company
      description: 'Deletes a lemlist company. Refuses by default when contacts are still attached — pass `force=true` to detach them (the `companyId` field is unset on each contact) before deleting the company.


        **No CRM-side propagation:** only the lemlist record is removed. Designed for the contact-to-company remapping workflow: after reassigning the contacts of a duplicate company to the canonical one (via `POST /contacts/{idOrEmail}`), call this endpoint to drop the now-empty duplicate.'
      tags:
      - Companies
      parameters:
      - name: companyId
        in: path
        required: true
        description: The lemlist company ID to delete.
        example: cpn_A1B2C3D4E5F6G7H8I
        schema:
          type: string
          pattern: ^cpn_[a-zA-Z0-9]+$
      - name: force
        in: query
        required: false
        description: When `true`, detaches contacts attached to this company (unsets their `companyId`) before deleting it. When omitted or `false`, the request fails with `400 COMPANY_HAS_CONTACTS` if any contact is still attached.
        example: 'true'
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Company deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  deletedCompanyId:
                    type: string
                    description: ID of the deleted lemlist company.
                  unlinkedContacts:
                    type: integer
                    description: Number of contacts whose `companyId` was unset before deletion. Only present when `force=true`.
                required:
                - success
                - deletedCompanyId
              examples:
                no contacts attached:
                  value:
                    success: true
                    deletedCompanyId: cpn_A1B2C3D4E5F6G7H8I
                force=true with attached contacts:
                  value:
                    success: true
                    deletedCompanyId: cpn_A1B2C3D4E5F6G7H8I
                    unlinkedContacts: 3
        '400':
          description: 'Invalid request. Possible error codes: `INVALID_COMPANY_ID` (malformed ID), `COMPANY_HAS_CONTACTS` (contacts still attached and `force` not set).'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      contactCount:
                        type: integer
                        description: Only on `COMPANY_HAS_CONTACTS` — how many contacts are still attached.
              example:
                success: false
                error:
                  code: COMPANY_HAS_CONTACTS
                  message: Company still has contacts attached. Pass ?force=true to detach them before deletion. (3 contacts attached)
                  contactCount: 3
        '401':
          description: The authentication you supplied is incorrect.
          content:
            text/plain:
              example: The authentication you supplied is incorrect
        '404':
          description: Company not found (`COMPANY_NOT_FOUND_BY_ID`).
          content:
            application/json:
              example:
                success: false
                error:
                  code: COMPANY_NOT_FOUND_BY_ID
                  message: Company not found by ID
        '405':
          description: Method not allowed.
      security:
      - basicAuth: []
      operationId: deleteCompaniesByCompanyId
      x-operation-id-source: derived
    servers:
    - url: https://api.lemlist.com/api
components:
  schemas:
    CompanyNote:
      type: object
      description: A text note attached to a company record to store information.
      properties:
        _id:
          type: string
          description: Unique note identifier
        teamId:
          type: string
          description: Team ID that owns the company
        companyId:
          type: string
          description: Parent company ID
        note:
          type: string
          description: Note text content
        type:
          type: string
          description: Type of note or activity (e.g., 'annotated')
        userId:
          type: string
          description: ID of the user who created the note
        sendUserId:
          type: string
          description: ID of the sending user if applicable
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
    FieldRejection:
      type: object
      description: A value lemlist refused to write on a Contact or Company, with the reason why. Surfaced under `fieldRejections[]` on those objects; filter a list endpoint to only flagged records via the `fieldRejectionReason` query param.
      properties:
        field:
          type: string
          description: The record field the rejected value targeted (e.g. `emails`, `linkedinUrl`, `domain`).
        reason:
          type: string
          description: Why the value was rejected, prefixed by its origin — `enrichment_*` (raised while enriching) or `crm_sync_*` (raised during CRM sync). Same values accepted by the `fieldRejectionReason` query param.
        source:
          type: string
          description: Where the rejection came from — an enrichment source (`lemrich`) or a CRM provider (`hubspot`, `salesforce`, `pipedrive`).
        conflictingRecordId:
          type: string
          description: For duplicate reasons, the id of the record that already holds the value — use it to merge or remap before resolving the duplicate. Omitted for non-duplicate reasons.
        rejectedValue:
          type: string
          description: The value that was refused.
        rejectedAt:
          type: string
          format: date-time
          description: When the rejection was recorded.
    Company:
      type: object
      description: An organization record in your CRM.
      properties:
        _id:
          type: string
          description: Unique company identifier
        name:
          type: string
          description: Company name (may also be present under fields.name)
        domain:
          type: string
          description: Website domain
        industry:
          type: string
          description: Industry sector
        size:
          type: string
          description: Company size
        location:
          type: string
          description: Geographic location
        fields:
          type: object
          description: Flexible key/value fields of the company (e.g., name, picture, industry, location, size, foundedOn)
          additionalProperties: true
        createdBy:
          type: string
          description: User ID who created the company
        ownerId:
          type: string
          description: User ID of the owner of the company
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        fieldRejections:
          type: array
          description: Values lemlist refused to write on this company, each with its reason. Empty when none. Filter the list endpoint to only flagged companies via `GET /companies?fieldRejectionReason=...`.
          items:
            $ref: '#/components/schemas/FieldRejection'
        crmSync:
          type:
          - object
          - 'null'
          description: CRM sync status for the company, resolved against the team's active CRM provider (Hubspot, Salesforce, or Pipedrive). Only present when a CRM is connected. Use this block to monitor sync state and resolve duplicates (e.g. via `GET /companies?crmSyncStatus=unique_index_error_company`).
          properties:
            provider:
              type: string
              enum:
              - hubspot
              - salesforce
              - pipedrive
              description: Active CRM provider for the team.
            crmRecordId:
              type:
              - string
              - 'null'
              description: Identifier of the company record on the CRM side. `null` when the lemlist company has not been synced yet.
            syncDisabled:
              type: boolean
              description: When `true`, automatic sync is paused for this company.
            errors:
              type: array
              description: List of recent sync errors. Empty when the company is synced cleanly.
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: Coarse error category (e.g. `CONNECT_FAILED`, `CREATE_FAILED`, `UPDATE_FAILED`).
                  reason:
                    type: string
                    description: Specific error reason. Matches the lowercase form accepted by the `crmSyncStatus` query param (e.g. `UNIQUE_INDEX_ERROR_COMPANY`, `PROPERTY_DOESNT_EXIST`, `REQUIRED_FIELD_MISSING`).
                  raisedAt:
                    type: string
                    format: date-time
                    description: Timestamp when the error was last raised.
                  metadata:
                    type: object
                    additionalProperties: true
                    description: Extra context. For `UNIQUE_INDEX_ERROR_COMPANY`, contains `alreadyExistingCompanyId` — the lemlist company that already occupies the conflicting CRM record. Use it to remap contacts onto the right lemlist company before deleting the duplicate.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-refined-from:
- lemlist-openapi-v1-legacy.json
- lemlist-openapi-v2.json