Get a contact list

curl --request GET \
  --url https://client-api.salesfinity.co/v1/contact-lists/csv/{id} \
  --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/{id}', 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/{id}",
  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/{id}"

	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/{id}")

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",
    "contacts": [
      {
        "_id": "6650c1f2a4b8e93d2c1f0a12",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "[email protected]",
        "company": "Acme Corp",
        "title": "VP of Sales",
        "account": "acme-corp",
        "linkedin": "https://www.linkedin.com/in/jane-doe-4b21a3",
        "website": "https://acme.com",
        "notes": "Interested in the enterprise plan. Call back after Q2.",
        "phone_numbers": [
          {
            "_id": "6650c1f2a4b8e93d2c1f0a13",
            "type": "direct",
            "number": "+14155552671"
          }
        ],
        "priority": 1,
        "timezone": "America/New_York",
        "external_relations": {
          "record_id": "A-1042"
        },
        "custom_fields": [
          {
            "_id": "6650c1f2a4b8e93d2c1f0a14",
            "type": "string",
            "label": "Account tier",
            "value": "Enterprise"
          }
        ]
      }
    ]
  },
  "pagination": {
    "total": 1250,
    "page": 1,
    "next": 2
  }
}

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

{
  "message": "CSV 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

Get a contact list

Returns one saved list and a page of its contacts. These are the saved contacts; the dialing queue can differ until you refill it with POST /v1/contact-lists/csv/{id}/reimport.

search keeps contacts whose first name, last name, email, company or title contains the text, ignoring case. sort orders contacts by any one contact field: numbers numerically, everything else as text. page and limit (default 50) paginate the contacts; pagination.total counts the contacts that match search. Without sort, contacts come back in the order they were added.

Each contact’s _id is what DELETE /v1/contact-lists/{id}/contacts/{contactId} takes.

GET

contact-lists

csv

{id}

Get a contact list

curl --request GET \
  --url https://client-api.salesfinity.co/v1/contact-lists/csv/{id} \
  --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/{id}', 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/{id}",
  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/{id}"

	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/{id}")

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",
    "contacts": [
      {
        "_id": "6650c1f2a4b8e93d2c1f0a12",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "[email protected]",
        "company": "Acme Corp",
        "title": "VP of Sales",
        "account": "acme-corp",
        "linkedin": "https://www.linkedin.com/in/jane-doe-4b21a3",
        "website": "https://acme.com",
        "notes": "Interested in the enterprise plan. Call back after Q2.",
        "phone_numbers": [
          {
            "_id": "6650c1f2a4b8e93d2c1f0a13",
            "type": "direct",
            "number": "+14155552671"
          }
        ],
        "priority": 1,
        "timezone": "America/New_York",
        "external_relations": {
          "record_id": "A-1042"
        },
        "custom_fields": [
          {
            "_id": "6650c1f2a4b8e93d2c1f0a14",
            "type": "string",
            "label": "Account tier",
            "value": "Enterprise"
          }
        ]
      }
    ]
  },
  "pagination": {
    "total": 1250,
    "page": 1,
    "next": 2
  }
}

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

{
  "message": "CSV 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"
}

Returns one saved list and a page of its contacts. Take the id from Create a contact list or List contact lists. These are the saved contacts. The dialing queue can differ until you refill it with Reimport a contact list into the dialing queue.

Example

curl 'https://client-api.salesfinity.co/v1/contact-lists/csv/6650c1f2a4b8e93d2c1f0a11?sort=-company&limit=50' \
  --header 'x-api-key: YOUR_API_KEY'

{
  "data": {
    "_id": "6650c1f2a4b8e93d2c1f0a11",
    "name": "Q2 Outbound Prospects",
    "user": "680edc0d1504192884a148e0",
    "contacts": [
      {
        "_id": "6650c1f2a4b8e93d2c1f0a12",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "[email protected]",
        "company": "Acme Corp",
        "title": "VP of Sales",
        "account": "acme-corp",
        "linkedin": "https://www.linkedin.com/in/jane-doe-4b21a3",
        "website": "https://acme.com",
        "notes": "Interested in the enterprise plan. Call back after Q2.",
        "phone_numbers": [
          { "_id": "6650c1f2a4b8e93d2c1f0a13", "type": "direct", "number": "+14155552671" }
        ],
        "priority": 1,
        "timezone": "America/New_York",
        "external_relations": { "record_id": "A-1042" },
        "custom_fields": [
          { "_id": "6650c1f2a4b8e93d2c1f0a14", "type": "string", "label": "Account tier", "value": "Enterprise" }
        ]
      }
    ]
  },
  "pagination": {
    "total": 1250,
    "page": 1,
    "next": 2
  }
}

Searching, sorting and paging contacts

search keeps contacts whose first name, last name, email, company or title contains the text, ignoring case. pagination.total then counts the matches.
sort takes one contact field, such as first_name, company or priority, with a - prefix for descending. Numbers sort numerically and everything else sorts as text. Without sort, contacts come back in the order they were added.
limit defaults to 50 contacts per page. Above 100 is treated as 100, and pagination.limit says what was used. Request pages with page until pagination.next is null.

Each contact’s _id is the contactId that Remove a contact from a list takes. The _id values inside phone_numbers and custom_fields are regenerated on every request of this endpoint; no endpoint takes them.

Errors

Status	When
404	No saved list with this ID in your team (`CSV contact list not found`).
400	The `id` is not a valid ID (`Invalid ObjectId format for parameter: id`).

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 saved list, from POST /v1/contact-lists or GET /v1/contact-lists/csv. A value that is not a valid ID fails with 400.

Example:

"6650c1f2a4b8e93d2c1f0a11"

Query Parameters

string

Keeps contacts whose first name, last name, email, company or title contains this text, ignoring case.

Example:

"acme"

sort

string

One contact field to sort by, such as first_name, company or priority. Prefix with - for descending.

Example:

"-company"

page

integer

default:1

Page of contacts, starting at 1.

Required range: x >= 1

limit

integer

default:50

Contacts per page. Default 50. Above 100 is treated as 100.

Required range: x >= 1

Response

CSV contact list 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

Get a contact list

Example

Searching, sorting and paging contacts

Errors

Authorizations

Path Parameters

Query Parameters

Response

​Example

​Searching, sorting and paging contacts

​Errors

Authorizations

Path Parameters

Query Parameters

Response

Example

Searching, sorting and paging contacts

Errors