List contact lists

curl --request GET \
  --url https://client-api.salesfinity.co/v1/contact-lists/csv \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://client-api.salesfinity.co/v1/contact-lists/csv', 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/csv",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "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"
	"net/http"
	"io"
)

func main() {

	url := "https://client-api.salesfinity.co/v1/contact-lists/csv"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://client-api.salesfinity.co/v1/contact-lists/csv")

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

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

{
  "data": [
    {
      "_id": "6650c1f2a4b8e93d2c1f0a11",
      "name": "Q2 Outbound Prospects",
      "user": "680edc0d1504192884a148e0",
      "total_contacts": 1250,
      "createdAt": "2026-10-03T14:05:22.481Z",
      "updatedAt": "2026-10-03T15:40:10.002Z"
    }
  ],
  "pagination": {
    "total": 23,
    "page": 1,
    "next": 2
  }
}

{
  "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

List contact lists

Returns the team’s saved contact lists, newest first, without their contacts. It includes every CSV-type list: those created with POST /v1/contact-lists and those uploaded as a CSV file in the dashboard. Lists that come from a connected CRM are not included. total_contacts is the size of the saved list, which can differ from the dialing queue until the list is refilled.

Paginate with page and limit until pagination.next is null. sort takes one field (name, createdAt, updatedAt or total_contacts), with a - prefix for descending. To read a list’s contacts, call GET /v1/contact-lists/csv/{id}.

GET

contact-lists

csv

List contact lists

curl --request GET \
  --url https://client-api.salesfinity.co/v1/contact-lists/csv \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://client-api.salesfinity.co/v1/contact-lists/csv', 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/csv",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "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"
	"net/http"
	"io"
)

func main() {

	url := "https://client-api.salesfinity.co/v1/contact-lists/csv"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://client-api.salesfinity.co/v1/contact-lists/csv")

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

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

{
  "data": [
    {
      "_id": "6650c1f2a4b8e93d2c1f0a11",
      "name": "Q2 Outbound Prospects",
      "user": "680edc0d1504192884a148e0",
      "total_contacts": 1250,
      "createdAt": "2026-10-03T14:05:22.481Z",
      "updatedAt": "2026-10-03T15:40:10.002Z"
    }
  ],
  "pagination": {
    "total": 23,
    "page": 1,
    "next": 2
  }
}

{
  "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"
}

Returns your team’s saved contact lists, newest first, without their contacts. Use it to find a list’s _id, then read the contacts with Get a contact list.

How contact lists work

Every list has two parts:

Part	What it is	Changed by
Saved list	The contacts as you created or edited them. Every endpoint in this group reads or edits it, and its `_id` is the ID they all take.	Create a contact list, Add a contact to a list, Remove a contact from a list, Merge contact lists
Dialing queue	The copy of the contacts the dialer works from.	Filled when the list is created. Refilled from the saved list by Reimport a contact list into the dialing queue, or when a rep imports the list in the dashboard.

Changes to the saved list reach the dialer only when the queue is refilled. Delete a contact list removes both parts. This endpoint returns every CSV-type list: those created through the API and those uploaded as a CSV file in the dashboard. Lists that come from a connected CRM are not included. A list is visible in the dashboard only to the member who owns it, given in user.

Example

curl 'https://client-api.salesfinity.co/v1/contact-lists/csv?search=q2&sort=name&page=1&limit=20' \
  --header 'x-api-key: YOUR_API_KEY'

{
  "data": [
    {
      "_id": "6650c1f2a4b8e93d2c1f0a11",
      "name": "Q2 Outbound Prospects",
      "user": "680edc0d1504192884a148e0",
      "total_contacts": 1250,
      "createdAt": "2026-10-03T14:05:22.481Z",
      "updatedAt": "2026-10-03T15:40:10.002Z"
    }
  ],
  "pagination": {
    "total": 23,
    "page": 1,
    "next": 2
  }
}

Paging, sorting and filtering

Request pages with page until pagination.next is null. limit defaults to 10. Above 100 is treated as 100, and pagination.limit says what was used.
sort takes one field: name, createdAt, updatedAt or total_contacts. Prefix it with - for descending. The default is -createdAt.
search matches part of the list name, ignoring case.
filters[user] keeps the lists one member owns. A value that is not a valid ID returns an empty page instead of an error. curl reads square brackets in a URL as a range, so pass --globoff or send the name as filters%5Buser%5D.
total_contacts counts the saved list. The dialing queue can hold a different number until it is refilled.

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.

Query Parameters

string

Case-insensitive substring match on the list name.

Example:

"outbound"

filters[user]

string

Only lists owned by this user ID. A value that is not a valid ID returns an empty page, not an error.

Example:

"680edc0d1504192884a148e0"

sort

string

One field to sort by: name, createdAt, updatedAt or total_contacts. Prefix with - for descending. Defaults to -createdAt.

Example:

"name"

page

integer

default:1

Page number, starting at 1.

Required range: x >= 1

limit

integer

default:10

Lists per page. Default 10. Above 100 is treated as 100.

Required range: x >= 1

Response

CSV contact lists retrieved successfully

data

object[]

Show child attributes

pagination

object

Show child attributes

Get started

MCP server

MCP reference

MCP use cases

Dialer API

Calls and analytics API

Enrichment API

Sequencer API

List contact lists

How contact lists work

Example

Paging, sorting and filtering

Authorizations

Query Parameters

Response

​How contact lists work

​Example

​Paging, sorting and filtering

Authorizations

Query Parameters

Response

How contact lists work

Example

Paging, sorting and filtering