Merge contact lists

curl --request POST \
  --url https://client-api.salesfinity.co/v1/contact-lists/{id}/merge \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "source_list_ids": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ],
  "delete_sources": false
}
'

import requests

url = "https://client-api.salesfinity.co/v1/contact-lists/{id}/merge"

payload = {
    "source_list_ids": ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012"],
    "delete_sources": False
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    source_list_ids: ['507f1f77bcf86cd799439011', '507f1f77bcf86cd799439012'],
    delete_sources: false
  })
};

fetch('https://client-api.salesfinity.co/v1/contact-lists/{id}/merge', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://client-api.salesfinity.co/v1/contact-lists/{id}/merge",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'source_list_ids' => [
        '507f1f77bcf86cd799439011',
        '507f1f77bcf86cd799439012'
    ],
    'delete_sources' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://client-api.salesfinity.co/v1/contact-lists/{id}/merge"

	payload := strings.NewReader("{\n  \"source_list_ids\": [\n    \"507f1f77bcf86cd799439011\",\n    \"507f1f77bcf86cd799439012\"\n  ],\n  \"delete_sources\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://client-api.salesfinity.co/v1/contact-lists/{id}/merge")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"source_list_ids\": [\n    \"507f1f77bcf86cd799439011\",\n    \"507f1f77bcf86cd799439012\"\n  ],\n  \"delete_sources\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://client-api.salesfinity.co/v1/contact-lists/{id}/merge")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"source_list_ids\": [\n    \"507f1f77bcf86cd799439011\",\n    \"507f1f77bcf86cd799439012\"\n  ],\n  \"delete_sources\": false\n}"

response = http.request(request)
puts response.read_body

{
  "_id": "6650c1f2a4b8e93d2c1f0a11",
  "name": "Q2 Outbound Prospects",
  "team": "64f1a2b3c4d5e6f7a8b9c0d1",
  "user": "680edc0d1504192884a148e0",
  "contact_list_id": "6650c1f2a4b8e93d2c1f0a10",
  "contacts": [
    {
      "_id": "6650c1f2a4b8e93d2c1f0a12",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "company": "Acme Corp",
      "title": "VP of Sales",
      "phone_numbers": [
        {
          "_id": "6650c1f2a4b8e93d2c1f0a13",
          "type": "direct",
          "number": "+14155552671"
        }
      ],
      "custom_fields": [
        {
          "_id": "6650c1f2a4b8e93d2c1f0a14",
          "type": "string",
          "label": "Account tier",
          "value": "Enterprise"
        }
      ]
    }
  ],
  "createdAt": "2026-10-03T14:05:22.481Z",
  "updatedAt": "2026-10-03T16:02:47.913Z",
  "__v": 0
}

{
  "message": [
    "source_list_ids must contain at least 1 elements"
  ],
  "error": "Bad Request",
  "statusCode": 400,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Forbidden resource",
  "error": "Forbidden",
  "statusCode": 403,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Target contact list not found",
  "error": "Not Found",
  "statusCode": 404,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Rate limit of 300 requests per minute exceeded. Retry in 12s.",
  "error": "Too Many Requests",
  "statusCode": 429,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Internal server error",
  "error": "Internal Server Error",
  "statusCode": 500,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Contact lists

Merge contact lists

Appends the contacts of each source list to the target’s saved list, keeping each contact’s _id. Contacts are not deduplicated, and the 2,000-contact limit of POST /v1/contact-lists does not apply, so merging is how to build a list larger than one create request allows.

The target’s dialing queue does not change until you refill it with POST /v1/contact-lists/csv/{id}/reimport. With delete_sources: true, each source list and its dialing queue are deleted permanently after the merge.

Source IDs that match no list in your team are skipped without an error. The target’s own ID is ignored if you list it; when that leaves no source, the call returns 404. Not idempotent: retrying a merge that kept its sources appends their contacts again.

Returns the target’s saved list with all of its contacts.

POST

contact-lists

{id}

merge

Merge contact lists

curl --request POST \
  --url https://client-api.salesfinity.co/v1/contact-lists/{id}/merge \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "source_list_ids": [
    "507f1f77bcf86cd799439011",
    "507f1f77bcf86cd799439012"
  ],
  "delete_sources": false
}
'

import requests

url = "https://client-api.salesfinity.co/v1/contact-lists/{id}/merge"

payload = {
    "source_list_ids": ["507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012"],
    "delete_sources": False
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    source_list_ids: ['507f1f77bcf86cd799439011', '507f1f77bcf86cd799439012'],
    delete_sources: false
  })
};

fetch('https://client-api.salesfinity.co/v1/contact-lists/{id}/merge', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://client-api.salesfinity.co/v1/contact-lists/{id}/merge",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'source_list_ids' => [
        '507f1f77bcf86cd799439011',
        '507f1f77bcf86cd799439012'
    ],
    'delete_sources' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://client-api.salesfinity.co/v1/contact-lists/{id}/merge"

	payload := strings.NewReader("{\n  \"source_list_ids\": [\n    \"507f1f77bcf86cd799439011\",\n    \"507f1f77bcf86cd799439012\"\n  ],\n  \"delete_sources\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://client-api.salesfinity.co/v1/contact-lists/{id}/merge")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"source_list_ids\": [\n    \"507f1f77bcf86cd799439011\",\n    \"507f1f77bcf86cd799439012\"\n  ],\n  \"delete_sources\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://client-api.salesfinity.co/v1/contact-lists/{id}/merge")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"source_list_ids\": [\n    \"507f1f77bcf86cd799439011\",\n    \"507f1f77bcf86cd799439012\"\n  ],\n  \"delete_sources\": false\n}"

