API Reference - Salesfinity Docs

The Salesfinity API is a JSON-over-HTTPS REST API for the Salesfinity parallel dialer. Use it to manage contact lists, run outbound sequences end to end, read call logs and AI call scores, pull team and SDR analytics, work with notes, and enrich phone numbers and email addresses. Everything on this page is plain text, so a person skimming, a search crawler, and an autonomous agent all get the same answer without running any JavaScript.

At a glance


Base URL	`https://client-api.salesfinity.co`
Authentication	`x-api-key` request header
Media type	`application/json` on requests and responses
OpenAPI description	`/api-reference/openapi.json` (OpenAPI 3.0.1)
Developer portal	Keys, quickstarts, testing, client patterns
Support	[email protected] · support.salesfinity.ai

Quickstart

Generate a key in the Salesfinity dashboard under Settings → Connections & API, then confirm it works by reading the team it belongs to. Every key is scoped to exactly one team, and every response is filtered to that team.

curl https://client-api.salesfinity.co/v1/team \
  --header 'x-api-key: YOUR_API_KEY'

A successful call returns the team name and its members, each with a user record, a status, and a license. If the key is missing or wrong you get an HTTP 403 with a JSON body rather than an HTML error page — see Errors. Once the key works, the usual next step is to list the team’s contact lists and then read one:

# Page 1 of the team's CSV contact lists
curl 'https://client-api.salesfinity.co/v1/contact-lists/csv?page=1&limit=10' \
  --header 'x-api-key: YOUR_API_KEY'

# One list, including the contacts inside it
curl 'https://client-api.salesfinity.co/v1/contact-lists/csv/CONTACT_LIST_ID' \
  --header 'x-api-key: YOUR_API_KEY'

Authentication

Every endpoint requires an API key in the x-api-key header. There is no OAuth flow, no bearer token, and no unauthenticated endpoint. Keys are long-lived until you revoke them in the dashboard. A missing, malformed, revoked, or wrong-team key returns HTTP 403 Forbidden, not 401. That is worth encoding in client code, because the conventional “retry auth on 401” branch will never fire against this API.

{ "message": "Forbidden resource", "error": "Forbidden", "statusCode": 403 }

Because a key is team-scoped, requesting a resource that belongs to a different team returns 404 Not Found rather than 403 — the API does not confirm that records outside your team exist. There is no separate sandbox host. See the developer portal for how to test against live data safely.

Conventions

Concern	Convention
Media type	`application/json` on requests and responses
Pagination	`page` (1-based) and `limit`. The `limit` default varies by endpoint — 10 on most lists, 50 for contacts inside a list, 100 for sequences — and is capped at 100 where a cap applies
Sorting	`sort=field` ascending, `sort=-field` descending, for example `sort=-createdAt`
Filtering	Bracketed query parameters such as `filters[start_date]`, `filters[user_ids]`, `filters[disposition_ids]`
IDs	24-character hexadecimal strings
Errors	Always JSON, always `{ message, error, statusCode }`

Errors

Every error response, on every endpoint and every status code, uses the same JSON envelope:

Field	Type	Description
`message`	string or string array	Human-readable description. An array with one entry per invalid field when request validation fails.
`error`	string	Stable HTTP reason phrase, for example `Forbidden` or `Not Found`. Branch on this rather than on `message`.
`statusCode`	integer	HTTP status code, repeated in the body so it survives transports that drop it.

Status	`error`	When it happens	What to do
400	`Bad Request`	Body or query parameters failed validation	Read the `message` array; each entry names a field
402	`Payment Required`	Team has no enrichment credits left	Top up credits, then retry
403	`Forbidden`	API key missing, malformed, revoked, or for another team	Fix the `x-api-key` header
404	`Not Found`	Unknown route, or a resource another team owns	Check the path and the ID
429	`Too Many Requests`	Client is being throttled	Retry with exponential backoff and jitter
500	`Internal Server Error`	Fault on the Salesfinity side	Retry with backoff, then contact support

