Skip to main content
POST
/
v1
/
contact-lists
cURL
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": "<string>",
  "user_id": "<string>",
  "contacts": [
    {
      "account": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "linkedin": "<string>",
      "email": "<string>",
      "website": "<string>",
      "notes": "<string>",
      "phone_numbers": [
        {
          "number": "<string>",
          "country_code": "<string>",
          "extension": "<string>"
        }
      ],
      "company": "<string>",
      "title": "<string>",
      "priority": 123,
      "timezone": "<string>",
      "external_relations": {},
      "custom_fields": [
        {
          "label": "<string>",
          "value": "<unknown>"
        }
      ]
    }
  ]
}
'
{}
Creates a new contact list for the team. Contacts are optional and can be added later via the Add Contact endpoint.

​
Limits

ResourceLimit
Contacts per list2,000
List name1–100 characters
Notes per contact2,000 characters
Phone numbers per contact10
Custom fields per contact10
Request payload size10MB

​
Request Body

FieldTypeRequiredDescription
namestringYesName of the contact list (1–100 characters)
user_idstringYesID of the team member who owns this list. Must be a valid member of the team. Get this from Get Team.
contactsarrayNoArray of contact objects (max 2,000). See Add Contact for the contact object schema.

​
Example Request

{
  "name": "Q2 Outbound Prospects",
  "user_id": "680edc0d1504192884a148e0",
  "contacts": [
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "company": "Acme Corp",
      "title": "VP of Sales",
      "phone_numbers": [
        {
          "type": "direct",
          "number": "+14155552671"
        }
      ]
    }
  ]
}

​
Example Request (empty list)

{
  "name": "Q2 Outbound Prospects",
  "user_id": "680edc0d1504192884a148e0"
}

​
Response (201)

Returns the created contact list object with its _id. Use this ID for all subsequent operations (adding contacts, merging, deleting, etc.).

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
name
string
required

Name of the contact list

Required string length: 1 - 100
​
user_id
string
required

ID of the team member who owns this list

​
contacts
object[]

Array of contacts (optional, max 2,000)

Maximum array length: 2000

Response

Contact list created successfully

The response is of type object.