> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesfinity.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Salesfinity API Documentation

> REST API and MCP server for the Salesfinity parallel dialer — authentication, endpoints, errors, and quickstarts in one place.

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.

<CardGroup cols={2}>
  <Card title="Get an API key" icon="key" href="https://preview.salesfinity.co/dashboard/settings">
    Dashboard → Settings → Connections & API → generate a key.
  </Card>

  <Card title="Developer portal" icon="code" href="/developers">
    Keys, quickstarts, testing guidance, and machine-readable resources.
  </Card>

  <Card title="API reference" icon="book" href="/api-reference/introduction">
    All 35 operations, generated from the OpenAPI description.
  </Card>

  <Card title="MCP server" icon="bolt" href="/mcp/overview">
    Connect Salesfinity to Claude and other MCP clients.
  </Card>
</CardGroup>

## 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`](/api-reference/openapi.json) (OpenAPI 3.0.1)                                   |
| **MCP endpoint**          | `https://mcp.salesfinity.ai/mcp`                                                                               |
| **Docs index for agents** | [`/llms.txt`](/llms.txt), [`/llms-full.txt`](/llms-full.txt)                                                   |
| **Sitemap**               | [`/sitemap.xml`](/sitemap.xml)                                                                                 |
| **Support**               | [hello@salesfinity.co](mailto:hello@salesfinity.co) · [support.salesfinity.ai](https://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.

```bash theme={null}
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](/api-reference/errors).

Once the key works, the usual next step is to list the team's contact lists and then read one:

```bash theme={null}
# 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.

```json theme={null}
{ "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](/api-reference/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](/api-reference/endpoint/get-contact-lists-csv)   | 8          | Create, read, merge, and delete CSV contact lists; add and remove the contacts inside them; push a list into the dialing queue |
| [Notes](/api-reference/endpoint/create-note)                     | 5          | Attach freeform notes to a person or company, list them, edit or delete your own, and toggle pins                              |
| [Snoozed Contacts](/api-reference/endpoint/get-snoozed-contacts) | 5          | Read and manage contacts held out of the dialing queue, by ID or LinkedIn username                                             |
| [Analytics](/api-reference/endpoint/analytics-overview)          | 3          | Aggregated call metrics with growth rates, plus breakdowns by contact list and by SDR                                          |
| [Enrichment](/api-reference/endpoint/enrich-email)               | 3          | Start an asynchronous work or personal email lookup, poll its result, and check credit balance                                 |
| [Call Logs](/api-reference/endpoint/call-log)                    | 2          | Paginated call history with filtering and sorting, and single-call lookup                                                      |
| [Scored Calls](/api-reference/endpoint/scored-calls)             | 2          | AI-scored calls with per-facet scoring and coaching recommendations                                                            |
| [Dispositions](/api-reference/endpoint/get-dispositions)         | 2          | Default and custom call outcomes configured for the team                                                                       |
| [Sequences](/api-reference/endpoint/get-sequences)               | 2          | Sequences referenced by the team's call logs                                                                                   |
| [Teams](/api-reference/endpoint/get-team)                        | 1          | The team that owns the API key, with members, statuses, and licenses                                                           |
| [Follow-up Tasks](/api-reference/endpoint/get-follow-ups)        | 1          | Follow-up tasks created from call outcomes                                                                                     |
| [Custom Fields](/api-reference/endpoint/get-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](/api-reference/endpoint/create-list)                                | Creates a new contact list                                                         |
| `POST`   | `/v1/contact-lists/{id}`                      | [Add a contact to a list](/api-reference/endpoint/add-contact)                              | Add a contact to an existing list                                                  |
| `DELETE` | `/v1/contact-lists/{id}/contacts/{contactId}` | [Remove a contact from a list](/api-reference/endpoint/remove-contact)                      | Remove a contact from a contact list                                               |
| `POST`   | `/v1/contact-lists/{id}/merge`                | [Merge contact lists](/api-reference/endpoint/merge-lists)                                  | Merges contacts from one or more source lists into the target list                 |
| `GET`    | `/v1/contact-lists/csv`                       | [List contact lists](/api-reference/endpoint/get-contact-lists-csv)                         | Returns all CSV contact lists for the team with filtering, sorting, and pagination |
| `DELETE` | `/v1/contact-lists/csv/{id}`                  | [Delete a contact list](/api-reference/endpoint/delete-contact-list)                        | Delete a contact list                                                              |
| `GET`    | `/v1/contact-lists/csv/{id}`                  | [Get a contact list](/api-reference/endpoint/get-contact-list-by-id)                        | 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](/api-reference/endpoint/reimport-contacts) | Reimport contacts from CSV                                                         |

### Teams

| Method | Path       | Operation                                                | Description              |
| ------ | ---------- | -------------------------------------------------------- | ------------------------ |
| `GET`  | `/v1/team` | [Get the current team](/api-reference/endpoint/get-team) | Returns team information |

### Dispositions

| Method | Path                    | Operation                                                          | Description                                                                                |
| ------ | ----------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `GET`  | `/v1/dispositions`      | [List dispositions](/api-reference/endpoint/get-dispositions)      | Returns all dispositions available for the team, including default and custom dispositions |
| `GET`  | `/v1/dispositions/{id}` | [Get a disposition](/api-reference/endpoint/get-disposition-by-id) | Get a specific disposition by its internal ID                                              |

### Sequences

| Method | Path                 | Operation                                                    | Description                                          |
| ------ | -------------------- | ------------------------------------------------------------ | ---------------------------------------------------- |
| `GET`  | `/v1/sequences`      | [List sequences](/api-reference/endpoint/get-sequences)      | Returns all sequences used in call logs for the team |
| `GET`  | `/v1/sequences/{id}` | [Get a sequence](/api-reference/endpoint/get-sequence-by-id) | Get a specific sequence by ID                        |

### Call Logs

| Method | Path                | Operation                                                    | Description                                                                |
| ------ | ------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------- |
| `GET`  | `/v1/call-log`      | [List call logs](/api-reference/endpoint/call-log)           | Retrieves a paginated list of call logs with filtering and sorting support |
| `GET`  | `/v1/call-log/{id}` | [Get a call log](/api-reference/endpoint/get-call-log-by-id) | Get a call log by ID                                                       |

### Analytics

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

### Snoozed Contacts

| Method   | Path                                          | Operation                                                                                             | Description                                                             |
| -------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `GET`    | `/v1/snoozed-contacts`                        | [List snoozed contacts](/api-reference/endpoint/get-snoozed-contacts)                                 | Returns all snoozed contacts for the team with pagination and filtering |
| `DELETE` | `/v1/snoozed-contacts/{id}`                   | [Delete a snoozed contact](/api-reference/endpoint/delete-snoozed-contact)                            | Delete a snoozed contact                                                |
| `GET`    | `/v1/snoozed-contacts/{id}`                   | [Get a snoozed contact](/api-reference/endpoint/get-snoozed-contact-by-id)                            | Get a snoozed contact by ID                                             |
| `PUT`    | `/v1/snoozed-contacts/{id}`                   | [Update a snoozed contact](/api-reference/endpoint/update-snoozed-contact)                            | Update a snoozed contact                                                |
| `GET`    | `/v1/snoozed-contacts/by-linkedin/{username}` | [Get a snoozed contact by LinkedIn username](/api-reference/endpoint/get-snoozed-contact-by-linkedin) | Get a snoozed contact by LinkedIn username                              |

### Follow-up Tasks

| Method | Path            | Operation                                                      | Description                                              |
| ------ | --------------- | -------------------------------------------------------------- | -------------------------------------------------------- |
| `GET`  | `/v1/follow-up` | [List follow-up tasks](/api-reference/endpoint/get-follow-ups) | Returns all follow-up tasks for the team with pagination |

### Custom Fields

| Method | Path                | Operation                                                       | Description                                               |
| ------ | ------------------- | --------------------------------------------------------------- | --------------------------------------------------------- |
| `GET`  | `/v1/custom-fields` | [List custom fields](/api-reference/endpoint/get-custom-fields) | Returns all custom field mappings configured for the team |

### Scored Calls

| Method | Path                    | Operation                                                          | Description                                                                                                    |
| ------ | ----------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `GET`  | `/v1/scored-calls`      | [List scored calls](/api-reference/endpoint/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](/api-reference/endpoint/get-scored-call-by-id) | Retrieves a single scored call by its ID with full AI-generated insight                                        |

### Notes

| Method   | Path                 | Operation                                             | Description                                                                                                  |
| -------- | -------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `GET`    | `/v2/notes`          | [List notes](/api-reference/endpoint/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](/api-reference/endpoint/create-note)  | Creates a note attached to a person (Contact) or company (Company), identified by domain identifiers rather… |
| `DELETE` | `/v2/notes/{id}`     | [Delete a note](/api-reference/endpoint/delete-note)  | Deletes an existing note                                                                                     |
| `PATCH`  | `/v2/notes/{id}`     | [Update a note](/api-reference/endpoint/update-note)  | Updates the content of an existing note                                                                      |
| `POST`   | `/v2/notes/{id}/pin` | [Toggle a note pin](/api-reference/endpoint/pin-note) | Toggles whether a note is pinned                                                                             |

### Enrichment

| Method | Path                            | Operation                                                                       | Description                                                                              |
| ------ | ------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `GET`  | `/v1/api/enrichment/credits`    | [Get enrichment credit balance](/api-reference/endpoint/get-enrichment-credits) | Returns the current enrichment credit balance for the team that owns the API key         |
| `POST` | `/v1/api/enrichment/email`      | [Start an email enrichment](/api-reference/endpoint/enrich-email)               | 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](/api-reference/endpoint/get-email-enrichment)  | 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](/api-reference/endpoint/enrich-email).

## MCP server for AI assistants

Salesfinity runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) 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.

<CardGroup cols={2}>
  <Card title="Claude.ai" icon="comment" href="/mcp/claude-ai">
    One-click connector setup for Claude.ai.
  </Card>

  <Card title="Claude Code" icon="terminal" href="/mcp/claude-code">
    Add the server to Claude Code from the CLI.
  </Card>

  <Card title="Other clients" icon="plug" href="/mcp/other-clients">
    Cursor, VS Code, and any MCP-compatible client.
  </Card>

  <Card title="Tool reference" icon="wrench" href="/mcp/tools">
    Every MCP tool, its parameters, and its behavior.
  </Card>
</CardGroup>

## Resources for agents and crawlers

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

* [`/llms.txt`](/llms.txt) — a compact index of every page on this site.
* [`/llms-full.txt`](/llms-full.txt) — the full documentation as a single plain-text file.
* [`/api-reference/openapi.json`](/api-reference/openapi.json) — the complete OpenAPI 3.0.1
  description, also served at [`/openapi.json`](/openapi.json).
* [`/sitemap.xml`](/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.

```bash theme={null}
curl -H 'Accept: text/markdown' https://docs.salesfinity.ai/api-reference/introduction
curl https://docs.salesfinity.ai/api-reference/introduction.md
```

## Getting help

Email [hello@salesfinity.co](mailto:hello@salesfinity.co) or browse the
[help center](https://support.salesfinity.ai). 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.