Branch on error or statusCode rather than on message. Retry 429 and 5xx with exponential backoff; 400, 402, 403, and 404 will not succeed on an identical retry. The full envelope, per-status examples, and recovery steps are on the Errors page.

Webhooks

Webhook subscriptions are created and managed inside the Salesfinity application, not through this API. Configure them in the dashboard under Settings → Connections & API; there are no webhook endpoints to call. The enrichment endpoints are the exception: they accept a per-request callback_url rather than a standing subscription — see Enrich Email and Enrich Phone.

What you can do with the API

The REST API exposes 114 operations across 21 groups. Every operation has a unique operationId, a description, typed parameters, and a JSON response schema in the OpenAPI description.

Group	Operations	What it covers
Contact Lists	8	Create, read, merge, and delete CSV contact lists; add and remove the contacts inside them; push a list into the dialing queue
Notes	5	Attach freeform notes to a person or company, list them, edit or delete your own, and toggle pins
Snoozed Contacts	5	Read and manage contacts held out of the dialing queue, by ID or LinkedIn username
Enrichment	5	Start an asynchronous phone or email lookup, poll its result, and check credit balance
Analytics	3	Aggregated call metrics with growth rates, plus breakdowns by contact list and by SDR
Call Logs	2	Paginated call history with filtering and sorting, and single-call lookup
Scored Calls	2	AI-scored calls with per-facet scoring and coaching recommendations
Dispositions	2	Default and custom call outcomes configured for the team
CRM Sequences	2	Sequence names observed on the team’s call logs, from an external CRM. Not the Sequencer — see below
Sequencer Sequences	12	Build, configure, enable and duplicate cadences, add contacts, and read analytics
Sequencer Steps	6	The ordered steps that make up a cadence
Sequencer Templates	6	Reusable email subjects and bodies
Sequencer Enrollments	16	Contacts inside a sequence, their timelines, and the verbs that move them
Sequencer Enrolment Runs	5	Preview a batch, then enrol up to 5000 in the background
Sequencer Tasks	17	The rep task queue, including call tasks and one-off tasks
Sequencer Suppression	4	The team do-not-contact list
Sequencer Policies	8	Rules of engagement: what may be enrolled, and what happens at each step
Sequencer Settings	3	Sequencer settings and sending mailboxes, read-only
Teams	1	The team that owns the API key, with members, statuses, and licenses
Follow-up Tasks	1	Follow-up tasks created from call outcomes
Custom Fields	1	Custom field mappings configured for the team

Complete endpoint index

Every operation in the API, with its HTTP method, path, and reference page. This table is generated from the OpenAPI description, so it is always in sync with the spec.

Contact Lists

Method	Path	Operation	Description
`POST`	`/v1/contact-lists`	Create a contact list	Creates a new contact list
`POST`	`/v1/contact-lists/{id}`	Add a contact to a list	Add a contact to an existing list
`DELETE`	`/v1/contact-lists/{id}/contacts/{contactId}`	Remove a contact from a list	Remove a contact from a contact list
`POST`	`/v1/contact-lists/{id}/merge`	Merge contact lists	Merges contacts from one or more source lists into the target list
`GET`	`/v1/contact-lists/csv`	List contact lists	Returns all CSV contact lists for the team with filtering, sorting, and pagination
`DELETE`	`/v1/contact-lists/csv/{id}`	Delete a contact list	Delete a contact list
`GET`	`/v1/contact-lists/csv/{id}`	Get a contact list	Returns a single CSV contact list with all its contacts
`POST`	`/v1/contact-lists/csv/{id}/reimport`	Reimport a contact list into the dialing queue	Reimport contacts from CSV

Teams

Method	Path	Operation	Description
`GET`	`/v1/team`	Get the current team	Returns team information

Dispositions

Method	Path	Operation	Description
`GET`	`/v1/dispositions`	List dispositions	Returns all dispositions available for the team, including default and custom dispositions
`GET`	`/v1/dispositions/{id}`	Get a disposition	Get a specific disposition by its internal ID

Sequences