response = http.request(request)
puts response.read_body

{
  "_id": "6650c1f2a4b8e93d2c1f0a11",
  "name": "Q2 Outbound Prospects",
  "team": "64f1a2b3c4d5e6f7a8b9c0d1",
  "user": "680edc0d1504192884a148e0",
  "contact_list_id": "6650c1f2a4b8e93d2c1f0a10",
  "contacts": [
    {
      "_id": "6650c1f2a4b8e93d2c1f0a12",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "company": "Acme Corp",
      "title": "VP of Sales",
      "phone_numbers": [
        {
          "_id": "6650c1f2a4b8e93d2c1f0a13",
          "type": "direct",
          "number": "+14155552671"
        }
      ],
      "custom_fields": [
        {
          "_id": "6650c1f2a4b8e93d2c1f0a14",
          "type": "string",
          "label": "Account tier",
          "value": "Enterprise"
        }
      ]
    }
  ],
  "createdAt": "2026-10-03T14:05:22.481Z",
  "updatedAt": "2026-10-03T16:02:47.913Z",
  "__v": 0
}

{
  "message": [
    "source_list_ids must contain at least 1 elements"
  ],
  "error": "Bad Request",
  "statusCode": 400,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Forbidden resource",
  "error": "Forbidden",
  "statusCode": 403,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Target contact list not found",
  "error": "Not Found",
  "statusCode": 404,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Rate limit of 300 requests per minute exceeded. Retry in 12s.",
  "error": "Too Many Requests",
  "statusCode": 429,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Internal server error",
  "error": "Internal Server Error",
  "statusCode": 500,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Appends the contacts of up to 20 source lists to a target list, and can delete the sources afterwards. Use it to build a list larger than the 2,000 contacts Create a contact list accepts in one request: create several lists, then merge them into one.

Example

Merge three lists into 6650c1f2a4b8e93d2c1f0a11 and delete them afterwards:

curl https://client-api.salesfinity.co/v1/contact-lists/6650c1f2a4b8e93d2c1f0a11/merge \
  --request POST \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "source_list_ids": [
      "6650c2a0a4b8e93d2c1f0b21",
      "6650c2a0a4b8e93d2c1f0b31",
      "6650c2a0a4b8e93d2c1f0b41"
    ],
    "delete_sources": true
  }'

The response (201) is the target’s saved list with all of its contacts, so it grows with the list. Then refill the target’s dialing queue:

curl https://client-api.salesfinity.co/v1/contact-lists/csv/6650c1f2a4b8e93d2c1f0a11/reimport \
  --request POST \
  --header 'x-api-key: YOUR_API_KEY'

How the merge works

Rule	Detail
Where contacts go	Source contacts are appended after the target’s existing contacts. Each keeps its `_id`.
Duplicates	Not removed. A person in two lists appears twice.
Size	No limit. The 2,000-contact limit applies only to Create a contact list.
Dialing queue	The target’s queue does not change until you call Reimport a contact list into the dialing queue.
`delete_sources: true`	Each source’s saved list and dialing queue are deleted permanently after the merge.
Unknown source IDs	IDs that match no list in your team are skipped without an error.
Target ID in `source_list_ids`	Ignored. If it was the only ID, the call returns 404.

Retrying

Not idempotent. Retrying a merge that kept its sources appends their contacts again. A merge with delete_sources: true that succeeded has already deleted its sources, so retrying it appends nothing.

Errors

Status	When
400	`source_list_ids` is missing, empty, has more than 20 IDs or holds a value that is not an ID, `delete_sources` is not a boolean, or the target `id` is not a valid ID (`Invalid ObjectId format for parameter: id`).
404	No saved list with the target ID in your team, or `source_list_ids` named only the target (`Target contact list not found`).

Authorizations

x-api-key

string

header

required

Team-scoped API key generated in the Salesfinity dashboard under Settings → Connections → API & Webhooks. A missing or invalid key returns HTTP 403.

Path Parameters

string

required

ID of the target saved list. A value that is not a valid ID fails with 400.

Example:

"6650c1f2a4b8e93d2c1f0a11"

Body

application/json

source_list_ids

string[]

required

IDs of the source lists to merge into the target list

Required array length: 1 - 20 elements

Example:

[
  "507f1f77bcf86cd799439011",
  "507f1f77bcf86cd799439012"
]

delete_sources

boolean

default:false

Whether to delete the source lists after merging

Response

Merged. The body is the target's saved list, with all its contacts.

_id

string

required

ID of the saved list.

Example:

"6650c1f2a4b8e93d2c1f0a11"

name

string

required

Name of the list.

Example:

"Q2 Outbound Prospects"

source

enum<string>

required

Not returned by POST /v1/contact-lists/{id}/merge.

Available options:

csv,

hubspot,

salesforce,

manual

user

object

Show child attributes

total_contacts

integer

Not returned by POST /v1/contact-lists/{id}/merge; count contacts instead.

team

string

ID of your team.

Example:

"64f1a2b3c4d5e6f7a8b9c0d1"

contact_list_id

string

ID of the list's dialing queue.

Example:

"6650c1f2a4b8e93d2c1f0a10"

contacts

object[]

Every contact in the saved list after the merge.

Show child attributes

createdAt

string<date-time>

updatedAt

string<date-time>

__v

integer

Internal document version. Ignore it.

Get started

MCP server

MCP reference

MCP use cases

Dialer API

Calls and analytics API

Enrichment API

Sequencer API

Merge contact lists

Example

How the merge works

Retrying

Errors

Authorizations

Path Parameters

Body

Response

​Example

​How the merge works

​Retrying

​Errors

Authorizations

Path Parameters

Body

Response

Example

How the merge works

Retrying

Errors