Skip to main content
POST
Add a contact to a list
Appends one contact to a saved list. The body is a single contact object, with the same fields and limits as each item of contacts in Create a contact list: 10 phone numbers, 10 custom fields and 2,000 characters of notes at most.
The dialing queue does not change until you refill it. Add all your contacts first, then call Reimport a contact list into the dialing queue once.

Example

Response (201):
The response carries no ID: production returns { "success": true }, although the response schema on this page shows an ID. To find the new contact’s _id, read the list with Get a contact list and search for the contact.

Behavior

  • No duplicate check: each call appends a contact, even one identical to a contact already in the list. A retry after a timeout can add the contact twice, so search the list before retrying.
  • No size check: the list can grow past the 2,000 contacts that Create a contact list accepts in one request.
  • An unknown field fails the request with 400. Phone numbers are stored exactly as sent, so send them in E.164 format.
  • Custom field labels are free text. To match the fields a CRM import creates, reuse an internal_name from List custom field mappings.

Errors

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

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

Body

application/json
account
string

Account or organization identifier, such as an account name or ID from your CRM.

Maximum string length: 500
Example:

"acme-corp"

first_name
string

First name.

Maximum string length: 200
Example:

"Jane"

last_name
string

Last name.

Maximum string length: 200
Example:

"Doe"

linkedin
string

LinkedIn profile URL.

Maximum string length: 500
Example:

"https://www.linkedin.com/in/jane-doe-4b21a3"

email
string

Email address. Not validated.

Maximum string length: 320
website
string

Website URL.

Maximum string length: 500
Example:

"https://acme.com"

notes
string

Free-text notes about the contact, at most 2,000 characters.

Maximum string length: 2000
Example:

"Interested in the enterprise plan. Call back after Q2."

phone_numbers
object[]

Phone numbers, at most 10.

Maximum array length: 10
company
string

Company name.

Maximum string length: 300
Example:

"Acme Corp"

title
string

Job title.

Maximum string length: 300
Example:

"VP of Sales"

priority
number

A number reps can sort and group the dialer queue by.

Example:

1

timezone
string

IANA time zone name, such as America/New_York. Not validated.

Maximum string length: 100
Example:

"America/New_York"

external_relations
object

Free-form object stored and returned with the contact, for references to other systems.

Example:
custom_fields
object[]

Custom fields, at most 10.

Maximum array length: 10

Response

Added. Production returns { "success": true }, not the ID shown in this schema; see the operation description.

A 24-character hexadecimal identifier for a Salesfinity resource. Returned on its own by endpoints whose only result is the id of the record they created or affected.

Pattern: ^[0-9a-fA-F]{24}$
Example:

"507f1f77bcf86cd799439011"