Method	Path	Operation	Description
`GET`	`/v1/sequences`	List sequences	Returns all sequences used in call logs for the team
`GET`	`/v1/sequences/{id}`	Get a sequence	Get a specific sequence by ID

Call Logs

Method	Path	Operation	Description
`GET`	`/v1/call-log`	List call logs	Retrieves a paginated list of call logs with filtering and sorting support
`GET`	`/v1/call-log/{id}`	Get a call log	Get a call log by ID

Analytics

Method	Path	Operation	Description
`GET`	`/v1/analytics/list-performance`	List call performance by contact list	Returns call metrics grouped by contact list with pagination
`GET`	`/v1/analytics/overview`	Get analytics overview	Returns aggregated analytics metrics with growth rates compared to the previous period
`GET`	`/v1/analytics/sdr-performance`	List call performance by SDR	Returns call metrics grouped by SDR (user) with pagination

Snoozed Contacts

Method	Path	Operation	Description
`GET`	`/v1/snoozed-contacts`	List snoozed contacts	Returns all snoozed contacts for the team with pagination and filtering
`DELETE`	`/v1/snoozed-contacts/{id}`	Delete a snoozed contact	Delete a snoozed contact
`GET`	`/v1/snoozed-contacts/{id}`	Get a snoozed contact	Get a snoozed contact by ID
`PUT`	`/v1/snoozed-contacts/{id}`	Update a snoozed contact	Update a snoozed contact
`GET`	`/v1/snoozed-contacts/by-linkedin/{username}`	Get a snoozed contact by LinkedIn username	Get a snoozed contact by LinkedIn username

Follow-up Tasks

Method	Path	Operation	Description
`GET`	`/v1/follow-up`	List follow-up tasks	Returns all follow-up tasks for the team with pagination

Custom Fields

Method	Path	Operation	Description
`GET`	`/v1/custom-fields`	List custom fields	Returns all custom field mappings configured for the team

Scored Calls

Method	Path	Operation	Description
`GET`	`/v1/scored-calls`	List scored calls	Retrieves a paginated list of AI-scored calls with detailed insights, scoring facets, lead qualification, and…
`GET`	`/v1/scored-calls/{id}`	Get a scored call	Retrieves a single scored call by its ID with full AI-generated insight

Notes

Method	Path	Operation	Description
`GET`	`/v2/notes`	List notes	Looks up the person or company by the provided identifiers and returns the notes attached to it
`POST`	`/v2/notes`	Create a note	Creates a note attached to a person (Contact) or company (Company), identified by domain identifiers rather…
`DELETE`	`/v2/notes/{id}`	Delete a note	Deletes an existing note
`PATCH`	`/v2/notes/{id}`	Update a note	Updates the content of an existing note
`POST`	`/v2/notes/{id}/pin`	Toggle a note pin	Toggles whether a note is pinned

Enrichment

Method	Path	Operation	Description
`GET`	`/v1/api/enrichment/credits`	Get enrichment credit balance	Returns the current enrichment credit balance for the team that owns the API key
`POST`	`/v1/api/enrichment/email`	Start an email enrichment	Starts an asynchronous lookup of a work or personal email address for a LinkedIn profile
`GET`	`/v1/api/enrichment/email/{id}`	Get an email enrichment result	Returns the current state of an email enrichment request
`POST`	`/v1/api/enrichment/phone`	Start a phone enrichment	Starts an asynchronous lookup of mobile and direct-dial phone numbers for a LinkedIn profile
`GET`	`/v1/api/enrichment/phone/{id}`	Get a phone enrichment result	Returns the current state of a phone enrichment request

Sequencer Sequences

