Create a contact list
curl --request POST \
--url https://client-api.salesfinity.co/v1/contact-lists \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"name": "Q2 Outbound Prospects",
"user_id": "680edc0d1504192884a148e0",
"contacts": [
{
"account": "acme-corp",
"first_name": "Jane",
"last_name": "Doe",
"linkedin": "https://www.linkedin.com/in/jane-doe-4b21a3",
"email": "[email protected]",
"website": "https://acme.com",
"notes": "Interested in the enterprise plan. Call back after Q2.",
"phone_numbers": [
{
"type": "direct",
"number": "+14155552671",
"country_code": "US",
"extension": "204"
}
],
"company": "Acme Corp",
"title": "VP of Sales",
"priority": 1,
"timezone": "America/New_York",
"external_relations": {
"record_id": "A-1042"
},
"custom_fields": [
{
"type": "string",
"label": "Account tier",
"value": "Enterprise"
}
]
}
]
}
'import requests
url = "https://client-api.salesfinity.co/v1/contact-lists"
payload = {
"name": "Q2 Outbound Prospects",
"user_id": "680edc0d1504192884a148e0",
"contacts": [
{
"account": "acme-corp",
"first_name": "Jane",
"last_name": "Doe",
"linkedin": "https://www.linkedin.com/in/jane-doe-4b21a3",
"email": "[email protected]",
"website": "https://acme.com",
"notes": "Interested in the enterprise plan. Call back after Q2.",
"phone_numbers": [
{
"type": "direct",
"number": "+14155552671",
"country_code": "US",
"extension": "204"
}
],
"company": "Acme Corp",
"title": "VP of Sales",
"priority": 1,
"timezone": "America/New_York",
"external_relations": { "record_id": "A-1042" },
"custom_fields": [
{
"type": "string",
"label": "Account tier",
"value": "Enterprise"
}
]
}
]
}
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({
name: 'Q2 Outbound Prospects',
user_id: '680edc0d1504192884a148e0',
contacts: [
{
account: 'acme-corp',
first_name: 'Jane',
last_name: 'Doe',
linkedin: 'https://www.linkedin.com/in/jane-doe-4b21a3',
email: '[email protected]',
website: 'https://acme.com',
notes: 'Interested in the enterprise plan. Call back after Q2.',
phone_numbers: [{type: 'direct', number: '+14155552671', country_code: 'US', extension: '204'}],
company: 'Acme Corp',
title: 'VP of Sales',
priority: 1,
timezone: 'America/New_York',
external_relations: {record_id: 'A-1042'},
custom_fields: [{type: 'string', label: 'Account tier', value: 'Enterprise'}]
}
]
})
};
fetch('https://client-api.salesfinity.co/v1/contact-lists', 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",
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([
'name' => 'Q2 Outbound Prospects',
'user_id' => '680edc0d1504192884a148e0',
'contacts' => [
[
'account' => 'acme-corp',
'first_name' => 'Jane',
'last_name' => 'Doe',
'linkedin' => 'https://www.linkedin.com/in/jane-doe-4b21a3',
'email' => '[email protected]',
'website' => 'https://acme.com',
'notes' => 'Interested in the enterprise plan. Call back after Q2.',
'phone_numbers' => [
[
'type' => 'direct',
'number' => '+14155552671',
'country_code' => 'US',
'extension' => '204'
]
],
'company' => 'Acme Corp',
'title' => 'VP of Sales',
'priority' => 1,
'timezone' => 'America/New_York',
'external_relations' => [
'record_id' => 'A-1042'
],
'custom_fields' => [
[
'type' => 'string',
'label' => 'Account tier',
'value' => 'Enterprise'
]
]
]
]
]),
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"
payload := strings.NewReader("{\n \"name\": \"Q2 Outbound Prospects\",\n \"user_id\": \"680edc0d1504192884a148e0\",\n \"contacts\": [\n {\n \"account\": \"acme-corp\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"linkedin\": \"https://www.linkedin.com/in/jane-doe-4b21a3\",\n \"email\": \"[email protected]\",\n \"website\": \"https://acme.com\",\n \"notes\": \"Interested in the enterprise plan. Call back after Q2.\",\n \"phone_numbers\": [\n {\n \"type\": \"direct\",\n \"number\": \"+14155552671\",\n \"country_code\": \"US\",\n \"extension\": \"204\"\n }\n ],\n \"company\": \"Acme Corp\",\n \"title\": \"VP of Sales\",\n \"priority\": 1,\n \"timezone\": \"America/New_York\",\n \"external_relations\": {\n \"record_id\": \"A-1042\"\n },\n \"custom_fields\": [\n {\n \"type\": \"string\",\n \"label\": \"Account tier\",\n \"value\": \"Enterprise\"\n }\n ]\n }\n ]\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")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Q2 Outbound Prospects\",\n \"user_id\": \"680edc0d1504192884a148e0\",\n \"contacts\": [\n {\n \"account\": \"acme-corp\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"linkedin\": \"https://www.linkedin.com/in/jane-doe-4b21a3\",\n \"email\": \"[email protected]\",\n \"website\": \"https://acme.com\",\n \"notes\": \"Interested in the enterprise plan. Call back after Q2.\",\n \"phone_numbers\": [\n {\n \"type\": \"direct\",\n \"number\": \"+14155552671\",\n \"country_code\": \"US\",\n \"extension\": \"204\"\n }\n ],\n \"company\": \"Acme Corp\",\n \"title\": \"VP of Sales\",\n \"priority\": 1,\n \"timezone\": \"America/New_York\",\n \"external_relations\": {\n \"record_id\": \"A-1042\"\n },\n \"custom_fields\": [\n {\n \"type\": \"string\",\n \"label\": \"Account tier\",\n \"value\": \"Enterprise\"\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://client-api.salesfinity.co/v1/contact-lists")
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 \"name\": \"Q2 Outbound Prospects\",\n \"user_id\": \"680edc0d1504192884a148e0\",\n \"contacts\": [\n {\n \"account\": \"acme-corp\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"linkedin\": \"https://www.linkedin.com/in/jane-doe-4b21a3\",\n \"email\": \"[email protected]\",\n \"website\": \"https://acme.com\",\n \"notes\": \"Interested in the enterprise plan. Call back after Q2.\",\n \"phone_numbers\": [\n {\n \"type\": \"direct\",\n \"number\": \"+14155552671\",\n \"country_code\": \"US\",\n \"extension\": \"204\"\n }\n ],\n \"company\": \"Acme Corp\",\n \"title\": \"VP of Sales\",\n \"priority\": 1,\n \"timezone\": \"America/New_York\",\n \"external_relations\": {\n \"record_id\": \"A-1042\"\n },\n \"custom_fields\": [\n {\n \"type\": \"string\",\n \"label\": \"Account tier\",\n \"value\": \"Enterprise\"\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"_id": "6650c1f2a4b8e93d2c1f0a11",
"name": "Q2 Outbound Prospects",
"team": "64f1a2b3c4d5e6f7a8b9c0d1",
"user": "680edc0d1504192884a148e0",
"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-03T14:05:22.481Z",
"__v": 0
}{
"message": [
"contacts.0.phone_numbers.0.type must be one of the following values: mobile, direct, office"
],
"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": "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
Create a contact list
Creates a contact list owned by the team member in user_id and fills its dialing queue with the same contacts. The list is visible in the dashboard only to that member.
Send up to 2,000 contacts, or none and add them later with POST /v1/contact-lists/{id}. The response is the saved list with every contact and the _id Salesfinity gave each one. Pass the list’s _id to every other contact-list operation.
Not idempotent: every call creates a new list, so a retry after a timeout can leave two lists with the same name. Before retrying, look for the list with GET /v1/contact-lists/csv?search=....
The body can be up to 10 MB; a larger body is rejected with 413. A field the contact object does not define is rejected with 400.
POST
/
v1
/
contact-lists
Create a contact list
curl --request POST \
--url https://client-api.salesfinity.co/v1/contact-lists \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"name": "Q2 Outbound Prospects",
"user_id": "680edc0d1504192884a148e0",
"contacts": [
{
"account": "acme-corp",
"first_name": "Jane",
"last_name": "Doe",
"linkedin": "https://www.linkedin.com/in/jane-doe-4b21a3",
"email": "[email protected]",
"website": "https://acme.com",
"notes": "Interested in the enterprise plan. Call back after Q2.",
"phone_numbers": [
{
"type": "direct",
"number": "+14155552671",
"country_code": "US",
"extension": "204"
}
],
"company": "Acme Corp",
"title": "VP of Sales",
"priority": 1,
"timezone": "America/New_York",
"external_relations": {
"record_id": "A-1042"
},
"custom_fields": [
{
"type": "string",
"label": "Account tier",
"value": "Enterprise"
}
]
}
]
}
'import requests
url = "https://client-api.salesfinity.co/v1/contact-lists"
payload = {
"name": "Q2 Outbound Prospects",
"user_id": "680edc0d1504192884a148e0",
"contacts": [
{
"account": "acme-corp",
"first_name": "Jane",
"last_name": "Doe",
"linkedin": "https://www.linkedin.com/in/jane-doe-4b21a3",
"email": "[email protected]",
"website": "https://acme.com",
"notes": "Interested in the enterprise plan. Call back after Q2.",
"phone_numbers": [
{
"type": "direct",
"number": "+14155552671",
"country_code": "US",
"extension": "204"
}
],
"company": "Acme Corp",
"title": "VP of Sales",
"priority": 1,
"timezone": "America/New_York",
"external_relations": { "record_id": "A-1042" },
"custom_fields": [
{
"type": "string",
"label": "Account tier",
"value": "Enterprise"
}
]
}
]
}
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({
name: 'Q2 Outbound Prospects',
user_id: '680edc0d1504192884a148e0',
contacts: [
{
account: 'acme-corp',
first_name: 'Jane',
last_name: 'Doe',
linkedin: 'https://www.linkedin.com/in/jane-doe-4b21a3',
email: '[email protected]',
website: 'https://acme.com',
notes: 'Interested in the enterprise plan. Call back after Q2.',
phone_numbers: [{type: 'direct', number: '+14155552671', country_code: 'US', extension: '204'}],
company: 'Acme Corp',
title: 'VP of Sales',
priority: 1,
timezone: 'America/New_York',
external_relations: {record_id: 'A-1042'},
custom_fields: [{type: 'string', label: 'Account tier', value: 'Enterprise'}]
}
]
})
};
fetch('https://client-api.salesfinity.co/v1/contact-lists', 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",
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([
'name' => 'Q2 Outbound Prospects',
'user_id' => '680edc0d1504192884a148e0',
'contacts' => [
[
'account' => 'acme-corp',
'first_name' => 'Jane',
'last_name' => 'Doe',
'linkedin' => 'https://www.linkedin.com/in/jane-doe-4b21a3',
'email' => '[email protected]',
'website' => 'https://acme.com',
'notes' => 'Interested in the enterprise plan. Call back after Q2.',
'phone_numbers' => [
[
'type' => 'direct',
'number' => '+14155552671',
'country_code' => 'US',
'extension' => '204'
]
],
'company' => 'Acme Corp',
'title' => 'VP of Sales',
'priority' => 1,
'timezone' => 'America/New_York',
'external_relations' => [
'record_id' => 'A-1042'
],
'custom_fields' => [
[
'type' => 'string',
'label' => 'Account tier',
'value' => 'Enterprise'
]
]
]
]
]),
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"
payload := strings.NewReader("{\n \"name\": \"Q2 Outbound Prospects\",\n \"user_id\": \"680edc0d1504192884a148e0\",\n \"contacts\": [\n {\n \"account\": \"acme-corp\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"linkedin\": \"https://www.linkedin.com/in/jane-doe-4b21a3\",\n \"email\": \"[email protected]\",\n \"website\": \"https://acme.com\",\n \"notes\": \"Interested in the enterprise plan. Call back after Q2.\",\n \"phone_numbers\": [\n {\n \"type\": \"direct\",\n \"number\": \"+14155552671\",\n \"country_code\": \"US\",\n \"extension\": \"204\"\n }\n ],\n \"company\": \"Acme Corp\",\n \"title\": \"VP of Sales\",\n \"priority\": 1,\n \"timezone\": \"America/New_York\",\n \"external_relations\": {\n \"record_id\": \"A-1042\"\n },\n \"custom_fields\": [\n {\n \"type\": \"string\",\n \"label\": \"Account tier\",\n \"value\": \"Enterprise\"\n }\n ]\n }\n ]\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")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Q2 Outbound Prospects\",\n \"user_id\": \"680edc0d1504192884a148e0\",\n \"contacts\": [\n {\n \"account\": \"acme-corp\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"linkedin\": \"https://www.linkedin.com/in/jane-doe-4b21a3\",\n \"email\": \"[email protected]\",\n \"website\": \"https://acme.com\",\n \"notes\": \"Interested in the enterprise plan. Call back after Q2.\",\n \"phone_numbers\": [\n {\n \"type\": \"direct\",\n \"number\": \"+14155552671\",\n \"country_code\": \"US\",\n \"extension\": \"204\"\n }\n ],\n \"company\": \"Acme Corp\",\n \"title\": \"VP of Sales\",\n \"priority\": 1,\n \"timezone\": \"America/New_York\",\n \"external_relations\": {\n \"record_id\": \"A-1042\"\n },\n \"custom_fields\": [\n {\n \"type\": \"string\",\n \"label\": \"Account tier\",\n \"value\": \"Enterprise\"\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://client-api.salesfinity.co/v1/contact-lists")
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 \"name\": \"Q2 Outbound Prospects\",\n \"user_id\": \"680edc0d1504192884a148e0\",\n \"contacts\": [\n {\n \"account\": \"acme-corp\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\",\n \"linkedin\": \"https://www.linkedin.com/in/jane-doe-4b21a3\",\n \"email\": \"[email protected]\",\n \"website\": \"https://acme.com\",\n \"notes\": \"Interested in the enterprise plan. Call back after Q2.\",\n \"phone_numbers\": [\n {\n \"type\": \"direct\",\n \"number\": \"+14155552671\",\n \"country_code\": \"US\",\n \"extension\": \"204\"\n }\n ],\n \"company\": \"Acme Corp\",\n \"title\": \"VP of Sales\",\n \"priority\": 1,\n \"timezone\": \"America/New_York\",\n \"external_relations\": {\n \"record_id\": \"A-1042\"\n },\n \"custom_fields\": [\n {\n \"type\": \"string\",\n \"label\": \"Account tier\",\n \"value\": \"Enterprise\"\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"_id": "6650c1f2a4b8e93d2c1f0a11",
"name": "Q2 Outbound Prospects",
"team": "64f1a2b3c4d5e6f7a8b9c0d1",
"user": "680edc0d1504192884a148e0",
"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-03T14:05:22.481Z",
"__v": 0
}{
"message": [
"contacts.0.phone_numbers.0.type must be one of the following values: mobile, direct, office"
],
"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": "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"
}Creates a contact list owned by one team member and fills its dialing queue with the same contacts. Send the contacts in the request, or create an empty list and add them with Add a contact to a list.
The owner,
The request schema lists the length limit of every other field. The 2,000-contact limit applies to one request, not to the list: Add a contact to a list and Merge contact lists can grow a list past it. To load more than 2,000 contacts, create several lists and merge them into one.
Response (201), the saved list with each contact as stored:
Keep the list’s
user_id, must be a member of your team: get member IDs from GET /v1/team. Only that member sees the list in the dashboard.
Limits
| Limit | Value | Past the limit |
|---|---|---|
| Contacts per request | 2,000 | 400 |
| List name | 1–100 characters | 400 |
| Phone numbers per contact | 10 | 400 |
| Custom fields per contact | 10 | 400 |
| Notes per contact | 2,000 characters | 400 |
| Request body | 10 MB | 413 |
Example
curl https://client-api.salesfinity.co/v1/contact-lists \
--request POST \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data @list.json
list.json:
{
"name": "Q2 Outbound Prospects",
"user_id": "680edc0d1504192884a148e0",
"contacts": [
{
"first_name": "Jane",
"last_name": "Doe",
"email": "[email protected]",
"company": "Acme Corp",
"title": "VP of Sales",
"phone_numbers": [
{ "type": "direct", "number": "+14155552671" }
],
"custom_fields": [
{ "type": "string", "label": "Account tier", "value": "Enterprise" }
]
}
]
}
{
"_id": "6650c1f2a4b8e93d2c1f0a11",
"name": "Q2 Outbound Prospects",
"team": "64f1a2b3c4d5e6f7a8b9c0d1",
"user": "680edc0d1504192884a148e0",
"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" }
],
"email_views": 0,
"sequence_step": 0
}
],
"createdAt": "2026-10-03T14:05:22.481Z",
"updatedAt": "2026-10-03T14:05:22.481Z",
"__v": 0
}
_id: every other contact-list operation takes it. The response is not wrapped in data.
Before you send
- Use only the fields in the contact schema. An unknown field, such as
phoneinstead ofphone_numbers, fails the whole request with 400 (contacts.0.property phone should not exist). - Phone numbers are stored exactly as sent, without validation or reformatting. Send them in E.164 format, such as
+14155552671. - Custom field labels are free text. To match the fields a CRM import creates, reuse an
internal_namefrom List custom field mappings.
Retrying
Not idempotent: every call creates a new list. If a request times out, look for the list withGET /v1/contact-lists/csv?search=... before you retry, or you can end up with two lists with the same name.
Errors
| Status | When |
|---|---|
| 400 | A field fails validation, an unknown field was sent, or user_id is not a member of your team (User is not a member of this team). message lists each failing field. |
| 413 | The body is larger than 10 MB. |
Authorizations
Team-scoped API key generated in the Salesfinity dashboard under Settings → Connections → API & Webhooks. A missing or invalid key returns HTTP 403.
Body
application/json
Name of the list, 1 to 100 characters. Names need not be unique.
Required string length:
1 - 100Example:
"Q2 Outbound Prospects"
ID of the team member who owns the list. Only that member sees it in the dashboard. A user who is not on your team fails with 400. Get member IDs from GET /v1/team.
Example:
"680edc0d1504192884a148e0"
Contacts to save, at most 2,000 per request. Omit it to create an empty list. POST /v1/contact-lists/{id} and POST /v1/contact-lists/{id}/merge can grow a list past 2,000.
Maximum array length:
2000Show child attributes
Show child attributes
Response
Created. The body is the saved list, with every contact as stored.
A saved contact list as stored, returned by POST /v1/contact-lists.
ID of the saved list. Pass it to every other contact-list operation.
Example:
"6650c1f2a4b8e93d2c1f0a11"
Example:
"Q2 Outbound Prospects"
ID of your team.
Example:
"64f1a2b3c4d5e6f7a8b9c0d1"
ID of the member who owns the list: the user_id you sent.
Example:
"680edc0d1504192884a148e0"
Every contact as stored, each with the _id Salesfinity gave it. Stored contacts also carry two internal counters, email_views and sequence_step, both 0 on a new contact.
Show child attributes
Show child attributes
Internal document version. Ignore it.