> ## 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. > Merges up to 10 lemlist companies into one survivor, moving everything attached to the deleted companies onto it. # Merge Companies Merges up to 10 lemlist companies into one. The survivor (`primaryId`) keeps its id and every value it holds; its **empty** fields are filled from the other companies, which are then deleted. A value the survivor already has is never overwritten. Companies are addressed by their lemlist id (`cpn_xxx`). ## What moves to the survivor * Contacts, activities, tasks and list memberships of every deleted company. * When a CRM is connected, the survivor keeps its CRM link, or adopts the first linked company's when it has none, and receives the merged values there. lemlist never merges or deletes anything in the CRM itself: the other companys' CRM records stay in the CRM, unlinked from lemlist. Merge them CRM-side too, or a later CRM import may recreate the duplicate. ## Partial runs — `success: true` does not mean complete The companies are folded into the survivor one at a time and the run **stops at the first failure**. The response is still `200`: `mergedIds` lists what went through, `remainingIds` what still exists — fix the cause and call again with the remaining ids. A failure on the very first fold returns an error instead, and nothing was written. There is no undo. Once merged, the secondary companies are deleted and only the survivor remains. ## OpenAPI ````yaml post /companies/merge 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/merge: post: tags: - Companies summary: Merge Companies description: >- Merges up to 10 lemlist companies into one. The survivor (`primaryId`) keeps its id and every value it holds; its empty fields are filled from the other companies, which are then deleted. Everything attached to a deleted company (contacts, activities, tasks, list memberships) is moved to the survivor. When a CRM is connected, the survivor keeps its CRM link (or adopts the first linked record's when it has none) and receives the merged values there; lemlist never merges or deletes anything in the CRM itself, so the other records' CRM entries stay in the CRM, unlinked from lemlist — merge them CRM-side too, or a CRM import may recreate the duplicate. The companies are folded into the survivor one at a time and the run **stops at the first failure**: `mergedIds` lists what went through, `remainingIds` what still exists. A first-fold failure returns an error instead — nothing was written. **No undo:** deleted companies are gone. requestBody: required: true content: application/json: schema: type: object properties: primaryId: type: string description: The surviving company. A lemlist company id (`cpn_xxx`). example: cpn_A1B2C3D4E5F6G7H8I secondaryIds: type: array items: type: string minItems: 1 maxItems: 9 description: >- The companies folded into the survivor then deleted, 9 at most. A lemlist company id (`cpn_xxx`). Must not contain `primaryId`, and each company is listed once. example: - cpn_J9K8L7M6N5O4P3Q2R - cpn_S1T2U3V4W5X6Y7Z8A required: - primaryId - secondaryIds responses: '200': description: >- Merge run — **`success: true` does not mean complete.** The companies fold one at a time and the run stops at the first failure, so ALWAYS check `remainingIds`: the companies listed there were NOT merged and still exist. Fix the cause and call again with the survivor and the remaining ids. content: application/json: schema: type: object properties: success: type: boolean primaryId: type: string description: ID of the surviving lemlist company. merged: type: boolean description: >- `true` once at least one company was folded into the survivor. mergedIds: type: array items: type: string description: >- IDs of the companies folded into the survivor and deleted, in fold order. remainingIds: type: array items: type: string description: >- IDs of the companies NOT merged because an earlier fold failed. Empty when everything went through. rejectedFields: type: array items: type: string description: >- Fields whose adopted value was refused by a uniqueness rule (kept survivor-side). Only present when it happened. required: - success - primaryId - merged - mergedIds - remainingIds examples: everything merged: value: success: true primaryId: cpn_A1B2C3D4E5F6G7H8I merged: true mergedIds: - cpn_J9K8L7M6N5O4P3Q2R - cpn_S1T2U3V4W5X6Y7Z8A remainingIds: [] stopped at the second fold: value: success: true primaryId: cpn_A1B2C3D4E5F6G7H8I merged: true mergedIds: - cpn_J9K8L7M6N5O4P3Q2R remainingIds: - cpn_S1T2U3V4W5X6Y7Z8A '400': description: >- Invalid request. Possible error codes: `ENTITY_MERGE_INVALID_PAYLOAD` (missing `primaryId` or empty `secondaryIds`), `ENTITY_MERGE_SAME_ENTITY` (`primaryId` among `secondaryIds`, or a company listed twice), `ENTITY_MERGE_TOO_MANY_ENTITIES` (more than 9 `secondaryIds`). content: application/json: example: success: false error: code: ENTITY_MERGE_SAME_ENTITY message: >- A record cannot be merged with itself, and each record is listed once '401': description: The authentication you supplied is incorrect. content: text/plain: example: The authentication you supplied is incorrect '404': description: >- One of the companies was not found (`ENTITY_MERGE_ENTITY_NOT_FOUND`). content: application/json: example: success: false error: code: ENTITY_MERGE_ENTITY_NOT_FOUND message: One of the records was not found '409': description: >- A company is being enriched and cannot be merged yet (`ENTITY_MERGE_ENRICHMENT_IN_PROGRESS`); retry once it finishes. content: application/json: example: success: false error: code: ENTITY_MERGE_ENRICHMENT_IN_PROGRESS message: A record is being enriched, retry once it finishes components: securitySchemes: basicAuth: type: http scheme: basic ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.