Method	Path	Operation	Description
`GET`	`/v2/sequencer/sequences`	List sequences	Returns the team’s sequences, newest first
`POST`	`/v2/sequencer/sequences`	Create a sequence	Creates the cadence shell
`DELETE`	`/v2/sequencer/sequences/{id}`	Delete a sequence	Permanent, and refused while any enrollment is still live
`GET`	`/v2/sequencer/sequences/{id}`	Get a sequence	Returns one sequence with its counters
`PATCH`	`/v2/sequencer/sequences/{id}`	Update a sequence	Changes settings, not structure — steps have their own endpoints
`GET`	`/v2/sequencer/sequences/{id}/analytics`	Get sequence analytics	Counts of enrollments by state, plus the sequence’s engagement counters (delivered, opened, clicked, replied,…
`GET`	`/v2/sequencer/sequences/{id}/analytics/people`	List the people behind an engagement metric	The drill-down behind one analytics tile — who opened, who replied, who bounced
`POST`	`/v2/sequencer/sequences/{id}/contacts`	Add contacts to a sequence	Enrols up to 500 prospects synchronously
`POST`	`/v2/sequencer/sequences/{id}/disable`	Disable a sequence	Pauses every live enrollment and returns how many were paused
`POST`	`/v2/sequencer/sequences/{id}/duplicate`	Duplicate a sequence	Copies the sequence and its steps
`POST`	`/v2/sequencer/sequences/{id}/enable`	Enable a sequence	Starts the cadence running and activates everyone already parked in it, returning how many moved
`GET`	`/v2/sequencer/sequences/{id}/enrollment-attempts`	List enrolment refusals	Who was not added to this sequence, and why: blocked by a rule, on the suppression list, already enrolled, over…

Sequencer Steps

Method	Path	Operation	Description
`GET`	`/v2/sequencer/sequences/{sequence_id}/steps`	List steps	The cadence, in order
`POST`	`/v2/sequencer/sequences/{sequence_id}/steps`	Add a step	Appends a step to the cadence
`DELETE`	`/v2/sequencer/sequences/{sequence_id}/steps/{step_id}`	Delete a step	Refused with 409 while any enrollment is live, for the same reason as reordering
`GET`	`/v2/sequencer/sequences/{sequence_id}/steps/{step_id}`	Get a step	One step of a cadence, with its delay, type and templates
`PATCH`	`/v2/sequencer/sequences/{sequence_id}/steps/{step_id}`	Update a step	Changes a step in place
`PUT`	`/v2/sequencer/sequences/{sequence_id}/steps/reorder`	Reorder steps	Send every step id in the order you want

Sequencer Templates

Method	Path	Operation	Description
`GET`	`/v2/sequencer/templates`	List email templates	The team’s reusable email bodies
`POST`	`/v2/sequencer/templates`	Create an email template	A reusable subject and HTML body
`DELETE`	`/v2/sequencer/templates/{id}`	Delete an email template	Archive instead if any live step still references it — a step left without a usable template cannot send
`GET`	`/v2/sequencer/templates/{id}`	Get an email template	One template, with its body and engagement counters
`PATCH`	`/v2/sequencer/templates/{id}`	Update an email template	Edits apply to every step already pointing at this template, including sequences that are currently running
`POST`	`/v2/sequencer/templates/{id}/preview`	Preview a rendered template	Renders the subject and body with merge fields resolved

Sequencer Enrollments

Method	Path	Operation	Description
`GET`	`/v2/sequencer/enrollments`	List enrollments	One row per contact per sequence: where they are in the cadence, who owns them, and how they have engaged
`GET`	`/v2/sequencer/enrollments/{id}`	Get an enrollment	One contact’s position in one sequence: state, current step, when the next step is due, owner, and engagement…
`POST`	`/v2/sequencer/enrollments/{id}/approve`	Approve a held enrollment	Releases an enrollment a rule held for approval, and the cadence starts
`GET`	`/v2/sequencer/enrollments/{id}/events`	List enrollment events	The prospect timeline, newest first: enrolment, sends, opens, replies, task activity, rule decisions and approvals
`POST`	`/v2/sequencer/enrollments/{id}/finish`	Un-enrol a contact	This is how you remove someone from a sequence
`POST`	`/v2/sequencer/enrollments/{id}/pause`	Pause an enrollment	Holds the cadence
`POST`	`/v2/sequencer/enrollments/{id}/reassign`	Reassign an enrollment	Hands the contact, and optionally their open tasks, to another rep
`POST`	`/v2/sequencer/enrollments/{id}/reject`	Reject a held enrollment	Refuses a held enrollment
`POST`	`/v2/sequencer/enrollments/{id}/resume`	Resume an enrollment	Lifts a pause
`POST`	`/v2/sequencer/enrollments/{id}/retry`	Retry a failed enrollment	The only way out of the `failed` state
`POST`	`/v2/sequencer/enrollments/bulk/account`	Finish or pause everyone at an account	Acts on every contact at one company — the “we just booked a meeting there, stop emailing the rest” case
`POST`	`/v2/sequencer/enrollments/bulk/approve`	Approve held enrollments	Releases enrollments a rule held for approval
`POST`	`/v2/sequencer/enrollments/bulk/finish`	Finish enrollments in bulk	The bulk form of un-enrolling
`POST`	`/v2/sequencer/enrollments/bulk/move`	Move enrollments to another sequence	Enrols in the target first and finishes the original only if that succeeded, so nobody is left out of both
`POST`	`/v2/sequencer/enrollments/bulk/reassign`	Reassign enrollments in bulk	Hands up to 500 enrollments to another rep
`POST`	`/v2/sequencer/enrollments/bulk/reject`	Reject held enrollments	Refuses enrollments a rule held for approval

Sequencer Enrolment Runs

Method	Path	Operation	Description
`GET`	`/v2/sequencer/enrollment-runs`	List enrolment runs	Recent runs for one sequence, newest first
`POST`	`/v2/sequencer/enrollment-runs`	Start an enrolment run	Queues up to 5000 prospects and returns immediately with a `run_id`
`GET`	`/v2/sequencer/enrollment-runs/{run_id}`	Get an enrolment run	Progress and outcome: how many were considered, enrolled, skipped and held, with a sample of the skips and why
`POST`	`/v2/sequencer/enrollment-runs/{run_id}/cancel`	Cancel an enrolment run	Stops the run adding anyone else
`POST`	`/v2/sequencer/enrollment-runs/preview`	Preview an enrolment	What would happen if you ran this, without running it

Sequencer Tasks

Method	Path	Operation	Description
`GET`	`/v2/sequencer/tasks`	List tasks	The team’s sequencer task queue: the calls, emails and to-dos a cadence has produced, plus any one-off tasks…
`POST`	`/v2/sequencer/tasks`	Create a one-off task	A standalone to-do for a contact, not tied to any cadence
`DELETE`	`/v2/sequencer/tasks/{id}`	Cancel a one-off task	One-off tasks only, and it cancels rather than destroys — the task moves to `cancelled` so the history survives
`GET`	`/v2/sequencer/tasks/{id}`	Get a task	Returns one task with its contact, sequence and step
`PATCH`	`/v2/sequencer/tasks/{id}`	Update a one-off task	One-off tasks only
`POST`	`/v2/sequencer/tasks/{id}/complete`	Complete a task	Resolves the task and advances the cadence
`GET`	`/v2/sequencer/tasks/{id}/events`	List task events	The timeline for one task, newest first
`POST`	`/v2/sequencer/tasks/{id}/reassign`	Reassign a task	Hands one task to another rep
`POST`	`/v2/sequencer/tasks/{id}/skip`	Skip a task	Skipping still advances the cadence
`POST`	`/v2/sequencer/tasks/{id}/snooze`	Snooze a task	Moves the due date
`GET`	`/v2/sequencer/tasks/account-coverage`	Get buying-committee coverage	For the accounts you name, which buying-committee seats are already covered by a contact in a sequence and…
`POST`	`/v2/sequencer/tasks/bulk`	Create one-off tasks in bulk	One task per contact, at most 500
`POST`	`/v2/sequencer/tasks/bulk/reassign`	Reassign tasks in bulk	Hands up to 500 tasks to another rep
`POST`	`/v2/sequencer/tasks/bulk/skip`	Skip tasks in bulk	Skipping still advances the cadence — the contact moves to the next step rather than stalling
`POST`	`/v2/sequencer/tasks/bulk/snooze`	Snooze tasks in bulk	Moves the due date on up to 500 tasks
`POST`	`/v2/sequencer/tasks/materialize-call-list`	Fill a rep’s dial list from their call tasks	Pushes due call tasks into the rep’s Salesfinity dial list so they can be dialled
`GET`	`/v2/sequencer/tasks/summary`	Get a task-queue summary	Counts for the overdue / today / this week / later buckets

Sequencer Suppression

Method	Path	Operation	Description
`GET`	`/v2/sequencer/suppression`	List suppression entries	The team’s do-not-contact list, checked before every enrolment and every send
`POST`	`/v2/sequencer/suppression`	Add a suppression entry	Adds one address, domain or phone number to the do-not-contact list
`DELETE`	`/v2/sequencer/suppression/{id}`	Remove a suppression entry	Lifts the block for that address, domain or number
`POST`	`/v2/sequencer/suppression/import`	Import suppression entries	Up to 1000 entries at once

Sequencer Policies

Method	Path	Operation	Description
`GET`	`/v2/sequencer/policies`	List rules of engagement	The team’s policies
`POST`	`/v2/sequencer/policies`	Create a rules-of-engagement policy	Condition and action types come from `/v2/sequencer/policies/catalog`, which is the live vocabulary — this…
`DELETE`	`/v2/sequencer/policies/{id}`	Delete a rules-of-engagement policy	Sequences pointing at it fall back to the team default
`GET`	`/v2/sequencer/policies/{id}`	Get a rules-of-engagement policy	One policy with its rules and outcome rules, and whether it is the team default
`PATCH`	`/v2/sequencer/policies/{id}`	Update a rules-of-engagement policy	Applies immediately to every sequence using this policy, so preview the rules first
`POST`	`/v2/sequencer/policies/{id}/default`	Make a policy the team default	Every sequence that does not name its own policy falls back to the default, so this changes behaviour across…
`GET`	`/v2/sequencer/policies/catalog`	Get the rules-of-engagement catalog	The conditions and actions a rule can be built from, and which scopes each is valid in
`POST`	`/v2/sequencer/policies/preview`	Preview a draft rule set	Replays an unsaved rule set against the team’s recent enrolments and reports what it would have done

Sequencer Settings

Method	Path	Operation	Description
`GET`	`/v2/sequencer/email-accounts`	List sending mailboxes	The team’s sending mailboxes with their health, warmup state and daily capacity
`GET`	`/v2/sequencer/email-accounts/{id}`	Get a sending mailbox	Health, warmup and sending limits for one mailbox
`GET`	`/v2/sequencer/settings`	Get sequencer settings	Team-level defaults: the shared mailbox pool, the default sending schedule, warmup defaults, unsubscribe…

Resources for agents and crawlers

/llms.txt — a compact index of every page on this site.
/llms-full.txt — the full documentation as a single plain-text file.
/api-reference/openapi.json — the complete OpenAPI 3.0.1 description, also served at /openapi.json.
/sitemap.xml — every canonical URL.
Any page also serves Markdown. Append .md to a page URL, or send Accept: text/markdown, to get the source instead of the rendered page.

curl -H 'Accept: text/markdown' https://docs.salesfinity.ai/api-reference/introduction
curl https://docs.salesfinity.ai/api-reference/introduction.md

Getting help

Email [email protected] or browse the help center. When reporting an API problem, include the request path, the timestamp, and the error and statusCode from the response body — that is usually enough to find the request in Salesfinity’s logs.

​At a glance

​Quickstart

​Authentication

​Conventions

​Errors

​Webhooks

​What you can do with the API

​Complete endpoint index

​Contact Lists

​Teams

​Dispositions

​Sequences

​Call Logs

​Analytics

​Snoozed Contacts

​Follow-up Tasks

​Custom Fields

​Scored Calls

​Notes

​Enrichment

​Sequencer Sequences

​Sequencer Steps

​Sequencer Templates

​Sequencer Enrollments

​Sequencer Enrolment Runs

​Sequencer Tasks

​Sequencer Suppression

​Sequencer Policies

​Sequencer Settings

​Resources for agents and crawlers

​Getting help