> ## 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 contacts into one survivor, moving everything attached to the deleted contacts onto it. # Merge Contacts Merges up to 10 lemlist contacts into one. The survivor (`primaryId`) keeps its id and every value it holds; its **empty** fields are filled from the other contacts, which are then deleted. A value the survivor already has is never overwritten. **Email addresses** follow the same rule: the survivor keeps its own, a loser's addresses are dropped — unless the survivor has none, in which case it takes the first loser's. Each contact is addressed by its lemlist id (`ctc_xxx`) or by one of its email addresses, like `DELETE /contacts/{idOrEmail}`. The response always carries the resolved `primaryId`. ## What moves to the survivor * Leads in campaigns, activities, tasks, list memberships and inbox conversations of every deleted contact. * When a CRM is connected, the survivor keeps its CRM link, or adopts the first linked contact's when it has none, and receives the merged values there. lemlist never merges or deletes anything in the CRM itself: the other contacts' 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 contacts 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 (typically an enrichment in progress) 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 contacts are deleted and only the survivor remains. ## OpenAPI ````yaml post /contacts/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: /contacts/merge: post: tags: - Contacts summary: Merge Contacts description: >- Merges up to 10 lemlist contacts into one. The survivor (`primaryId`) keeps its id and every value it holds; its empty fields are filled from the other contacts, which are then deleted. Everything attached to a deleted contact (leads in campaigns, activities, tasks, list memberships, inbox conversations) 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 contacts 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. **Email addresses:** the survivor keeps its own; a loser's addresses are dropped, unless the survivor has none (then it takes the first loser's). **No undo:** deleted contacts are gone. requestBody: required: true content: application/json: schema: type: object properties: primaryId: type: string description: >- The surviving contact. A lemlist contact id (`ctc_xxx`) or one of the contact's email addresses. example: ctc_xW8Ou6C03Csv8vatp secondaryIds: type: array items: type: string minItems: 1 maxItems: 9 description: >- The contacts folded into the survivor then deleted, 9 at most. A lemlist contact id (`ctc_xxx`) or one of the contact's email addresses. Must not contain `primaryId`, and each contact is listed once. example: - ctc_bT4Ktq6kbXwWKv2rM - john.doe@acme.com required: - primaryId - secondaryIds responses: '200': description: >- Merge run — **`success: true` does not mean complete.** The contacts fold one at a time and the run stops at the first failure, so ALWAYS check `remainingIds`: the contacts listed there were NOT merged and still exist. Fix the cause (typically an enrichment in progress) 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 contact — resolved from the email when one was given. merged: type: boolean description: >- `true` once at least one contact was folded into the survivor. mergedIds: type: array items: type: string description: >- IDs of the contacts folded into the survivor and deleted, in fold order. remainingIds: type: array items: type: string description: >- IDs of the contacts 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: ctc_xW8Ou6C03Csv8vatp merged: true mergedIds: - ctc_bT4Ktq6kbXwWKv2rM - john.doe@acme.com remainingIds: [] stopped at the second fold: value: success: true primaryId: ctc_xW8Ou6C03Csv8vatp merged: true mergedIds: - ctc_bT4Ktq6kbXwWKv2rM remainingIds: - john.doe@acme.com '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 contact 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 contacts was not found (`ENTITY_MERGE_ENTITY_NOT_FOUND`) — an unknown email counts as a missing contact. content: application/json: example: success: false error: code: ENTITY_MERGE_ENTITY_NOT_FOUND message: One of the records was not found '409': description: >- A contact 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.