Salesfinity API Documentation - Salesfinity API Docs

Salesfinity is a parallel dialing platform for outbound sales teams. This site documents every programmatic way into it: a JSON-over-HTTPS REST API and a hosted MCP server for AI assistants. Everything below is on this page in plain text so that a person skimming, a search crawler, and an autonomous agent all get the same answer without running any JavaScript.

Get an API key

Dashboard → Settings → Connections & API → generate a key.

Developer portal

Keys, quickstarts, testing guidance, and machine-readable resources.

API reference

All 35 operations, generated from the OpenAPI description.

MCP server

Connect Salesfinity to Claude and other MCP clients.

At a glance


API 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)
MCP endpoint	`https://mcp.salesfinity.ai/mcp`
Docs index for agents	`/llms.txt`, `/llms-full.txt`
Sitemap	`/sitemap.xml`
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.

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

The full envelope, per-status examples, and retry guidance are on the Errors page.

Pagination, filtering, and sorting

List endpoints take page (1-based) and limit query parameters and return the requested page alongside a total count. The limit default is not uniform — it is 10 on most list endpoints, 50 for contacts inside a single list, and 100 for sequences — so read the parameter schema on the operation you are calling. Where a maximum applies it is 100. Filtering uses bracketed query parameters such as filters[start_date], filters[user_ids], and filters[disposition_ids]. Sorting uses a sort parameter that takes a field name, prefixed with - for descending order, for example sort=-createdAt.

What you can do with the API

The REST API exposes 35 operations across 12 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
Analytics	3	Aggregated call metrics with growth rates, plus breakdowns by contact list and by SDR
Enrichment	3	Start an asynchronous work or personal email lookup, poll its result, and check credit balance
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
Sequences	2	Sequences referenced by the team’s call logs
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 never drifts from 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

Webhooks

Webhook subscriptions are created and managed inside the Salesfinity application, not through this API. Configure them in the dashboard; there are no webhook endpoints to call. The one exception is enrichment, which takes a per-request callback_url rather than a standing subscription — see Enrich Email.

MCP server for AI assistants

Salesfinity runs a hosted Model Context Protocol server at https://mcp.salesfinity.ai/mcp. It gives an assistant direct, authenticated access to the same data as the REST API — contact lists, call logs, scored calls, and analytics — without you writing an integration.

Claude.ai

One-click connector setup for Claude.ai.

Claude Code

Add the server to Claude Code from the CLI.

Other clients

Cursor, VS Code, and any MCP-compatible client.

Tool reference

Every MCP tool, its parameters, and its behavior.

Resources for agents and crawlers

This documentation publishes machine-readable entry points so an agent can orient itself without scraping rendered HTML:

/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.

Get an API key

Developer portal

API reference

MCP server

​At a glance

​Quickstart

​Authentication

​Errors

​Pagination, filtering, and sorting

​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

​Webhooks

​MCP server for AI assistants