# Add a Contact to a List
Source: https://docs.salesfinity.ai/api-reference/endpoint/add-contact
POST /v1/contact-lists/{id}
Add a contact to an existing list
Adds a new contact to an existing contact list. The contact is added to both the source list and the dialing queue immediately.
### Path Parameters
* **id** (*required*, string): Contact list ID returned from [Create a List](/api-reference/endpoint/create-list) or [Get All Contact Lists](/api-reference/endpoint/get-contact-lists).
### Request Body
| Field | Type | Required | Max Length | Description |
| -------------------- | ------ | -------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `first_name` | string | No | 200 | Contact's first name |
| `last_name` | string | No | 200 | Contact's last name |
| `email` | string | No | 320 | Contact's email address |
| `phone_numbers` | array | No | 10 items | Array of phone number objects |
| `company` | string | No | 300 | Company name |
| `title` | string | No | 300 | Job title |
| `linkedin` | string | No | 500 | LinkedIn profile URL |
| `website` | string | No | 500 | Website URL |
| `account` | string | No | 500 | Account or organization identifier |
| `notes` | string | No | 2,000 | Free-text notes about the contact |
| `priority` | number | No | — | Contact priority (lower is higher priority) |
| `timezone` | string | No | 100 | IANA timezone identifier (e.g. `America/New_York`) |
| `external_relations` | object | No | — | External system references (e.g. CRM IDs) |
| `custom_fields` | array | No | 10 items | Array of custom field objects. See [Get Custom Fields](/api-reference/endpoint/get-custom-fields) to retrieve available fields for your team. |
#### Phone Number Object
| Field | Type | Required | Description |
| -------------- | ------ | -------- | -------------------------------------------------- |
| `type` | string | Yes | Phone number type: `mobile`, `direct`, or `office` |
| `number` | string | Yes | Phone number in E.164 format (e.g. `+14155552671`) |
| `country_code` | string | No | ISO 3166-1 alpha-2 country code (e.g. `US`) |
| `extension` | string | No | Phone extension |
#### Custom Field Object
| Field | Type | Required | Max Length | Description |
| ------- | ------ | -------- | ---------- | ------------------------------------------------------ |
| `type` | string | Yes | — | Field data type: `string`, `number`, or `boolean` |
| `label` | string | Yes | 100 | Display label for the field |
| `value` | any | No | — | Field value (string, number, boolean, or string array) |
### Example Request
```json theme={null}
{
"first_name": "John",
"last_name": "Doe",
"email": "john@acme.com",
"company": "Acme Corp",
"title": "VP of Sales",
"phone_numbers": [
{
"type": "direct",
"number": "+14155552671"
}
],
"notes": "Interested in enterprise plan. Follow up after Q2.",
"custom_fields": [
{
"type": "string",
"label": "Industry",
"value": "SaaS"
},
{
"type": "number",
"label": "Employee Count",
"value": 250
},
{
"type": "boolean",
"label": "Decision Maker",
"value": true
}
]
}
```
### Response (201)
Returns the contact list ID.
# Get List Performance
Source: https://docs.salesfinity.ai/api-reference/endpoint/analytics-list-performance
GET /v1/analytics/list-performance
Returns call metrics grouped by contact list with pagination
Returns call metrics grouped by contact list with pagination. Use this endpoint to analyze performance across different contact lists.
### Query Parameters
* **start\_date** (*optional*, date): Start date for the analytics period. Accepts ISO 8601 format. If omitted, defaults to 7 days before `end_date`.
* Examples:
* `2024-01-01T00:00:00.000Z` - ISO 8601 with UTC timezone
* `2024-01-01` - Simple date format (YYYY-MM-DD)
* `2024-01-01T00:00:00-05:00` - ISO 8601 with timezone offset
* **end\_date** (*optional*, date): End date for the analytics period. Accepts ISO 8601 format. If omitted, defaults to the current date.
* Examples:
* `2024-01-31T23:59:59.999Z` - ISO 8601 with UTC timezone
* `2024-01-31` - Simple date format (YYYY-MM-DD)
* `2024-01-31T23:59:59-05:00` - ISO 8601 with timezone offset
* **user\_ids** (*optional*, array of strings): Filter by specific user IDs.
* Example: `["64d2b3f2c4e3a6b8f2d9e1a7"]`
* **disposition\_ids** (*optional*, array of numbers): Filter by disposition IDs (1=Meeting Set, 2=No Longer With Company, 3=Not Interested, etc.).
* Example: `[1, 2, 3]`
* **timezone** (*optional*, string): Timezone for date calculations.
* Example: `America/New_York`
* **page** (*optional*, number): Page number (default: 1).
* Example: `1`
* **limit** (*optional*, number): Items per page (default: 10, max: 100).
* Example: `10`
* **search** (*optional*, string): Search by list name.
* Example: `"sales"`
### Response
Returns a paginated list of contact list performance metrics.
**Metrics per list:**
* `_id` - Contact list ID
* `name` - Contact list name
* `source` - List source (e.g., "csv", "crm")
* `total_calls` - Total calls made to contacts in this list
* `connected_calls` - Connected calls
* `conversations` - Meaningful conversations
* `meetings_set` - Meetings set from this list
* `good_quality_contacts` - Contacts with valid phone numbers
* `data_quality` - Ratio of good quality contacts
* `owner` - List owner information (id, name, email)
# Get Analytics Overview
Source: https://docs.salesfinity.ai/api-reference/endpoint/analytics-overview
GET /v1/analytics/overview
Returns aggregated analytics metrics with growth rates compared to the previous period
Returns aggregated analytics metrics with growth rates compared to the previous period. Use this endpoint to get a high-level summary of call performance including total calls, connected calls, conversations, meetings set, and follow-up tasks.
### Query Parameters
* **start\_date** (*optional*, date): Start date for the analytics period. Accepts ISO 8601 format. If omitted, defaults to 7 days before `end_date`.
* Examples:
* `2024-01-01T00:00:00.000Z` - ISO 8601 with UTC timezone
* `2024-01-01` - Simple date format (YYYY-MM-DD)
* `2024-01-01T00:00:00-05:00` - ISO 8601 with timezone offset
* **end\_date** (*optional*, date): End date for the analytics period. Accepts ISO 8601 format. If omitted, defaults to the current date.
* Examples:
* `2024-01-31T23:59:59.999Z` - ISO 8601 with UTC timezone
* `2024-01-31` - Simple date format (YYYY-MM-DD)
* `2024-01-31T23:59:59-05:00` - ISO 8601 with timezone offset
* **user\_ids** (*optional*, array of strings): Filter by specific user IDs.
* Example: `["64d2b3f2c4e3a6b8f2d9e1a7"]`
* **disposition\_ids** (*optional*, array of numbers): Filter by disposition IDs (1=Meeting Set, 2=No Longer With Company, 3=Not Interested, etc.).
* Example: `[1, 2, 3]`
* **timezone** (*optional*, string): Timezone for date calculations.
* Example: `America/New_York`
### Response
Each metric is returned as an object of the form `{ "value": number, "growth_rate": number }`, where `growth_rate` is the percentage change compared to the previous period of equal length.
**Metrics included:**
* `total_calls` - Total number of calls made
* `total_inbound_calls` - Total number of inbound calls
* `connected_calls` - Calls that connected (answered by human, disposition \< 10)
* `conversations` - Connected calls with a meeting set or duration >= 60s
* `connection_rate` - `connected_calls / total_calls` (percentage)
* `conversation_rate` - `conversations / connected_calls` (percentage)
* `avg_calls_per_day` - Average calls per active day
* `total_call_duration` - Total call duration in seconds
* `total_meetings_set` - Calls with disposition ID = 1 (Meeting Set)
* `total_follow_up_tasks` - Number of follow-up tasks created
* `unique_contacts` - Number of distinct contacts called
* `unique_companies` - Number of distinct companies called
Example:
```json theme={null}
{
"total_calls": { "value": 1240, "growth_rate": 12.5 },
"total_inbound_calls": { "value": 85, "growth_rate": -3.1 },
"connected_calls": { "value": 430, "growth_rate": 8.0 },
"conversations": { "value": 96, "growth_rate": 5.2 },
"connection_rate": { "value": 34.7, "growth_rate": 1.4 },
"conversation_rate": { "value": 22.3, "growth_rate": -0.8 },
"avg_calls_per_day": { "value": 62, "growth_rate": 4.0 },
"total_call_duration": { "value": 51840, "growth_rate": 9.7 },
"total_meetings_set": { "value": 41, "growth_rate": 10.0 },
"total_follow_up_tasks": { "value": 58, "growth_rate": 6.3 },
"unique_contacts": { "value": 512, "growth_rate": 7.1 },
"unique_companies": { "value": 233, "growth_rate": 3.9 }
}
```
# Get SDR Performance
Source: https://docs.salesfinity.ai/api-reference/endpoint/analytics-sdr-performance
GET /v1/analytics/sdr-performance
Returns call metrics grouped by SDR (user) with pagination
Returns call metrics grouped by SDR (Sales Development Representative) with pagination. Use this endpoint to analyze individual user performance.
### Query Parameters
* **start\_date** (*optional*, date): Start date for the analytics period. Accepts ISO 8601 format. If omitted, defaults to 7 days before `end_date`.
* Examples:
* `2024-01-01T00:00:00.000Z` - ISO 8601 with UTC timezone
* `2024-01-01` - Simple date format (YYYY-MM-DD)
* `2024-01-01T00:00:00-05:00` - ISO 8601 with timezone offset
* **end\_date** (*optional*, date): End date for the analytics period. Accepts ISO 8601 format. If omitted, defaults to the current date.
* Examples:
* `2024-01-31T23:59:59.999Z` - ISO 8601 with UTC timezone
* `2024-01-31` - Simple date format (YYYY-MM-DD)
* `2024-01-31T23:59:59-05:00` - ISO 8601 with timezone offset
* **user\_ids** (*optional*, array of strings): Filter by specific user IDs.
* Example: `["64d2b3f2c4e3a6b8f2d9e1a7"]`
* **disposition\_ids** (*optional*, array of numbers): Filter by disposition IDs (1=Meeting Set, 2=No Longer With Company, 3=Not Interested, etc.).
* Example: `[1, 2, 3]`
* **timezone** (*optional*, string): Timezone for date calculations.
* Example: `America/New_York`
* **page** (*optional*, number): Page number (default: 1).
* Example: `1`
* **limit** (*optional*, number): Items per page (default: 10, max: 100).
* Example: `10`
* **search** (*optional*, string): Search by SDR name or email.
* Example: `"john@example.com"`
### Response
Returns a paginated list of SDR performance metrics.
**Metrics per SDR:**
* `_id` - User ID
* `first_name` - SDR first name
* `last_name` - SDR last name
* `email` - SDR email
* `image` - Profile image URL
* `total_calls` - Total calls made
* `connected_calls` - Connected calls
* `connection_rate` - Ratio of connected to total calls (0-1)
* `conversations` - Meaningful conversations
* `conversation_rate` - Ratio of conversations to total calls (0-1)
* `avg_dials_day` - Average dials per active day
* `total_duration` - Total call duration in seconds
* `meetings_set` - Number of meetings set
* `data_quality` - Data quality ratio (0-1)
# Retrieve Call Logs
Source: https://docs.salesfinity.ai/api-reference/endpoint/call-log
GET /v1/call-log
Retrieves a paginated list of call logs with filtering and sorting support.
Retrieves a paginated list of call logs from the system. Use this endpoint to access call logs with metadata, such as timestamps, dispositions, and contact information.
### Query Parameters
#### Pagination & Sorting
* **limit** (*optional*, number): Number of items per page (default: 10, max: 100)
* **page** (*optional*, number): The current page number to retrieve (default: 1)
* **sort** (*optional*, string): Sort field with optional `-` prefix for descending order (default: `-createdAt`)
#### Filters
All filters are passed as query parameters with the `filters[field]` format.
##### Date Filters
* **filters\[start\_date]** (*optional*, ISO 8601 date): Start of date range
* **filters\[end\_date]** (*optional*, ISO 8601 date): End of date range
##### Call Properties
* **filters\[outcome]** (*optional*, string): Filter by call outcome
* `answered` - Call was answered
* `no-answer` - Call was not answered
* `cancelled` - Call was cancelled
* **filters\[direction]** (*optional*, string): Filter by call direction
* `inbound` - Incoming calls
* `outbound` - Outgoing calls
* **filters\[min\_duration]** (*optional*, number): Minimum call duration in seconds
* **filters\[max\_duration]** (*optional*, number): Maximum call duration in seconds
* **filters\[has\_recording]** (*optional*, boolean): Filter by recording availability
* `true` - Only calls with recordings
* `false` - Only calls without recordings
* **filters\[answered\_by]** (*optional*, string): Filter by who answered
* `human` - Answered by a person
* `machine_start` - Answered by voicemail/machine
* **filters\[is\_completed]** (*optional*, boolean): Filter by completion status
##### Disposition Filters
* **filters\[disposition\_ids]** (*optional*, number\[]): Filter by disposition IDs. See [Get Dispositions](/api-reference/endpoint/get-dispositions) for available IDs.
* **filters\[exclude\_negative\_dispositions]** (*optional*, boolean): When `true`, only returns calls with positive dispositions (Meeting Set, Referral, Callback Later, etc.)
##### Entity Filters
* **filters\[user\_ids]** (*optional*, string\[]): Filter by user IDs
* **filters\[contact\_list\_ids]** (*optional*, string\[]): Filter by contact list IDs
* **filters\[contact\_ids]** (*optional*, string\[]): Filter by contact IDs (the contact's `_id`)
* **filters\[crm\_ids]** (*optional*, string\[]): Filter by CRM IDs (the contact's `crm_id`)
* **filters\[sequences]** (*optional*, string\[]): Filter by sequence IDs. See [Get Sequences](/api-reference/endpoint/get-sequences) to discover available sequences.
##### Phone Number Filters
* **filters\[from]** (*optional*, string\[]): Filter by caller phone numbers
* **filters\[to]** (*optional*, string\[]): Filter by called phone numbers
##### Search
* **filters\[search]** (*optional*, string): Full-text search across the contact's name, company, account, title and email, the to/from and contact phone numbers, and the call notes, summary and disposition/call purpose/call sentiment names. Call transcripts are not searched.
### Example Requests
**Basic request with date filter:**
```
GET /v1/call-log?filters[start_date]=2024-01-01&filters[end_date]=2024-01-31
```
**Filter by outcome and minimum duration:**
```
GET /v1/call-log?filters[outcome]=answered&filters[min_duration]=60
```
**Filter by disposition and recording:**
```
GET /v1/call-log?filters[disposition_ids][]=1&filters[disposition_ids][]=4&filters[has_recording]=true
```
**Search with multiple filters:**
```
GET /v1/call-log?filters[search]=Acme&filters[direction]=outbound&page=1&limit=50
```
**Filter by sequence:**
```
GET /v1/call-log?filters[sequences][]=seq_12345&filters[sequences][]=seq_67890
```
**Filter by CRM ID:**
```
GET /v1/call-log?filters[crm_ids][]=00Q5f000001abcXYZ
```
### Response
Returns a JSON object containing the list of call logs with pagination metadata.
Each call log includes both `contact_list` and `source`. `contact_list` is the **dialing-queue** list the call was placed from (its `_id` is the queue id). `source` identifies the **original source list** the call came from — for CSV lists, `source.id` is the CSV list id (which differs from the queue id). `source.id`/`source.name` are `null` for non-CSV lists. `contact_list` is unchanged and remains fully backward compatible.
```json theme={null}
{
"data": [
{
"_id": "507f1f77bcf86cd799439011",
"call_id": "call_abc123",
"outcome": "answered",
"direction": "outbound",
"answered_by": "human",
"duration": 180,
"to": "+1234567890",
"from": "+1987654321",
"disposition": {
"internal_id": 1,
"external_id": "meeting_set",
"external_name": "Meeting Set"
},
"contact": {
"first_name": "John",
"last_name": "Doe",
"company": "Acme Corp",
"email": "john@acme.com",
"title": "VP of Sales"
},
"contact_list": {
"_id": "507f1f77bcf86cd799439022",
"name": "Q1 Prospects"
},
"source": {
"type": "csv",
"id": "507f1f77bcf86cd799439099",
"name": "Q1 Prospects"
},
"user": {
"_id": "507f1f77bcf86cd799439033",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@company.com"
},
"recording_url": "https://recordings.example.com/call_abc123.mp3",
"notes": "Great conversation, follow up next week",
"is_completed": true,
"started_at": "2024-01-15T14:30:00.000Z",
"ended_at": "2024-01-15T14:33:00.000Z",
"createdAt": "2024-01-15T14:33:00.000Z",
"updatedAt": "2024-01-15T14:33:00.000Z"
}
],
"pagination": {
"total": 150,
"page": 1,
"limit": 10,
"pages": 15
}
}
```
### Response Fields
| Field | Type | Description |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_id` | string | Unique identifier |
| `call_id` | string | Unique call identifier |
| `outcome` | string | Call outcome (answered, no-answer, cancelled) |
| `direction` | string | Call direction (inbound, outbound) |
| `answered_by` | string | Who answered (human, machine\_start) |
| `duration` | number | Call duration in seconds |
| `to` | string | Called phone number |
| `from` | string | Caller phone number |
| `disposition` | object | Disposition details with internal\_id |
| `contact` | object | Contact information |
| `contact_list` | object | The dialing-queue list (`ContactList`) the call was placed from; its `_id` is the queue id. Unchanged for backward compatibility. |
| `source` | object | The original source list the call came from. Additive; leaves `contact_list` untouched. Fields: `type` (integration source, e.g. `csv`/`hubspot`), `id` (the original source list id — the CSV list id for CSV lists, `null` for non-CSV), `name` (source list name). `id`/`name` are `null` when unresolved. |
| `user` | object | User who made/received the call |
| `recording_url` | string | URL to call recording (if available) |
| `notes` | string | Call notes |
| `transcription` | string | Call transcription (if available) |
| `summary` | string | AI-generated call summary (if available) |
| `is_completed` | boolean | Whether the call is completed |
| `started_at` | date | Call start time |
| `ended_at` | date | Call end time |
| `createdAt` | date | Record creation time |
| `updatedAt` | date | Record last update time |
# Create a List
Source: https://docs.salesfinity.ai/api-reference/endpoint/create-list
POST /v1/contact-lists
Creates a new contact list
Creates a new contact list for the team. Contacts are optional and can be added later via the [Add Contact](/api-reference/endpoint/add-contact) endpoint.
### Limits
| Resource | Limit |
| ------------------------- | ---------------- |
| Contacts per list | 2,000 |
| List name | 1–100 characters |
| Notes per contact | 2,000 characters |
| Phone numbers per contact | 10 |
| Custom fields per contact | 10 |
| Request payload size | 10MB |
### Request Body
| Field | Type | Required | Description |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | Yes | Name of the contact list (1–100 characters) |
| `user_id` | string | Yes | ID of the team member who owns this list. Must be a valid member of the team. Get this from [Get Team](/api-reference/endpoint/get-team). |
| `contacts` | array | No | Array of contact objects (max 2,000). See [Add Contact](/api-reference/endpoint/add-contact) for the contact object schema. |
### Example Request
```json theme={null}
{
"name": "Q2 Outbound Prospects",
"user_id": "680edc0d1504192884a148e0",
"contacts": [
{
"first_name": "John",
"last_name": "Doe",
"email": "john@acme.com",
"company": "Acme Corp",
"title": "VP of Sales",
"phone_numbers": [
{
"type": "direct",
"number": "+14155552671"
}
]
}
]
}
```
### Example Request (empty list)
```json theme={null}
{
"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.).
# Create a Note
Source: https://docs.salesfinity.ai/api-reference/endpoint/create-note
POST /v2/notes
Creates a note attached to a person (Contact) or company (Company), identified by domain identifiers rather than by list/contact IDs. For a person, supply at least one of linkedin_url, email, crm_id, or phone. For a company, supply at least one of website_url or name. If no matching record exists yet, a minimal Contact or Company is created on the fly and the note is attached to its stable ID.
Creates a note attached to a **person** (Contact) or a **company** (Company). Unlike the older list-scoped endpoints, v2 notes are addressed by **domain identifiers** rather than by contact-list and contact IDs — so you can attach a note without first looking the person up in a list.
The target is resolved from the identifiers you provide. If no matching record exists yet, a minimal Contact or Company is created on the fly and the note is attached to its stable ID.
### Request Body
| Field | Type | Required | Max Length | Description |
| --------- | ------ | -------- | ---------- | --------------------------------------------------------------------------------------------- |
| `type` | string | Yes | — | `person` or `company`. Determines which identifier fields are required. |
| `user_id` | string | Yes | — | ID of the team member authoring the note. Must be a member of the team that owns the API key. |
| `content` | string | Yes | 10,000 | Plain text content of the note. |
#### Person identifiers (`type: "person"`)
Supply **at least one** of:
| Field | Type | Max Length | Description |
| -------------- | ------ | ---------- | ---------------------------------------------------------- |
| `linkedin_url` | string | 500 | LinkedIn profile URL. Username is extracted automatically. |
| `email` | string | 320 | Email address. |
| `crm_id` | string | 200 | External CRM identifier (e.g. `salesforce:003XXX`). |
| `phone` | string | 50 | Phone number in E.164 format. |
Optionally, link a company when a **new** Contact has to be created (ignored if the person already exists):
| Field | Type | Max Length | Description |
| ----------------- | ------ | ---------- | -------------------------------------- |
| `company_name` | string | 300 | Company name to link to the person. |
| `company_website` | string | 500 | Company website to link to the person. |
#### Company identifiers (`type: "company"`)
Supply **at least one** of:
| Field | Type | Max Length | Description |
| ------------- | ------ | ---------- | ------------------------------------------------------------------- |
| `website_url` | string | 500 | Company website URL. Normalized to hostname for matching. |
| `name` | string | 300 | Company name. Case-insensitive match against the company name list. |
### Example Request — person
```json theme={null}
{
"type": "person",
"user_id": "507f1f77bcf86cd799439033",
"content": "Mentioned moving back from Lisbon next quarter.",
"email": "john@example.com",
"company_name": "Acme Corp"
}
```
### Example Request — company
```json theme={null}
{
"type": "company",
"user_id": "507f1f77bcf86cd799439033",
"content": "Renewal owner is the new VP of Ops — loop in before Q3.",
"website_url": "https://acme.com"
}
```
### Response (201)
Returns the created [note object](/api-reference/endpoint/list-notes#note-object). For a person note, `contact` is set; for a company note, `company` is set.
### Errors
| Status | Description |
| ------ | --------------------------------------------------------------------------------------------------------------- |
| 400 | Validation failed (e.g. no identifier supplied for the chosen `type`), or `user_id` is not a member of the team |
# Create Webhook
Source: https://docs.salesfinity.ai/api-reference/endpoint/create-webhook
POST /v1/webhooks
Create a new webhook
Creates a new webhook subscription. Webhooks allow you to receive real-time HTTP POST notifications when specific events occur in your account.
### Request Body
| Field | Type | Required | Description |
| -------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | Yes | A descriptive name for the webhook |
| `url` | string | Yes | The URL to receive webhook POST requests (must be a valid URL) |
| `events` | string\[] | Yes | Array of event types to subscribe to |
| `dispositions` | number\[] | No | Filter `CALL_LOGGED` events by disposition IDs. If provided, only calls with matching dispositions will trigger the webhook. |
#### Available Events
| Event | Description |
| ----------------- | ----------------------------------------------------------------------------- |
| `CALL_LOGGED` | Triggered when a user logs a call, capturing relevant call details |
| `CONTACT_SNOOZED` | Triggered when a contact is snoozed, capturing the contact and snooze details |
### Example Request
```json theme={null}
{
"name": "CRM Call Sync",
"url": "https://example.com/webhooks/salesfinity",
"events": ["CALL_LOGGED"],
"dispositions": [1, 4]
}
```
### Response (201)
Returns the created webhook object.
```json theme={null}
{
"_id": "507f1f77bcf86cd799439011",
"name": "CRM Call Sync",
"url": "https://example.com/webhooks/salesfinity",
"events": ["CALL_LOGGED"],
"dispositions": [1, 4],
"status": "active",
"createdAt": "2024-01-15T10:00:00.000Z",
"updatedAt": "2024-01-15T10:00:00.000Z"
}
```
# Delete a List
Source: https://docs.salesfinity.ai/api-reference/endpoint/delete-contact-list
DELETE /v1/contact-lists/csv/{id}
Delete a contact list
Permanently deletes a contact list and all its contacts from both the source and the dialing queue.
**Warning:** This action is irreversible — all contacts and data in the list will be lost.
### Path Parameters
* **id** (*required*, string): The contact list ID returned from [Create a List](/api-reference/endpoint/create-list) or [Get All Contact Lists](/api-reference/endpoint/get-contact-lists).
### Response (200)
```json theme={null}
{
"success": true
}
```
### Errors
| Status | Description |
| ------ | ---------------------- |
| 404 | Contact list not found |
# Delete a Note
Source: https://docs.salesfinity.ai/api-reference/endpoint/delete-note
DELETE /v2/notes/{id}
Deletes an existing note. Only the original author may delete a note.
Deletes an existing note.
Only the **original author** may delete a note.
### Path Parameters
* **id** (*required*, string): Note ID, from [List Notes](/api-reference/endpoint/list-notes).
### Request Body
| Field | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------------------------------------------------------- |
| `user_id` | string | Yes | ID of the team member performing the delete. Must match the original author of the note. |
### Example Request
```json theme={null}
{
"user_id": "507f1f77bcf86cd799439033"
}
```
### Response (200)
```json theme={null}
{
"success": true
}
```
### Errors
| Status | Description |
| ------ | ------------------------------------ |
| 403 | Only the author can delete this note |
| 404 | Note not found |
# Delete Snoozed Contact
Source: https://docs.salesfinity.ai/api-reference/endpoint/delete-snoozed-contact
DELETE /v1/snoozed-contacts/{id}
Delete a snoozed contact
Removes a contact from the snoozed list, allowing them to appear in call lists again immediately.
### Path Parameters
* **id** (*required*, string): Snoozed contact ID
### Response
Returns a success message if deleted, or 404 if not found.
```json theme={null}
{
"message": "Snoozed contact deleted successfully"
}
```
# Delete Webhook
Source: https://docs.salesfinity.ai/api-reference/endpoint/delete-webhook
DELETE /v1/webhooks/{id}
Delete a webhook
Deletes a webhook by its ID. Once deleted, you will no longer receive notifications at the webhook URL.
### Path Parameters
* **id** (*required*, string): Webhook ID
### Response
Returns the deleted webhook object, or 404 if not found.
```json theme={null}
{
"_id": "507f1f77bcf86cd799439011",
"name": "CRM Call Sync",
"url": "https://example.com/webhooks/salesfinity",
"events": ["CALL_LOGGED"],
"status": "active"
}
```
# Request an Email Enrichment
Source: https://docs.salesfinity.ai/api-reference/endpoint/enrich-email
POST /v1/api/enrichment/email
Starts an asynchronous lookup of a work or personal email address for a LinkedIn profile. Returns immediately with a request `_id` and a `status` of `pending`; the result is delivered later either by polling `GET /v1/api/enrichment/email/{id}` or via the optional `callback_url` webhook. Each completed lookup costs 1 enrichment credit (charged only when an email is found). Requires a positive credit balance.
Starts an **asynchronous** lookup of a work or personal email address for a LinkedIn profile.
The call returns immediately with a request `_id` and a `status` of `pending`. The actual lookup runs in the background — collect the result either by [polling](/api-reference/endpoint/get-email-enrichment) the returned `_id`, or by providing a `callback_url` that we POST to when the lookup finishes.
Each **completed** lookup costs **1 enrichment credit**. Credits are charged only when an email is found (`status: "completed"`), never for `not-found`. The request is rejected with `402` if the team has no remaining credits — check your balance with [Get Enrichment Credits](/api-reference/endpoint/get-enrichment-credits).
### Request Body
| Field | Type | Required | Description |
| -------------- | ------------- | -------- | -------------------------------------------------------------------------------- |
| `linkedin_url` | string | Yes | LinkedIn profile URL. Must be a `linkedin.com/in/` URL. |
| `type` | string | Yes | Email type to find — `work` or `personal`. |
| `callback_url` | string (URL) | No | Webhook POSTed when the enrichment finishes. Retried up to 3 times with backoff. |
| `external_id` | string (≤256) | No | Opaque value echoed back in the callback for client-side correlation. |
### Example Request
```json theme={null}
{
"linkedin_url": "https://www.linkedin.com/in/janedoe",
"type": "work",
"callback_url": "https://example.com/webhooks/enrichment",
"external_id": "lead-42"
}
```
### Response (201)
```json theme={null}
{
"_id": "507f1f77bcf86cd799439011",
"status": "pending",
"linkedin_url": "https://www.linkedin.com/in/janedoe"
}
```
Persist the `_id` — it is the handle for polling and the identifier referenced in the callback.
### Callback payload
If you supplied a `callback_url`, we POST a JSON body to it once the lookup resolves:
```json theme={null}
{
"request_id": "507f1f77bcf86cd799439011",
"status": "completed",
"enrichment_type": "work_email",
"email": { "email": "jane@acme.com", "type": "work" },
"linkedin_url": "https://www.linkedin.com/in/janedoe",
"external_id": "lead-42"
}
```
`status` is `completed` (with `email`) or `not-found` (`email` is `null`). Delivery is attempted up to 3 times; if every attempt fails, fall back to polling.
### Errors
| Status | Description |
| ------ | ---------------------------------------------------------------------------------------------------------------- |
| 400 | Validation failed — `linkedin_url` is not a `linkedin.com/in/` URL, or `type` is not `work`/`personal` |
| 402 | Insufficient enrichment credits |
# Get Call Log by ID
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-call-log-by-id
GET /v1/call-log/{id}
Get a call log by ID
Retrieves a single call log entry by its ID.
### Path Parameters
* **id** (*required*, string): Call log ID
### Response
Returns the call log object matching the given ID, or 404 if not found.
```json theme={null}
{
"data": {
"_id": "507f1f77bcf86cd799439011",
"call_id": "call_abc123",
"outcome": "answered",
"direction": "outbound",
"answered_by": "human",
"duration": 180,
"to": "+1234567890",
"from": "+1987654321",
"disposition": {
"internal_id": 1,
"external_id": "meeting_set",
"external_name": "Meeting Set"
},
"contact": {
"first_name": "John",
"last_name": "Doe",
"company": "Acme Corp",
"email": "john@acme.com",
"title": "VP of Sales"
},
"contact_list": {
"_id": "507f1f77bcf86cd799439022",
"name": "Q1 Prospects"
},
"user": {
"_id": "507f1f77bcf86cd799439033",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@company.com"
},
"recording_url": "https://recordings.example.com/call_abc123.mp3",
"notes": "Great conversation, follow up next week",
"is_completed": true,
"started_at": "2024-01-15T14:30:00.000Z",
"ended_at": "2024-01-15T14:33:00.000Z",
"createdAt": "2024-01-15T14:33:00.000Z",
"updatedAt": "2024-01-15T14:33:00.000Z"
}
}
```
# Get a List by ID
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-contact-list-by-id
GET /v1/contact-lists/csv/{id}
Returns a single CSV contact list with all its contacts. Supports searching, sorting, and paginating contacts.
Returns a single CSV contact list with all its contacts. Supports searching, sorting, and paginating the contacts within the list.
### Path Parameters
* **id** (*required*, string): CSV contact list ID
### Query Parameters
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `search` | string | Search contacts by first name, last name, email, or company (case-insensitive) |
| `sort` | string | Sort contacts by field. Prefix with `-` for descending. Examples: `first_name`, `-company`, `priority` |
| `page` | number | Page number for contacts. Default: 1 |
| `limit` | number | Contacts per page. Default: 50 |
### Response
Returns the list metadata and a paginated array of contacts:
| Field | Type | Description |
| ---------- | ------ | ------------------------------------- |
| `_id` | string | Unique identifier of the contact list |
| `name` | string | Name of the list |
| `user` | string | ID of the user who owns the list |
| `contacts` | array | Array of contact objects |
Each contact object includes:
| Field | Type | Description |
| --------------- | ------ | -------------------- |
| `_id` | string | Contact ID |
| `first_name` | string | First name |
| `last_name` | string | Last name |
| `email` | string | Email address |
| `company` | string | Company name |
| `title` | string | Job title |
| `phone_numbers` | array | Phone numbers |
| `linkedin` | string | LinkedIn profile URL |
| `website` | string | Website URL |
| `notes` | string | Notes |
| `priority` | number | Priority |
| `timezone` | string | Timezone |
| `custom_fields` | array | Custom fields |
### Example Requests
```bash theme={null}
# Get a list with all contacts
GET /v1/contact-lists/csv/507f1f77bcf86cd799439011
# Search contacts by name
GET /v1/contact-lists/csv/507f1f77bcf86cd799439011?search=john
# Sort contacts by company, page 2
GET /v1/contact-lists/csv/507f1f77bcf86cd799439011?sort=company&page=2&limit=20
```
### Errors
| Status | Description |
| ------ | -------------------------- |
| 404 | CSV contact list not found |
# Get All Lists
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-contact-lists-csv
GET /v1/contact-lists/csv
Returns all CSV contact lists for the team with filtering, sorting, and pagination.
Returns all CSV contact lists for the team. This is the primary endpoint for listing your contact lists. Returns metadata only — use [Get List by ID](/api-reference/endpoint/get-contact-list-by-id) to see the contacts inside a list.
### Query Parameters
| Parameter | Type | Description |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------- |
| `search` | string | Search lists by name (case-insensitive) |
| `filters[user]` | string | Filter by user ID |
| `sort` | string | Sort by field. Prefix with `-` for descending. Default: `-createdAt`. Examples: `name`, `-updatedAt` |
| `page` | number | Page number. Default: 1 |
| `limit` | number | Items per page. Default: 10 |
### Response
Returns a paginated array of contact lists:
| Field | Type | Description |
| ---------------- | ------ | ------------------------------------- |
| `_id` | string | Unique identifier of the contact list |
| `name` | string | Name of the list |
| `user` | string | ID of the user who owns the list |
| `total_contacts` | number | Number of contacts in the list |
| `createdAt` | string | Date the list was created |
| `updatedAt` | string | Date the list was last updated |
### Example Requests
```bash theme={null}
# Get all lists
GET /v1/contact-lists/csv
# Search by name
GET /v1/contact-lists/csv?search=outbound
# Filter by user
GET /v1/contact-lists/csv?filters[user]=680edc0d1504192884a148e0
# Sort by name ascending
GET /v1/contact-lists/csv?sort=name
# Combine filters
GET /v1/contact-lists/csv?search=q2&filters[user]=680edc0d1504192884a148e0&sort=-createdAt&page=1&limit=20
```
# Get Custom Fields
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-custom-fields
GET /v1/custom-fields
Returns all custom field mappings configured for the team. Custom fields represent field mappings between Salesfinity and integrated CRM platforms.
Returns all custom field mappings configured for your team. Custom fields represent field mappings between Salesfinity and your integrated CRM platforms (Salesforce, HubSpot, etc.).
Each record contains the integration source and the mapped fields for contacts and leads.
### Response
Returns an array of custom field mapping records.
* `_id` - Unique identifier
* `source` - Integration source (e.g. `salesforce`, `hubspot`)
* `team` - Team ID
* `user` - User ID who configured the mapping
* `fields` - Array of contact field mappings
* `type` - Field category
* `field_type` - Data type of the field
* `internal_name` - Salesfinity field name
* `external_key` - CRM field key
* `external_name` - CRM field display name
* `lead_fields` - Array of lead field mappings (same structure as `fields`)
* `createdAt` - Creation timestamp
* `updatedAt` - Last update timestamp
# Get Disposition by ID
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-disposition-by-id
GET /v1/dispositions/{id}
Get a specific disposition by its internal ID
Retrieves a specific disposition by its ID.
### Path Parameters
* **id** (*required*, number): The internal disposition ID (1-14 for default dispositions, higher for custom)
### Response
Returns a JSON object containing the disposition details.
```json theme={null}
{
"data": {
"_id": "507f1f77bcf86cd799439011",
"id": 1,
"name": "Answered - Meeting Set",
"is_custom": false,
"is_required": true,
"category": "positive"
}
}
```
### Error Responses
* **404 Not Found**: Disposition with the specified ID does not exist
# Get Dispositions
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-dispositions
GET /v1/dispositions
Returns all dispositions available for the team, including default and custom dispositions
Retrieves all dispositions available for your team. Dispositions are call outcome categories used to classify the result of each call.
This endpoint returns both default dispositions (built-in) and any custom dispositions your team has created.
### Query Parameters
* **is\_custom** (*optional*, boolean): Filter by custom or default dispositions
* `true` - Only return custom dispositions
* `false` - Only return default dispositions
* **category** (*optional*, string): Filter by disposition category
* `positive` - Meeting set, referral, callback later, reach out in 6 months, send an email
* `negative` - Not interested, do not call again
* `neutral` - No longer with company, wrong contact
* `not_answered` - No answer, left voicemail, gatekeeper, bad number
* `cancelled` - Cancelled calls
### Response
Returns a JSON object containing an array of dispositions.
```json theme={null}
{
"data": [
{
"_id": "507f1f77bcf86cd799439011",
"id": 1,
"name": "Answered - Meeting Set",
"is_custom": false,
"is_required": true,
"category": "positive"
},
{
"_id": "507f1f77bcf86cd799439012",
"id": 2,
"name": "Answered - No Longer with Company",
"is_custom": false,
"is_required": false,
"category": "neutral"
}
]
}
```
### Response Fields
| Field | Type | Description |
| ------------- | ------- | -------------------------------------------- |
| `_id` | string | Unique identifier |
| `id` | number | Disposition ID (use for filtering call logs) |
| `name` | string | Human-readable disposition name |
| `is_custom` | boolean | Whether this is a custom disposition |
| `is_required` | boolean | Whether this disposition is required |
| `category` | string | Disposition category |
### Default Dispositions
| ID | Name | Category |
| -- | --------------------------------- | ------------- |
| 1 | Answered - Meeting Set | positive |
| 2 | Answered - No Longer with Company | neutral |
| 3 | Answered - Not Interested | negative |
| 4 | Answered - Referral | positive |
| 5 | Answered - Wrong Contact | neutral |
| 6 | Answered - Call back later | positive |
| 7 | Answered - Reach out in 6 months | positive |
| 8 | Answered - Send an email | positive |
| 9 | Answered - Do not call again | negative |
| 10 | No Answer | not\_answered |
| 11 | Left Voicemail | not\_answered |
| 12 | Gatekeeper | not\_answered |
| 13 | Bad Number | not\_answered |
| 14 | Cancelled | cancelled |
# Poll an Email Enrichment
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-email-enrichment
GET /v1/api/enrichment/email/{id}
Returns the current state of an email enrichment request. While the lookup is in progress `status` is `pending` or `processing`. When finished `status` is `completed` (with the found `email`) or `not-found` (no email available). Polling is a fallback for the callback and is safe to call repeatedly — a request is never charged twice.
Returns the current state of an email enrichment request created with [Request an Email Enrichment](/api-reference/endpoint/enrich-email).
Polling is the fallback for the `callback_url` webhook — it is safe to call repeatedly, and a request is **never charged twice** regardless of how often you poll.
### Path Parameters
| Parameter | Type | Description |
| --------- | ------ | ------------------------------------------------------------------- |
| `id` | string | The enrichment request `_id` returned when the request was created. |
### Status lifecycle
| Status | Meaning |
| ------------ | -------------------------------------------------------------------------- |
| `pending` | Accepted, not yet started. |
| `processing` | Lookup in progress. |
| `completed` | An email was found — see the `email` field. (1 credit charged.) |
| `not-found` | Lookup finished, no email available. `email` is `null`. No credit charged. |
| `failed` | The lookup could not be completed. |
### Response (200) — completed
```json theme={null}
{
"_id": "507f1f77bcf86cd799439011",
"status": "completed",
"enrichment_type": "work_email",
"email": { "email": "jane@acme.com", "type": "work" },
"linkedin_url": "https://www.linkedin.com/in/janedoe",
"external_id": "lead-42"
}
```
### Response (200) — still running
```json theme={null}
{
"_id": "507f1f77bcf86cd799439011",
"status": "processing",
"linkedin_url": "https://www.linkedin.com/in/janedoe"
}
```
### Errors
| Status | Description |
| ------ | ---------------------------------------------- |
| 404 | No enrichment request found for the given `id` |
# Get Enrichment Credits
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-enrichment-credits
GET /v1/api/enrichment/credits
Returns the current enrichment credit balance for the team that owns the API key. Each completed email enrichment costs 1 credit.
Returns the current enrichment credit balance for the team that owns the API key.
Each **completed** email enrichment costs **1 credit**. Use this endpoint to check available credits before kicking off enrichment requests — a request with a zero balance is rejected with `402 Payment Required`.
### Response (200)
```json theme={null}
{
"balance": 250
}
```
| Field | Type | Description |
| --------- | ------- | ---------------------------------------------------- |
| `balance` | integer | Number of enrichment credits remaining for the team. |
# Get Follow-up Tasks
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-follow-ups
GET /v1/follow-up
Returns all follow-up tasks for the team with pagination
Returns all follow-up tasks for the team with pagination support. Follow-up tasks are created after calls to track pending actions and reminders.
### Query Parameters
* **page** (*optional*, number): Page number for pagination. Default: 1
* **limit** (*optional*, number): Number of items per page. Min: 1, Max: 100
* **sort** (*optional*, string): Sort field(s). Prefix with "-" for descending order. Default: `-createdAt`
* Example: `follow_up_date,-priority`
### Response
Returns a paginated array of follow-up tasks with the following fields:
* `_id` - Unique identifier
* `team` - Team ID
* `user` - Assigned user
* `call_log` - Associated call log ID
* `contact` - Contact ID
* `company` - Company ID
* `priority` - Task priority: `high`, `medium`, or `low`
* `status` - Task status: `not_overdue`, `overdue`, or `completed`
* `follow_up_date` - Scheduled follow-up date
* `first_name` - Contact's first name
* `last_name` - Contact's last name
* `tags` - Array of tags: `timing`, `budget`, `competitor`
* `touches` - Number of contact attempts
* `context` - Additional context or notes
* `is_archived` - Whether the task is archived
* `createdAt` - Creation timestamp
* `updatedAt` - Last update timestamp
# Get Scored Call by ID
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-scored-call-by-id
GET /v1/scored-calls/{id}
Retrieves a single scored call by its ID with full AI-generated insight.
Retrieves a single scored call by its ID, including the full AI-generated insight with scoring facets, lead qualification, and coaching recommendations.
### Path Parameters
* **id** (*required*, string): Scored call ID
### Response
Returns the scored call object matching the given ID, or 404 if not found.
```json theme={null}
{
"data": {
"_id": "507f1f77bcf86cd799439011",
"insight": {
"total_score": 78,
"lead": {
"function": "Sales",
"tech_stack_mentioned": ["Salesforce", "Outreach"],
"current_vendor": "Competitor Inc",
"fit_score": 85,
"is_decision_maker": true,
"is_correct_persona": true,
"pain_point_resonated": true,
"is_qualified_meeting": true,
"is_likely_to_buy": false,
"prospect_lifecycle_stage": ["solution_aware"]
},
"messaging": {
"value_prop_resonated": ["efficiency", "time_savings"],
"objection_outcome": ["handled"],
"emotional_triggers": ["frustration_with_current_tool"],
"recommendation_to_nail_messaging": "Lead with ROI data specific to their industry"
},
"targeting_feedback": {
"persona_fit": "excellent",
"industry_fit": "good",
"persona_seniority": "vp",
"title_relevance": "good",
"data_quality_issue": [],
"future_follow_up_needed": true,
"follow_up_reason": ["renewal"]
},
"metadata": {
"duration_sec": 245,
"asr_confidence_avg": 0.92,
"audio_features_available": true,
"talk_listen_ratio_rep": 0.45,
"total_questions": 8,
"open_question_ratio": 0.625,
"interruptions_by_rep": 1,
"core_pitch_duration_sec": 35,
"estimated_wpm_rep": 155,
"objections_detected": ["budget"]
},
"facets": {
"intro": {
"score": 85,
"weight_pct": 10,
"explanation": "Strong permission-based opener",
"insufficient_evidence": false,
"checks": {
"permission_opener_used": true,
"opener_length_sec": 12,
"time_to_opener_sec": 3,
"improvement_recommendation": "Consider a more personalized opener"
}
},
"discovery": {
"score": 72,
"weight_pct": 25,
"explanation": "Good question quality but missed timing topic",
"insufficient_evidence": false,
"metrics": {
"total_questions": 8,
"open_question_ratio": 0.625,
"improvement_recommendation": "Ask about timeline and decision process",
"topic_coverage": ["pain", "current_tools"]
}
},
"pitch": {
"score": 80,
"weight_pct": 20,
"explanation": "Well-tailored pitch to discovery findings",
"insufficient_evidence": false,
"metrics": {
"core_pitch_duration_sec": 35,
"tailored_to_discovery": true,
"improvement_recommendation": "Include a customer success story",
"outcome_keywords": ["efficiency", "save_time"]
}
},
"tonality": {
"score": 75,
"weight_pct": 15,
"explanation": "Good pace, minor filler word usage",
"insufficient_evidence": false,
"metrics": {
"estimated_wpm": 155,
"interruptions_by_rep": 1,
"filler_density_per_min": 2.1,
"improvement_recommendation": "Reduce filler words"
}
},
"objection_handling": {
"score": 70,
"weight_pct": 15,
"explanation": "Addressed budget objection but no follow-up probe",
"insufficient_evidence": false,
"metrics": {
"objections_detected": ["budget"],
"followup_probe_present": false,
"resolution_check_present": true,
"improvement_recommendation": "Add a follow-up question after handling objections"
}
},
"cta": {
"score": 82,
"weight_pct": 15,
"explanation": "Clear CTA with specific time offered",
"insufficient_evidence": false,
"metrics": {
"cta_attempted": true,
"cta_type": "meeting",
"specific_time_offered": true,
"improvement_recommendation": "Confirm next steps via email",
"outcome": "accepted"
}
}
},
"gaps": {
"skill": 25,
"playbook": 15,
"rationale": "Discovery needs more depth on timing and decision process"
},
"coaching": {
"top_wins": ["Strong opener", "Good pitch tailoring"],
"top_opportunities": ["Deeper discovery", "Objection follow-up probes"],
"suggested_drills": [
{
"facet": "discovery",
"assignment": "Practice SPIN questions for uncovering timeline"
}
]
}
},
"call_log": {
"_id": "507f1f77bcf86cd799439022",
"contact": {
"first_name": "John",
"last_name": "Doe",
"company": "Acme Corp"
},
"recording_url": "https://recordings.example.com/call_abc123.mp3",
"duration": 245
},
"user": {
"_id": "507f1f77bcf86cd799439033",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@company.com"
},
"type": "call",
"createdAt": "2024-01-15T14:33:00.000Z",
"updatedAt": "2024-01-15T14:33:00.000Z"
}
}
```
# Get Sequence by ID
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-sequence-by-id
GET /v1/sequences/{id}
Get a specific sequence by ID
Retrieves a specific sequence by its ID with detailed statistics.
### Path Parameters
* **id** (*required*, string): The sequence ID
### Response
Returns a JSON object containing the sequence details.
```json theme={null}
{
"data": {
"id": "seq_12345",
"name": "Q1 Outbound Campaign",
"last_used_at": "2024-02-01T15:30:00.000Z",
"first_used_at": "2024-01-05T09:00:00.000Z",
"total_calls": 1250
}
}
```
### Error Responses
* **404 Not Found**: Sequence with the specified ID does not exist
# Get Sequences
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-sequences
GET /v1/sequences
Returns all sequences used in call logs for the team
Retrieves all sequences that have been used in call logs for your team. Sequences represent marketing/sales automation campaigns from integrated platforms like Outreach, Salesloft, etc.
Use this endpoint to discover sequence IDs for filtering call logs.
### Query Parameters
* **search** (*optional*, string): Search sequences by name
* **sort** (*optional*, string): Sort field and order. Default: `-last_used_at`
* `-last_used_at` - Most recently used first
* `last_used_at` - Oldest used first
* `-total_calls` - Most calls first
* `total_calls` - Fewest calls first
* `-name` - Name descending (Z-A)
* `name` - Name ascending (A-Z)
* **limit** (*optional*, number): Results per page (default: 100, max: 100)
* **page** (*optional*, number): Page number (default: 1)
### Response
Returns a JSON object containing an array of sequences with pagination.
```json theme={null}
{
"data": [
{
"id": "seq_12345",
"name": "Q1 Outbound Campaign",
"last_used_at": "2024-02-01T15:30:00.000Z",
"first_used_at": "2024-01-05T09:00:00.000Z",
"total_calls": 1250
},
{
"id": "seq_67890",
"name": "Enterprise Follow-up",
"last_used_at": "2024-01-28T10:15:00.000Z",
"first_used_at": "2024-01-10T14:00:00.000Z",
"total_calls": 430
}
],
"pagination": {
"total": 15,
"page": 1,
"limit": 100
}
}
```
### Response Fields
| Field | Type | Description |
| --------------- | ------ | --------------------------------------- |
| `id` | string | Sequence ID (from external integration) |
| `name` | string | Sequence name |
| `last_used_at` | date | Most recent call date in this sequence |
| `first_used_at` | date | First call date in this sequence |
| `total_calls` | number | Total calls made within this sequence |
# Get Snoozed Contact by ID
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-snoozed-contact-by-id
GET /v1/snoozed-contacts/{id}
Get a snoozed contact by ID
Retrieves a specific snoozed contact by its ID.
### Path Parameters
* **id** (*required*, string): Snoozed contact ID
### Response
Returns the snoozed contact if found, or 404 if not found.
**Response fields:**
* `_id` - Unique identifier
* `team` - Team ID
* `user` - User who snoozed the contact
* `contact_list` - Associated contact list ID
* `linkedin_username` - LinkedIn username
* `external_contact_id` - External CRM contact ID
* `email` - Email address
* `phone_number` - Phone number
* `snooze_until` - Date when snooze expires
* `createdAt` - Creation timestamp
* `updatedAt` - Last update timestamp
# Get Snoozed Contact by LinkedIn
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-snoozed-contact-by-linkedin
GET /v1/snoozed-contacts/by-linkedin/{username}
Get a snoozed contact by LinkedIn username
Retrieves a snoozed contact by their LinkedIn username. Useful for checking if a specific LinkedIn profile is currently snoozed.
### Path Parameters
* **username** (*required*, string): LinkedIn username to look up
### Response
Returns the snoozed contact if found, or 404 if not found.
**Response fields:**
* `_id` - Unique identifier
* `team` - Team ID
* `user` - User who snoozed the contact
* `linkedin_username` - LinkedIn username
* `external_contact_id` - External CRM contact ID
* `email` - Email address
* `phone_number` - Phone number
* `snooze_until` - Date when snooze expires
* `createdAt` - Creation timestamp
* `updatedAt` - Last update timestamp
# Get Snoozed Contacts
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-snoozed-contacts
GET /v1/snoozed-contacts
Returns all snoozed contacts for the team with pagination and filtering
Returns all snoozed contacts for the team with pagination and filtering support. Snoozed contacts are temporarily suppressed from call lists until their snooze period expires.
### Query Parameters
* **page** (*optional*, number): Page number for pagination. Default: 1
* **limit** (*optional*, number): Number of items per page. Min: 1, Max: 100
* **sort** (*optional*, string): Sort field(s). Prefix with "-" for descending order. Default: `-createdAt`
* **linkedin\_username** (*optional*, string): Filter by LinkedIn username
* **external\_contact\_id** (*optional*, string): Filter by external contact ID (e.g., CRM ID)
* **email** (*optional*, string): Filter by email address
* **phone\_number** (*optional*, string): Filter by phone number
### Response
Returns a paginated array of snoozed contacts with the following fields:
* `_id` - Unique identifier
* `team` - Team ID
* `user` - User who snoozed the contact
* `contact_list` - Associated contact list ID
* `linkedin_username` - LinkedIn username
* `external_contact_id` - External CRM contact ID
* `email` - Email address
* `phone_number` - Phone number
* `snooze_until` - Date when snooze expires
* `createdAt` - Creation timestamp
* `updatedAt` - Last update timestamp
# Get All Users
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-team
GET /v1/team
Returns team information
Retrieves details about the current team, including each team member's status, license, and relevant user data.
* **Tags**: `teams`
* **Response**: Team information and associated members.
# Get Webhook by ID
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-webhook-by-id
GET /v1/webhooks/{id}
Get a webhook by ID
Retrieves a single webhook by its ID.
### Path Parameters
* **id** (*required*, string): Webhook ID
### Response
Returns the webhook object, or 404 if not found.
```json theme={null}
{
"_id": "507f1f77bcf86cd799439011",
"name": "CRM Call Sync",
"url": "https://example.com/webhooks/salesfinity",
"events": ["CALL_LOGGED"],
"dispositions": [1, 4],
"status": "active",
"createdAt": "2024-01-15T10:00:00.000Z",
"updatedAt": "2024-01-15T10:00:00.000Z"
}
```
# Get Webhook Events
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-webhook-events
GET /v1/webhooks/events
Returns all available webhook event types
Returns a list of all available webhook event types and their descriptions. Use this endpoint to discover which events you can subscribe to when creating or updating a webhook.
### Response
Returns an array of event objects.
```json theme={null}
[
{
"event": "CALL_LOGGED",
"description": "Triggered when a user logs a call, capturing relevant call details."
},
{
"event": "CONTACT_SNOOZED",
"description": "Triggered when a contact is snoozed, capturing the contact and snooze details."
}
]
```
### Webhook delivery format
When an event fires, Salesfinity sends an HTTP `POST` to your configured webhook URL with a JSON body of the shape `{ "event": , "payload": }`.
#### `CALL_LOGGED` payload
```json theme={null}
{
"event": "CALL_LOGGED",
"payload": {
"_id": "6a3130af1ff24e60da9d1c34",
"call_id": "call_abc123",
"outcome": "answered",
"direction": "outbound",
"duration": 180,
"to": "+1234567890",
"from": "+1987654321",
"disposition": { "internal_id": 1, "external_name": "Meeting Set" },
"contact": { "first_name": "John", "last_name": "Doe", "company": "Acme Corp" },
"contact_list": "6a312e171ff24e60da9c4a52",
"contact_list_item": "6a312e171ff24e60da9c4973",
"source": {
"type": "csv",
"id": "6a312e181ff24e60da9c5048",
"name": "Coordinated Solutions (Month Campaign).csv"
},
"user": { "_id": "69e792fd2b95b13306e936ab", "first_name": "Jane", "last_name": "Smith", "email": "jane@company.com" }
}
}
```
`contact_list` is the **dialing-queue** list id (`ContactList._id`) — an internal id that changes each time a list is imported for dialing. `source` identifies the **original source list**: for CSV lists, `source.id` is the CSV list id you see in [Get All Lists](/api-reference/endpoint/get-contact-lists-csv) (`/v1/contact-lists/csv`), and `source.name` is its name. For non-CSV lists, `source.id`/`source.name` are `null` and only `source.type` (e.g. `hubspot`) is provided. Use `source.id` — not `contact_list` — to match a call back to the list you dialed.
You can filter `CALL_LOGGED` deliveries by disposition when creating the webhook (see [Create Webhook](/api-reference/endpoint/create-webhook)).
# Get Webhook Logs
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-webhook-logs
GET /v1/webhooks/{id}/logs
Get logs for a webhook
Retrieves delivery logs for a specific webhook. Use this endpoint to monitor webhook delivery status, debug failures, and inspect payloads.
### Path Parameters
* **id** (*required*, string): Webhook ID
### Query Parameters
* **limit** (*optional*, number): Number of items per page (default: 10, max: 100)
* **page** (*optional*, number): The current page number to retrieve (default: 1)
* **sort** (*optional*, string): Sort field with optional `-` prefix for descending order (default: `-createdAt`)
### Response
Returns a paginated list of webhook log entries.
```json theme={null}
{
"data": [
{
"_id": "507f1f77bcf86cd799439055",
"event": "CALL_LOGGED",
"status": "success",
"request": {
"body": {
"event": "CALL_LOGGED",
"payload": {
"call_id": "call_abc123",
"outcome": "answered",
"duration": 180
}
}
},
"response": {
"code": 200,
"body": { "received": true }
},
"responseTime": 245,
"createdAt": "2024-01-15T14:33:00.000Z"
}
],
"pagination": {
"total": 50,
"page": 1,
"limit": 10,
"pages": 5
}
}
```
### Response Fields
| Field | Type | Description |
| -------------- | ------ | -------------------------------------------------- |
| `_id` | string | Log entry ID |
| `event` | string | The event type that triggered this delivery |
| `status` | string | Delivery status (`success` or `failed`) |
| `request` | object | The request payload sent to the webhook URL |
| `response` | object | The response received (includes `code` and `body`) |
| `responseTime` | number | Response time in milliseconds |
| `createdAt` | date | When the delivery was attempted |
# Get All Webhooks
Source: https://docs.salesfinity.ai/api-reference/endpoint/get-webhooks
GET /v1/webhooks
Returns all webhooks for the team
Retrieves all webhooks configured for the current team.
### Response
Returns a list of webhook objects with pagination metadata.
```json theme={null}
{
"data": [
{
"_id": "507f1f77bcf86cd799439011",
"name": "CRM Call Sync",
"url": "https://example.com/webhooks/salesfinity",
"events": ["CALL_LOGGED"],
"status": "active"
},
{
"_id": "507f1f77bcf86cd799439022",
"name": "Snooze Notifications",
"url": "https://example.com/webhooks/snooze",
"events": ["CONTACT_SNOOZED"],
"status": "active"
}
],
"pagination": {
"total": 2,
"page": 1,
"limit": 10,
"pages": 1
}
}
```
### Response Fields
| Field | Type | Description |
| -------- | --------- | --------------------------------------- |
| `_id` | string | Webhook ID |
| `name` | string | Webhook name |
| `url` | string | Destination URL for webhook payloads |
| `events` | string\[] | Subscribed event types |
| `status` | string | Webhook status (`active` or `inactive`) |
# List Notes
Source: https://docs.salesfinity.ai/api-reference/endpoint/list-notes
GET /v2/notes
Looks up the person or company by the provided identifiers and returns the notes attached to it. Resolve-only: returns 404 if no matching record exists (nothing is created on read). Notes are sorted pinned first, then by createdAt descending. For a person, supply at least one of linkedin_url, email, crm_id, or phone. For a company, supply at least one of website_url or name.
Returns the notes attached to a **person** (Contact) or a **company** (Company), resolved from the identifiers you provide.
This is **resolve-only**: unlike [Create a Note](/api-reference/endpoint/create-note), it never creates a record. If no matching person or company exists, it returns `404`.
Notes come back sorted **pinned first**, then by `createdAt` descending.
### Query Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------------------------------- |
| `type` | string | Yes | `person` or `company`. Determines which identifier params are required. |
#### Person identifiers (`type=person`)
Supply **at least one** of `linkedin_url`, `email`, `crm_id`, or `phone`.
| Parameter | Type | Description |
| -------------- | ------ | ---------------------------- |
| `linkedin_url` | string | LinkedIn profile URL |
| `email` | string | Email address |
| `crm_id` | string | External CRM identifier |
| `phone` | string | Phone number in E.164 format |
#### Company identifiers (`type=company`)
Supply **at least one** of `website_url` or `name`.
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------- |
| `website_url` | string | Company website URL |
| `name` | string | Company name (case-insensitive) |
### Response
| Field | Type | Description |
| ------------ | -------------- | --------------------------------------------------------------------------------------------------- |
| `type` | string | Target type echoed from the request (`person` or `company`). |
| `contact_id` | string \| null | Resolved unified Contact ID. Present when `type=person`. Stable across reimports and dialer drains. |
| `company_id` | string \| null | Resolved unified Company ID. Present when `type=company`. |
| `notes` | array | Array of [note objects](#note-object), pinned first then by creation date descending. |
#### Note Object
| Field | Type | Description |
| ----------- | -------------- | ------------------------------------------------------------------------------------------------------------ |
| `_id` | string | Note ID |
| `team` | string | Team that owns the note |
| `author` | object | Author (`_id`, `first_name`, `last_name`, `email`, `image`). Populated when available; otherwise just `_id`. |
| `content` | string | Plain text content of the note |
| `is_pinned` | boolean | Whether the note is pinned to the top |
| `pinned_at` | string \| null | When the note was pinned (ISO 8601) |
| `pinned_by` | string \| null | ID of the member who pinned it |
| `contact` | string \| null | Contact this note is attached to (mutually exclusive with `company`) |
| `company` | string \| null | Company this note is attached to (mutually exclusive with `contact`) |
| `createdAt` | string | Creation timestamp (ISO 8601) |
| `updatedAt` | string | Last update timestamp (ISO 8601) |
### Example Request
```bash theme={null}
GET /v2/notes?type=person&email=john@example.com
```
### Errors
| Status | Description |
| ------ | ----------------------------------- |
| 404 | No matching person or company found |
# Merge Lists
Source: https://docs.salesfinity.ai/api-reference/endpoint/merge-lists
POST /v1/contact-lists/{id}/merge
Merges contacts from one or more source lists into the target list. Optionally deletes the source lists after merging.
Merges contacts from one or more source lists into a target list. Optionally deletes the source lists after merging.
This is useful when payload limits require creating multiple sub-lists that should logically be one list. Instead of leaving SDRs with fragmented lists in the dialer, merge them server-side into a single clean list.
### Path Parameters
* **id** (*required*, string): Target contact list ID to merge into.
### Request Body
| Field | Type | Required | Description |
| ----------------- | --------- | -------- | ------------------------------------------------------------------ |
| `source_list_ids` | string\[] | Yes | IDs of the source lists to merge into the target (1–20 lists) |
| `delete_sources` | boolean | No | Whether to delete the source lists after merging. Default: `false` |
### Limits
* Max **20** source lists per merge request
* The target list cannot appear in `source_list_ids` (it will be ignored)
### Example Request
```json theme={null}
{
"source_list_ids": [
"507f1f77bcf86cd799439011",
"507f1f77bcf86cd799439012",
"507f1f77bcf86cd799439013"
],
"delete_sources": true
}
```
### Response (201)
Returns the updated target contact list.
### Errors
| Status | Description |
| ------ | ----------------------------- |
| 404 | Target contact list not found |
# Pin or Unpin a Note
Source: https://docs.salesfinity.ai/api-reference/endpoint/pin-note
POST /v2/notes/{id}/pin
Toggles whether a note is pinned. Any team member may toggle a pin (not just the author). Pinned notes sort to the top.
Toggles whether a note is pinned. Pinned notes sort to the top of the list.
Unlike editing and deleting, **any team member** may toggle a pin — not just the author.
### Path Parameters
* **id** (*required*, string): Note ID, from [List Notes](/api-reference/endpoint/list-notes).
### Request Body
| Field | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------- |
| `user_id` | string | Yes | ID of the team member toggling the pin. Must be a member of the team that owns the API key. |
### Example Request
```json theme={null}
{
"user_id": "507f1f77bcf86cd799439033"
}
```
### Response (201)
Returns the updated [note object](/api-reference/endpoint/list-notes#note-object) with the new `is_pinned`, `pinned_at`, and `pinned_by` values.
### Errors
| Status | Description |
| ------ | -------------- |
| 404 | Note not found |
# Add the List to Dialing Queue
Source: https://docs.salesfinity.ai/api-reference/endpoint/reimport-contacts
POST /v1/contact-lists/csv/{id}/reimport
Reimport contacts from CSV
Reimports contacts from the source list back into the dialing queue. This replaces the current queue contents with the full source list.
Use this to reset a partially-dialed list back to its original state, or to push source changes into the active queue.
### Path Parameters
* **id** (*required*, string): Contact list ID.
### Response (201)
Returns the updated contact list.
### Errors
| Status | Description |
| ------ | -------------------------- |
| 404 | CSV contact list not found |
# Remove a Contact from a List
Source: https://docs.salesfinity.ai/api-reference/endpoint/remove-contact
DELETE /v1/contact-lists/{id}/contacts/{contactId}
Remove a contact from a contact list
Removes a contact from an existing contact list. The contact is removed from both the source list and the dialing queue.
### Path Parameters
* **id** (*required*, string): Contact list ID.
* **contactId** (*required*, string): ID of the contact to remove.
### Response (200)
```json theme={null}
{
"success": true
}
```
### Errors
| Status | Description |
| ------ | ---------------------- |
| 404 | Contact list not found |
# Retrieve Scored Calls
Source: https://docs.salesfinity.ai/api-reference/endpoint/scored-calls
GET /v1/scored-calls
Retrieves a paginated list of AI-scored calls with detailed insights, scoring facets, lead qualification, and coaching recommendations.
Retrieves a paginated list of AI-scored calls. Each scored call includes detailed insights across six scoring facets (intro, discovery, pitch, tonality, objection handling, CTA), lead qualification data, coaching recommendations, and an overall score.
### Query Parameters
#### Pagination & Sorting
* **limit** (*optional*, number): Number of items per page (default: 10, max: 100)
* **page** (*optional*, number): The current page number to retrieve (default: 1)
* **sort** (*optional*, string): Sort field with optional `-` prefix for descending order (default: `-createdAt`)
#### Filters
* **start\_date** (*optional*, ISO 8601 date): Start of date range
* **end\_date** (*optional*, ISO 8601 date): End of date range
* **min\_score** (*optional*, number): Minimum total score (0-100)
* **max\_score** (*optional*, number): Maximum total score (0-100)
* **user\_id** (*optional*, string): Filter by user ID
### Example Requests
**Basic request:**
```
GET /v1/scored-calls?page=1&limit=10
```
**Filter by date range:**
```
GET /v1/scored-calls?start_date=2024-01-01&end_date=2024-01-31
```
**Filter by score range:**
```
GET /v1/scored-calls?min_score=70&max_score=100
```
**Filter by user and date:**
```
GET /v1/scored-calls?user_id=507f1f77bcf86cd799439033&start_date=2024-01-01&end_date=2024-01-31
```
### Response
Returns a JSON object containing the list of scored calls with pagination metadata.
```json theme={null}
{
"data": [
{
"_id": "507f1f77bcf86cd799439011",
"insight": {
"total_score": 78,
"lead": {
"function": "Sales",
"tech_stack_mentioned": ["Salesforce", "Outreach"],
"current_vendor": "Competitor Inc",
"fit_score": 85,
"is_decision_maker": true,
"is_correct_persona": true,
"pain_point_resonated": true,
"is_qualified_meeting": true,
"is_likely_to_buy": false,
"prospect_lifecycle_stage": ["solution_aware"]
},
"messaging": {
"value_prop_resonated": ["efficiency", "time_savings"],
"objection_outcome": ["handled"],
"emotional_triggers": ["frustration_with_current_tool"],
"recommendation_to_nail_messaging": "Lead with ROI data specific to their industry"
},
"targeting_feedback": {
"persona_fit": "excellent",
"industry_fit": "good",
"persona_seniority": "vp",
"title_relevance": "good",
"data_quality_issue": [],
"future_follow_up_needed": true,
"follow_up_reason": ["renewal"]
},
"metadata": {
"duration_sec": 245,
"asr_confidence_avg": 0.92,
"audio_features_available": true,
"talk_listen_ratio_rep": 0.45,
"total_questions": 8,
"open_question_ratio": 0.625,
"interruptions_by_rep": 1,
"core_pitch_duration_sec": 35,
"estimated_wpm_rep": 155,
"objections_detected": ["budget"]
},
"facets": {
"intro": {
"score": 85,
"weight_pct": 10,
"explanation": "Strong permission-based opener",
"insufficient_evidence": false,
"checks": {
"permission_opener_used": true,
"opener_length_sec": 12,
"time_to_opener_sec": 3,
"improvement_recommendation": "Consider a more personalized opener"
}
},
"discovery": {
"score": 72,
"weight_pct": 25,
"explanation": "Good question quality but missed timing topic",
"insufficient_evidence": false,
"metrics": {
"total_questions": 8,
"open_question_ratio": 0.625,
"improvement_recommendation": "Ask about timeline and decision process",
"topic_coverage": ["pain", "current_tools"]
}
},
"pitch": {
"score": 80,
"weight_pct": 20,
"explanation": "Well-tailored pitch to discovery findings",
"insufficient_evidence": false,
"metrics": {
"core_pitch_duration_sec": 35,
"tailored_to_discovery": true,
"improvement_recommendation": "Include a customer success story",
"outcome_keywords": ["efficiency", "save_time"]
}
},
"tonality": {
"score": 75,
"weight_pct": 15,
"explanation": "Good pace, minor filler word usage",
"insufficient_evidence": false,
"metrics": {
"estimated_wpm": 155,
"interruptions_by_rep": 1,
"filler_density_per_min": 2.1,
"improvement_recommendation": "Reduce filler words"
}
},
"objection_handling": {
"score": 70,
"weight_pct": 15,
"explanation": "Addressed budget objection but no follow-up probe",
"insufficient_evidence": false,
"metrics": {
"objections_detected": ["budget"],
"followup_probe_present": false,
"resolution_check_present": true,
"improvement_recommendation": "Add a follow-up question after handling objections"
}
},
"cta": {
"score": 82,
"weight_pct": 15,
"explanation": "Clear CTA with specific time offered",
"insufficient_evidence": false,
"metrics": {
"cta_attempted": true,
"cta_type": "meeting",
"specific_time_offered": true,
"improvement_recommendation": "Confirm next steps via email",
"outcome": "accepted"
}
}
},
"gaps": {
"skill": 25,
"playbook": 15,
"rationale": "Discovery needs more depth on timing and decision process"
},
"coaching": {
"top_wins": ["Strong opener", "Good pitch tailoring"],
"top_opportunities": ["Deeper discovery", "Objection follow-up probes"],
"suggested_drills": [
{
"facet": "discovery",
"assignment": "Practice SPIN questions for uncovering timeline"
}
]
}
},
"call_log": {
"_id": "507f1f77bcf86cd799439022",
"contact": {
"first_name": "John",
"last_name": "Doe",
"company": "Acme Corp"
},
"recording_url": "https://recordings.example.com/call_abc123.mp3",
"duration": 245
},
"user": {
"_id": "507f1f77bcf86cd799439033",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@company.com"
},
"type": "call",
"createdAt": "2024-01-15T14:33:00.000Z",
"updatedAt": "2024-01-15T14:33:00.000Z"
}
],
"pagination": {
"total": 42,
"page": 1,
"limit": 10,
"pages": 5
}
}
```
### Response Fields
| Field | Type | Description |
| ----------- | ------ | -------------------------------------------------------------- |
| `_id` | string | Unique identifier for the scored call |
| `insight` | object | Full scoring insight (see below) |
| `call_log` | object | Associated call log with contact, recording\_url, and duration |
| `user` | object | User who made the call |
| `type` | string | Scoring type (`call`) |
| `createdAt` | date | Record creation time |
| `updatedAt` | date | Record last update time |
#### Insight Object
| Field | Type | Description |
| -------------------- | ------ | ----------------------------------------------------------------------------- |
| `total_score` | number | Overall call score (0-100) |
| `lead` | object | Lead qualification data (fit\_score, decision\_maker, lifecycle stage) |
| `messaging` | object | Messaging effectiveness (value props, objection outcomes, emotional triggers) |
| `targeting_feedback` | object | Persona and industry fit assessment |
| `metadata` | object | Call characteristics (duration, talk ratio, questions, speech rate) |
| `facets` | object | Six scoring categories with individual scores and evidence |
| `gaps` | object | Skill and playbook gap scores with rationale |
| `coaching` | object | Top wins, opportunities, and suggested drills |
#### Scoring Facets
| Facet | Weight | Description |
| -------------------- | ------ | -------------------------------------------------------- |
| `intro` | 10% | Permission opener usage and effectiveness |
| `discovery` | 25% | Question quality, open question ratio, topic coverage |
| `pitch` | 20% | Pitch duration, tailoring to discovery, outcome keywords |
| `tonality` | 15% | Speech rate, interruptions, filler word density |
| `objection_handling` | 15% | Objection detection, follow-up probes, resolution |
| `cta` | 15% | CTA attempt, type, specificity, and outcome |
# Update a Note
Source: https://docs.salesfinity.ai/api-reference/endpoint/update-note
PATCH /v2/notes/{id}
Updates the content of an existing note. Only the original author may edit a note.
Updates the content of an existing note.
Only the **original author** may edit a note.
### Path Parameters
* **id** (*required*, string): Note ID, from [List Notes](/api-reference/endpoint/list-notes).
### Request Body
| Field | Type | Required | Max Length | Description |
| --------- | ------ | -------- | ---------- | ---------------------------------------------------------------------------------------- |
| `content` | string | Yes | 10,000 | Updated plain text content of the note |
| `user_id` | string | Yes | — | ID of the team member performing the update. Must match the original author of the note. |
### Example Request
```json theme={null}
{
"content": "Updated: confirmed budget approved for Q3.",
"user_id": "507f1f77bcf86cd799439033"
}
```
### Response (200)
Returns the updated [note object](/api-reference/endpoint/list-notes#note-object).
### Errors
| Status | Description |
| ------ | ---------------------------------- |
| 403 | Only the author can edit this note |
| 404 | Note not found |
# Update Snoozed Contact
Source: https://docs.salesfinity.ai/api-reference/endpoint/update-snoozed-contact
PUT /v1/snoozed-contacts/{id}
Update a snoozed contact
Updates a snoozed contact's information, including extending or modifying the snooze period.
### Path Parameters
* **id** (*required*, string): Snoozed contact ID
### Request Body
All fields are optional. Only provided fields will be updated.
* **linkedin\_username** (*optional*, string): LinkedIn username
* **external\_contact\_id** (*optional*, string): External CRM contact ID
* **email** (*optional*, string): Email address
* **phone\_number** (*optional*, string): Phone number
* **snooze\_until** (*optional*, date): New snooze expiration date (ISO 8601 format)
* Example: `2024-06-15T00:00:00.000Z`
### Response
Returns the updated snoozed contact, or 404 if not found.
# Update Webhook
Source: https://docs.salesfinity.ai/api-reference/endpoint/update-webhook
PUT /v1/webhooks/{id}
Update a webhook
Updates an existing webhook configuration.
### Path Parameters
* **id** (*required*, string): Webhook ID
### Request Body
| Field | Type | Required | Description |
| -------------- | --------- | -------- | ----------------------------------------------------------------------- |
| `name` | string | Yes | A descriptive name for the webhook |
| `url` | string | Yes | The URL to receive webhook POST requests (must be a valid URL) |
| `events` | string\[] | Yes | Array of event types to subscribe to (`CALL_LOGGED`, `CONTACT_SNOOZED`) |
| `dispositions` | number\[] | No | Filter `CALL_LOGGED` events by disposition IDs |
### Example Request
```json theme={null}
{
"name": "Updated CRM Sync",
"url": "https://example.com/webhooks/v2/salesfinity",
"events": ["CALL_LOGGED", "CONTACT_SNOOZED"],
"dispositions": []
}
```
### Response
Returns the updated webhook object, or 404 if not found.
```json theme={null}
{
"_id": "507f1f77bcf86cd799439011",
"name": "Updated CRM Sync",
"url": "https://example.com/webhooks/v2/salesfinity",
"events": ["CALL_LOGGED", "CONTACT_SNOOZED"],
"dispositions": [],
"status": "active",
"createdAt": "2024-01-15T10:00:00.000Z",
"updatedAt": "2024-01-20T14:00:00.000Z"
}
```
# Introduction
Source: https://docs.salesfinity.ai/api-reference/introduction
Get started with Salesfinity API
If you need help with anything, feel free to email us at [hello@salesfinity.co](mailto:hello@salesfinity.co) or visit help center at [https://support.salesfinity.ai/](https://support.salesfinity.ai/)
## Welcome
To get your API key, please go to: [Settings](https://preview.salesfinity.co/dashboard/settings) and head over to Connections & API and generate a new API key.
Open Salesfinity Settings Page.
## Authentication
All API endpoints are authenticated using API keys. Example curl request
```json theme={null}
curl --location 'https://client-api.salesfinity.co/v1/contact-lists/csv?page=1' \
--header 'x-api-key: my_api_key'
```
# Connect to Claude.ai
Source: https://docs.salesfinity.ai/mcp/claude-ai
Set up Salesfinity MCP on Claude.ai desktop and web apps
Connect Salesfinity to Claude.ai to manage your sales data through natural conversation. Setup takes under a minute.
One-click setup — opens Claude.ai with the Salesfinity connector pre-filled.
## Video walkthrough
## Prerequisites
* A [Claude Pro, Team, or Enterprise](https://claude.ai/upgrade) subscription (MCP integrations require a paid plan)
* A Salesfinity API key — generate one in [Settings → Connections & API](https://preview.salesfinity.co/dashboard/settings)
## Step-by-step setup
Go to [claude.ai](https://claude.ai) and click on your profile icon in the bottom-left corner, then select **Settings**.
In the settings panel, click **Integrations** in the sidebar. You'll see a section for MCP integrations.
Click **Add more integrations**, then enter the MCP server URL:
```
https://mcp.salesfinity.ai/mcp
```
You'll be redirected to the Salesfinity authorization page. Enter your API key and click **Connect**.
Your API key is securely exchanged for an OAuth token. Salesfinity never stores your key on the MCP server.
Return to Claude and start a new conversation. The Salesfinity tools are now available. Try asking:
*"Show me all my contact lists"*
## Verifying the connection
After setup, you can verify the integration is working by looking for the Salesfinity icon in the tools section at the bottom of the Claude chat input. You can also ask Claude:
*"Can you check my Salesfinity connection by getting my team info?"*
Claude will call the `get_team` tool and display your team details.
## Troubleshooting
| Issue | Solution |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| "Unauthorized" error | Your API key may be invalid or expired. Generate a new one in [Settings](https://preview.salesfinity.co/dashboard/settings) and re-authorize. |
| Tools not appearing | Make sure the integration shows as "Connected" in Claude Settings → Integrations. Try removing and re-adding it. |
| "Invalid API Key" on auth page | Double-check you're using an API key from the Connections & API section, not another credential. |
Need help? Email us at [hello@salesfinity.co](mailto:hello@salesfinity.co) or visit the [Help Center](https://support.salesfinity.ai).
# Connect to Claude Code
Source: https://docs.salesfinity.ai/mcp/claude-code
Set up Salesfinity MCP in the Claude Code CLI
Use Salesfinity directly from your terminal with [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
## Setup
Add the Salesfinity MCP server to your Claude Code configuration:
```bash theme={null}
claude mcp add salesfinity \
--transport streamable-http \
https://mcp.salesfinity.ai/mcp
```
The first time you use a Salesfinity tool, Claude Code will open the OAuth authorization page in your browser. Enter your API key to connect.
## Verify the connection
```bash theme={null}
claude
> Can you get my team info from Salesfinity?
```
## Example usage
```bash theme={null}
# Ask about your contact lists
> Show me all my contact lists sorted by name
# Create a list
> Create a contact list called "Demo Prospects" with user_id 680edc0d1504192884a148e0
# Check analytics
> What's my team's call performance for the last 7 days?
# Search call logs
> Show me all answered calls from this week with recordings
```
## Configuration file
If you prefer to edit the config file directly, add this to your `~/.claude.json` or project `.claude.json`:
```json theme={null}
{
"mcpServers": {
"salesfinity": {
"type": "streamable-http",
"url": "https://mcp.salesfinity.ai/mcp"
}
}
}
```
# Other MCP Clients
Source: https://docs.salesfinity.ai/mcp/other-clients
Connect Salesfinity to Cursor, Windsurf, and other MCP-compatible clients
The Salesfinity MCP server works with any client that supports the [Model Context Protocol](https://modelcontextprotocol.io). Below are setup instructions for popular clients.
## Server details
| Field | Value |
| --------------------- | -------------------------------------------- |
| **Server URL** | `https://mcp.salesfinity.ai/mcp` |
| **Transport** | Streamable HTTP |
| **Authentication** | OAuth 2.0 (Authorization Code flow) |
| **Authorization URL** | `https://mcp.salesfinity.ai/oauth/authorize` |
| **Token URL** | `https://mcp.salesfinity.ai/oauth/token` |
## Cursor
Add to your Cursor MCP settings (`.cursor/mcp.json` in your project or global config):
```json theme={null}
{
"mcpServers": {
"salesfinity": {
"url": "https://mcp.salesfinity.ai/mcp"
}
}
}
```
Open the Cursor settings UI, navigate to **MCP**, and verify the Salesfinity server shows as connected.
## Windsurf
Add to your Windsurf MCP configuration (`~/.codeium/windsurf/mcp_config.json`):
```json theme={null}
{
"mcpServers": {
"salesfinity": {
"serverUrl": "https://mcp.salesfinity.ai/mcp"
}
}
}
```
## Generic MCP client
For any MCP-compatible client, use these connection details:
* **Transport type**: Streamable HTTP
* **Endpoint**: `https://mcp.salesfinity.ai/mcp`
* **Auth**: The server supports OAuth 2.0 discovery via `/.well-known/oauth-authorization-server`
The OAuth flow will prompt you to enter your Salesfinity API key on first connection.
Client configuration varies — check your specific client's documentation for the exact format. The server URL and transport type are the same across all clients.
# MCP Overview
Source: https://docs.salesfinity.ai/mcp/overview
Connect Salesfinity to Claude AI and other MCP-compatible clients
The Salesfinity MCP (Model Context Protocol) server lets AI assistants like Claude interact directly with your Salesfinity account — managing contact lists, reviewing call logs, analyzing performance, and more — all through natural language.
One-click setup — opens Claude.ai with the Salesfinity connector pre-filled. Requires a Claude Pro, Team, or Enterprise plan.
## What is MCP?
[Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that lets AI applications securely connect to external tools and data sources. Instead of copy-pasting data between Salesfinity and your AI assistant, MCP gives the assistant direct access to your Salesfinity data.
## What can you do with Salesfinity MCP?
Create lists, add or remove contacts, search and filter across all your lists
Get analytics overviews, SDR performance breakdowns, and list-level metrics
Search and filter call logs, view AI-scored calls with coaching recommendations
Create, update, and monitor webhook subscriptions and delivery logs
### Example prompts
Once connected, you can ask Claude things like:
* *"Show me all my contact lists"*
* *"Create a new list called Q2 Outbound with these 5 contacts..."*
* *"How many calls did my team make last week? What was the connect rate?"*
* *"Show me the top-performing SDRs this month"*
* *"Which contact lists have the highest answer rates?"*
* *"Show me all AI-scored calls below 50 from last week"*
* *"Set up a webhook to notify me on Slack when a call is logged"*
## Available tools
The MCP server exposes the following tools to AI assistants:
| Tool | Description |
| --------------------------------- | ----------------------------------------------------------------- |
| `get_contact_lists` | List all contact lists with search, filtering, and sorting |
| `get_contact_list_by_id` | Get a single list with all contacts, search, sort, and pagination |
| `create_contact_list` | Create a new contact list with contacts |
| `add_contact_to_list` | Add a contact to an existing list |
| `remove_contact_from_list` | Remove a contact from a list |
| `delete_contact_list` | Permanently delete a contact list |
| `reimport_contacts` | Reimport contacts to the dialing queue |
| `get_team` | Get team info and members |
| `get_call_logs` | Search and filter call logs |
| `get_call_log_by_id` | Get a specific call log |
| `get_scored_calls` | List AI-scored calls with filters |
| `get_scored_call_by_id` | Get a scored call with full AI analysis |
| `get_dispositions` | List all call dispositions |
| `get_disposition_by_id` | Get a specific disposition |
| `get_sequences` | List all sequences |
| `get_sequence_by_id` | Get a specific sequence |
| `get_snoozed_contacts` | List snoozed contacts with filters |
| `get_snoozed_contact_by_id` | Get a snoozed contact |
| `get_snoozed_contact_by_linkedin` | Look up snoozed contact by LinkedIn |
| `update_snoozed_contact` | Update a snoozed contact |
| `delete_snoozed_contact` | Remove a contact from the snooze list |
| `get_follow_ups` | List follow-up tasks |
| `get_custom_fields` | Get custom field definitions |
| `get_analytics_overview` | Aggregated metrics with growth rates |
| `get_list_performance` | Performance metrics by contact list |
| `get_sdr_performance` | Performance metrics by SDR |
| `create_webhook` | Create a webhook subscription |
| `get_webhooks` | List all webhooks |
| `get_webhook_by_id` | Get a specific webhook |
| `update_webhook` | Update a webhook |
| `delete_webhook` | Delete a webhook |
| `get_webhook_events` | List available webhook event types |
| `get_webhook_logs` | Get delivery logs for a webhook |
## Next steps
Step-by-step setup for Claude.ai (Desktop & Web)
Setup for Claude Code CLI
Cursor, Windsurf, and other MCP-compatible clients
Detailed documentation for every MCP tool
# Tool Reference
Source: https://docs.salesfinity.ai/mcp/tools
Detailed documentation for every Salesfinity MCP tool
This page documents every tool available through the Salesfinity MCP server, including parameters, behavior, and usage tips.
## Contact Lists
### get\_contact\_lists
List all contact lists for your team. Returns metadata only — use `get_contact_list_by_id` to see the contacts inside a list.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------------------------------------------- |
| `search` | string | No | Search lists by name (case-insensitive) |
| `user` | string | No | Filter by user ID |
| `sort` | string | No | Sort by field. Prefix with `-` for descending. Default: `-createdAt` |
| `page` | number | No | Page number (default 1) |
| `limit` | number | No | Items per page (default 10, max 100) |
***
### get\_contact\_list\_by\_id
Get a single contact list with all its contacts. Supports searching, sorting, and paginating the contacts within the list.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------------------- |
| `id` | string | Yes | Contact list ID |
| `search` | string | No | Search contacts by first name, last name, email, or company |
| `sort` | string | No | Sort contacts by field. Prefix with `-` for descending |
| `page` | number | No | Page number for contacts (default 1) |
| `limit` | number | No | Contacts per page (default 50) |
***
### create\_contact\_list
Create a new contact list with contacts. Maximum 2,000 contacts per list.
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ---------------------------------------------------------------- |
| `name` | string | Yes | List name (1–100 characters) |
| `user_id` | string | Yes | User ID who will own this list |
| `contacts` | array | Yes | Array of contact objects (see [Contact object](#contact-object)) |
***
### add\_contact\_to\_list
Add a single contact to an existing list. After adding, call `reimport_contacts` to include them in the dialing queue.
| Parameter | Type | Required | Description |
| ------------------ | ------ | -------- | ------------------------------------- |
| `list_id` | string | Yes | Contact list ID |
| All contact fields | — | — | See [Contact object](#contact-object) |
***
### remove\_contact\_from\_list
Remove a contact from a list.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | -------------------- |
| `list_id` | string | Yes | Contact list ID |
| `contact_id` | string | Yes | Contact ID to remove |
***
### delete\_contact\_list
Permanently delete a contact list and all its contacts. This action is irreversible.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------- |
| `list_id` | string | Yes | Contact list ID to delete |
***
### reimport\_contacts
Reimport contacts from the source list to the dialing queue. Call this after adding contacts to make them available for dialing.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------- |
| `list_id` | string | Yes | Contact list ID to reimport |
***
## Team
### get\_team
Get team information including all team members. Takes no parameters.
***
## Call Logs
### get\_call\_logs
Search and filter call logs with extensive filtering options.
| Parameter | Type | Required | Description |
| ------------------------------- | --------- | -------- | ------------------------------------------------------- |
| `page` | number | No | Page number (default 1) |
| `limit` | number | No | Items per page (1–100, default 10) |
| `sort` | string | No | Sort field. Default: `-createdAt` |
| `start_date` | string | No | Filter start date (ISO 8601) |
| `end_date` | string | No | Filter end date (ISO 8601) |
| `outcome` | string | No | Filter by outcome: `answered`, `no-answer`, `cancelled` |
| `direction` | string | No | Filter by direction: `inbound`, `outbound` |
| `min_duration` | number | No | Minimum call duration (seconds) |
| `max_duration` | number | No | Maximum call duration (seconds) |
| `has_recording` | boolean | No | Filter by recording availability |
| `answered_by` | string | No | Filter by who answered: `human`, `machine_start` |
| `is_completed` | boolean | No | Filter by completion status |
| `disposition_ids` | number\[] | No | Filter by disposition IDs |
| `exclude_negative_dispositions` | boolean | No | Only return positive dispositions |
| `user_ids` | string\[] | No | Filter by user IDs |
| `contact_list_ids` | string\[] | No | Filter by contact list IDs |
| `sequences` | string\[] | No | Filter by sequence IDs |
| `search` | string | No | Full-text search across contact name, company, phone |
***
### get\_call\_log\_by\_id
Get a specific call log by its ID.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| `id` | string | Yes | Call log ID |
***
## Scored Calls
### get\_scored\_calls
List AI-scored calls with insights, scoring facets, and coaching recommendations.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------------------- |
| `page` | number | No | Page number (default 1) |
| `limit` | number | No | Items per page (1–100, default 10) |
| `sort` | string | No | Sort field. Default: `-createdAt` |
| `start_date` | string | No | Filter start date (ISO 8601) |
| `end_date` | string | No | Filter end date (ISO 8601) |
| `min_score` | number | No | Minimum total score (0–100) |
| `max_score` | number | No | Maximum total score (0–100) |
| `user_id` | string | No | Filter by user ID |
***
### get\_scored\_call\_by\_id
Get a specific scored call with full AI-generated insight, facets, and recommendations.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------- |
| `id` | string | Yes | Scored call ID |
***
## Dispositions
### get\_dispositions
Get all available call dispositions for the team. Takes no parameters.
***
### get\_disposition\_by\_id
Get a specific disposition by ID.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------- |
| `id` | string | Yes | Disposition ID |
***
## Sequences
### get\_sequences
List all sequences with pagination.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------ |
| `page` | number | No | Page number (default 1) |
| `limit` | number | No | Items per page (default 10, max 100) |
***
### get\_sequence\_by\_id
Get a specific sequence by ID.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| `id` | string | Yes | Sequence ID |
***
## Snoozed Contacts
### get\_snoozed\_contacts
List snoozed contacts with filtering.
| Parameter | Type | Required | Description |
| --------------------- | ------ | -------- | ------------------------------------ |
| `page` | number | No | Page number (default 1) |
| `limit` | number | No | Items per page (default 10, max 100) |
| `sort` | string | No | Sort field |
| `linkedin_username` | string | No | Filter by LinkedIn username |
| `external_contact_id` | string | No | Filter by external CRM contact ID |
| `email` | string | No | Filter by email |
| `phone_number` | string | No | Filter by phone number |
***
### get\_snoozed\_contact\_by\_id
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------ |
| `id` | string | Yes | Snoozed contact ID |
***
### get\_snoozed\_contact\_by\_linkedin
Look up a snoozed contact by LinkedIn username.
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ----------------- |
| `username` | string | Yes | LinkedIn username |
***
### update\_snoozed\_contact
Update a snoozed contact's details or extend the snooze duration.
| Parameter | Type | Required | Description |
| --------------------- | ------ | -------- | -------------------------------- |
| `id` | string | Yes | Snoozed contact ID |
| `linkedin_username` | string | No | LinkedIn username |
| `external_contact_id` | string | No | External CRM contact ID |
| `email` | string | No | Email address |
| `phone_number` | string | No | Phone number |
| `snooze_until` | string | No | New snooze expiration (ISO 8601) |
***
### delete\_snoozed\_contact
Remove a contact from the snooze list, allowing them to appear in call lists again.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------ |
| `id` | string | Yes | Snoozed contact ID |
***
## Follow-up Tasks
### get\_follow\_ups
List follow-up tasks with pagination.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------ |
| `page` | number | No | Page number (default 1) |
| `limit` | number | No | Items per page (default 10, max 100) |
| `sort` | string | No | Sort field |
***
## Custom Fields
### get\_custom\_fields
Get all custom field definitions configured for the team. Use these when adding contacts with custom fields. Takes no parameters.
***
## Analytics
### get\_analytics\_overview
Get aggregated metrics with growth rates compared to the previous period.
| Parameter | Type | Required | Description |
| ----------------- | --------- | -------- | ------------------------- |
| `start_date` | string | Yes | Start date (ISO 8601) |
| `end_date` | string | Yes | End date (ISO 8601) |
| `user_ids` | string\[] | No | Filter by user IDs |
| `disposition_ids` | string\[] | No | Filter by disposition IDs |
***
### get\_list\_performance
Performance metrics grouped by contact list.
| Parameter | Type | Required | Description |
| ----------------- | --------- | -------- | ------------------------------------ |
| `start_date` | string | Yes | Start date (ISO 8601) |
| `end_date` | string | Yes | End date (ISO 8601) |
| `user_ids` | string\[] | No | Filter by user IDs |
| `disposition_ids` | string\[] | No | Filter by disposition IDs |
| `page` | number | No | Page number (default 1) |
| `limit` | number | No | Items per page (default 10, max 100) |
| `search` | string | No | Search by list name |
***
### get\_sdr\_performance
Performance metrics grouped by SDR.
| Parameter | Type | Required | Description |
| ----------------- | --------- | -------- | ------------------------------------ |
| `start_date` | string | Yes | Start date (ISO 8601) |
| `end_date` | string | Yes | End date (ISO 8601) |
| `user_ids` | string\[] | No | Filter by user IDs |
| `disposition_ids` | string\[] | No | Filter by disposition IDs |
| `page` | number | No | Page number (default 1) |
| `limit` | number | No | Items per page (default 10, max 100) |
| `search` | string | No | Search by SDR name or email |
***
## Webhooks
### create\_webhook
Create a webhook subscription.
| Parameter | Type | Required | Description |
| -------------- | --------- | -------- | ---------------------------------------------- |
| `name` | string | Yes | Descriptive name |
| `events` | string\[] | Yes | Event types: `CALL_LOGGED`, `CONTACT_SNOOZED` |
| `url` | string | Yes | URL to receive POST requests |
| `dispositions` | number\[] | No | Filter `CALL_LOGGED` events by disposition IDs |
***
### get\_webhooks
List all configured webhooks. Takes no parameters.
***
### get\_webhook\_by\_id
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `webhook_id` | string | Yes | Webhook ID |
***
### update\_webhook
| Parameter | Type | Required | Description |
| -------------- | --------- | -------- | --------------------------------------------- |
| `webhook_id` | string | Yes | Webhook ID |
| `name` | string | Yes | Descriptive name |
| `events` | string\[] | Yes | Event types: `CALL_LOGGED`, `CONTACT_SNOOZED` |
| `url` | string | Yes | Webhook URL |
| `dispositions` | number\[] | No | Filter `CALL_LOGGED` by disposition IDs |
***
### delete\_webhook
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `webhook_id` | string | Yes | Webhook ID |
***
### get\_webhook\_events
List available webhook event types and their descriptions. Takes no parameters.
***
### get\_webhook\_logs
Get delivery logs for a specific webhook.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ------------------------------------ |
| `webhook_id` | string | Yes | Webhook ID |
| `page` | number | No | Page number (default 1) |
| `limit` | number | No | Items per page (default 10, max 100) |
| `sort` | string | No | Sort field |
***
## Contact object
Used when creating lists or adding contacts:
| Field | Type | Required | Description |
| --------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `first_name` | string | Yes | Contact's first name |
| `last_name` | string | No | Last name |
| `email` | string | No | Email address |
| `phone_numbers` | array | No | Phone numbers (max 10). Each has `type` (`mobile`/`direct`/`office`), `number`, optional `country_code` and `extension` |
| `company` | string | No | Company name |
| `title` | string | No | Job title |
| `linkedin` | string | No | LinkedIn profile URL |
| `website` | string | No | Website URL |
| `notes` | string | No | Notes (max 2,000 characters) |
| `priority` | number | No | Priority |
| `timezone` | string | No | Timezone |
| `custom_fields` | array | No | Custom fields (max 10). Each has `type` (`string`/`number`/`boolean`), `label`, and optional `value` |
# For Managers & Leaders
Source: https://docs.salesfinity.ai/mcp/use-cases/managers
Use cases for VP of Sales, SDR Managers, and team leads using Claude x Salesfinity MCP
Prompts and workflows for sales leaders who need to monitor team performance, coach reps, forecast pipeline, and run efficient operations.
## Performance Analysis & Diagnostics
### Weekly Performance Pulse
Get a complete picture of team performance with automated week-over-week comparison.
**Prompt:** "Pull this week's call data across all reps. Compare dials, conversations, and meetings booked vs last week. Flag any rep who dropped more than 20% in any metric and suggest why."
**What Claude does:** Pulls analytics overview for both periods, compares SDR performance metrics, and highlights reps with significant drops alongside potential explanations from their call patterns.
**Tools used:** `get_analytics_overview`, `get_sdr_performance`, `get_call_logs`
***
### Rep-vs-Rep Benchmarking
Understand the behavioral differences between your top and bottom performers.
**Prompt:** "Compare my top 3 reps against my bottom 3 reps over the last 30 days. What are the specific behavioral differences in call volume, connect rate, conversation duration, and meeting conversion?"
**Tools used:** `get_sdr_performance`, `get_scored_calls`, `get_call_logs`
***
### Ramp Tracking for New Hires
Monitor whether new reps are hitting milestones on schedule.
**Prompt:** "Pull call data for reps who started in the last 90 days. Show me their week-over-week progression on dials, connects, and meetings. Which new hires are ramping on pace and which need intervention?"
**Tools used:** `get_team`, `get_sdr_performance`, `get_call_logs`
***
### Disposition Pattern Analysis
Diagnose whether your team is wasting dials on bad data or poor timing.
**Prompt:** "Across the full team over the last 4 weeks, break down call dispositions. What percentage are no-answers, voicemails, gatekeepers, conversations, and meetings? Are we wasting dials on bad data?"
**Tools used:** `get_dispositions`, `get_call_logs`, `get_analytics_overview`
***
### Time-of-Day Optimization
Find the optimal dialing windows for your team.
**Prompt:** "Analyze connect rates and meeting-booked rates by hour of day and day of week across the team. When should we be dialing for maximum live conversations?"
**Tools used:** `get_call_logs`, `get_analytics_overview`
***
### List Performance Audit
Identify which lists are producing results and which should be retired.
**Prompt:** "Pull performance metrics grouped by contact list. Which lists are producing the highest connect rates and meeting rates? Which lists should we retire or deprioritize?"
**Tools used:** `get_list_performance`, `get_contact_lists`
***
### Meeting-Set Quality Check
Ensure reps are booking real, qualified meetings — not just padding numbers.
**Prompt:** "Pull all meetings booked in the last 30 days. Cross-reference with scored calls. Are reps booking real qualified meetings or are they setting low-quality appointments that will no-show?"
**Tools used:** `get_scored_calls`, `get_call_logs`, `get_sdr_performance`
***
### Attrition Risk Detector
Spot disengaged reps before they quit.
**Prompt:** "Look at rep activity trends over the last 6 weeks. Flag any reps whose dial volume, conversation count, or meeting output has been declining consistently — they might be disengaged or about to churn."
**Tools used:** `get_sdr_performance`, `get_call_logs`
***
### Territory/Vertical Performance Comparison
Find which market segments respond best to cold outreach.
**Prompt:** "If our lists are segmented by industry or territory, compare conversion metrics across segments. Which verticals are most receptive to cold outreach right now?"
**Tools used:** `get_list_performance`, `get_contact_lists`, `get_call_logs`
***
### Monthly Board-Ready Snapshot
Generate an executive summary you can drop straight into a board deck.
**Prompt:** "Generate a clean executive summary of our outbound engine performance for this month: total dials, conversations, meetings, conversion rates at each stage, and month-over-month trends. Format it so I can drop it into a board deck."
**Tools used:** `get_analytics_overview`, `get_sdr_performance`, `get_list_performance`
***
## Coaching & Rep Development
### Individual Rep Coaching Plan
Build a data-driven coaching plan for any rep on your team.
**Prompt:** "Pull all call data, scored calls, and dispositions for \[Rep Name] over the last 2 weeks. Identify their top 3 strengths and top 3 areas for improvement. Write a specific coaching plan with talk track suggestions."
**Tools used:** `get_call_logs`, `get_scored_calls`, `get_sdr_performance`
***
### Scored Call Review Session Prep
Prepare for 1:1s with concrete call examples.
**Prompt:** "Pull the 5 highest-scored and 5 lowest-scored calls for \[Rep Name] this month. Summarize what went right in the top calls and what went wrong in the bottom calls so I can prep for our 1:1."
**Tools used:** `get_scored_calls`
***
### Objection Handling Analysis
Discover which objections your team faces most and who handles them best.
**Prompt:** "Across all scored calls this month, what are the most common objections prospects raise? Which reps handle them best? Pull examples of effective objection responses from top performers."
**Tools used:** `get_scored_calls`, `get_sdr_performance`
***
### Opening Line Effectiveness
A/B test cold call openers using real data.
**Prompt:** "Analyze scored calls across the team. Compare different cold call openers — permission-based, pattern-interrupt, direct, referral-based. Which openers lead to conversations lasting over 60 seconds and ultimately to meetings?"
**Tools used:** `get_scored_calls`, `get_call_logs`
***
### Talk-to-Listen Ratio Audit
Find out if reps are talking too much and not listening enough.
**Prompt:** "For reps with low meeting conversion despite high conversation counts, pull their scored calls. Are they talking too much? What's the ratio compared to reps who convert at higher rates?"
**Tools used:** `get_scored_calls`, `get_sdr_performance`
***
### Discovery Question Quality
Build a discovery framework from what's actually working.
**Prompt:** "Pull scored calls that resulted in meetings booked. What discovery questions are being asked? Now pull calls that had conversations but no meeting. What questions are missing? Build a recommended discovery framework from the data."
**Tools used:** `get_scored_calls`, `get_call_logs`
***
### Peer Learning Matchup
Pair struggling reps with the right mentor for their specific gap.
**Prompt:** "Identify which rep is best at each stage: getting past gatekeepers, opening conversations, handling 'not interested,' booking the meeting. Pair struggling reps with the right mentor for their specific gap."
**Tools used:** `get_sdr_performance`, `get_scored_calls`, `get_call_logs`
***
### Weekly Coaching Digest
Automated coaching notes for every rep, every Monday.
**Prompt:** "Pull last week's data for each rep. Generate a 3-bullet coaching note per rep: one thing they did well, one thing to work on, one specific call to re-listen to."
**Tools used:** `get_sdr_performance`, `get_scored_calls`, `get_call_logs`
***
### New Hire Scorecard
Benchmark new reps against where your top performers were at the same stage.
**Prompt:** "For reps in their first 30 days, pull their call scores, conversation rates, and compare to where our current top performers were at the same point in their ramp. Are they tracking ahead or behind?"
**Tools used:** `get_team`, `get_sdr_performance`, `get_scored_calls`
***
### Call Confidence Tracker
Track whether reps are getting more comfortable on calls over time.
**Prompt:** "Track conversation duration trends for each rep over time. Are they getting more comfortable staying on calls longer? Increasing average conversation length usually correlates with better outcomes — show me the trend."
**Tools used:** `get_call_logs`, `get_sdr_performance`
***
## Pipeline & Forecasting
### Meeting Flow Forecast
Predict meeting output based on current trends.
**Prompt:** "Based on our current dial volume, connect rates, and meeting conversion rates, how many meetings will we book this month if trends hold? What would happen if we increased dials by 15%?"
**Tools used:** `get_analytics_overview`, `get_sdr_performance`
***
### Funnel Leak Diagnosis
Quantify exactly where you're losing potential meetings.
**Prompt:** "Show me where we're losing the most potential meetings. Is it at the dial-to-connect stage (bad data or timing), connect-to-conversation (poor openers), or conversation-to-meeting (weak discovery or ask)? Quantify each leak."
**Tools used:** `get_analytics_overview`, `get_call_logs`, `get_dispositions`
***
### Follow-Up Pipeline Mining
Recover meetings hiding in your follow-up backlog.
**Prompt:** "Pull all follow-up tasks across the team. How many are overdue? Which reps have the largest follow-up backlog? Prioritize follow-ups by likelihood to convert based on original conversation scores."
**Tools used:** `get_follow_ups`, `get_scored_calls`, `get_sdr_performance`
***
### Snoozed Contact Re-engagement
Turn snoozed contacts back into active pipeline.
**Prompt:** "Pull all snoozed contacts. Segment by snooze reason and time snoozed. Which ones are due for re-engagement? Generate a prioritized list of snoozed contacts to add back to active lists."
**Tools used:** `get_snoozed_contacts`, `get_contact_lists`
***
### Meeting-to-Revenue Attribution
Calculate the revenue value of every dial.
**Prompt:** "Pull all meetings booked over the last quarter. Help me build a simple attribution model: how many dials does it take to generate one meeting, and if I know our meeting-to-opportunity and opportunity-to-close rates, what's the revenue value per dial?"
**Tools used:** `get_analytics_overview`, `get_call_logs`, `get_sdr_performance`
***
## Team Operations & Workflow
### Daily Standup Data Pack
Get a 60-second standup brief with zero prep.
**Prompt:** "Pull yesterday's numbers for each rep: dials, conversations, meetings. Rank them. Give me a quick narrative I can use to kick off our morning standup in 60 seconds."
**Tools used:** `get_sdr_performance`, `get_analytics_overview`
***
### Contest & Leaderboard Generator
Run data-driven sales contests with blended scoring.
**Prompt:** "Create a weekly leaderboard based on a blended score: 40% meetings booked, 30% conversations had, 30% dial volume. Rank all reps. Who's winning this week?"
**Tools used:** `get_sdr_performance`, `get_analytics_overview`
***
### List Refresh Recommendations
Know when your lists go stale before performance drops.
**Prompt:** "Look at all active contact lists. Which ones have been active for over 30 days with declining connect rates? Recommend which lists to refresh, retire, or reimport."
**Tools used:** `get_contact_lists`, `get_list_performance`
***
### Capacity Planning
Plan headcount with data, not gut feeling.
**Prompt:** "Based on current per-rep averages for dials, conversations, and meetings, how many reps do I need to hit 200 meetings per month? What if I improve conversion rates by 10% through coaching instead of hiring?"
**Tools used:** `get_analytics_overview`, `get_sdr_performance`
***
### Sequence Performance by Stage
Identify which sequences need to be rewritten.
**Prompt:** "Pull performance data for each sequence. Which sequences are driving the most conversations and meetings? Are there sequences with high dial volume but low conversion that need to be rewritten?"
**Tools used:** `get_sequences`, `get_list_performance`, `get_call_logs`
# Use Cases
Source: https://docs.salesfinity.ai/mcp/use-cases/overview
Practical ways to use Claude x Salesfinity MCP to automate workflows and boost sales performance
The Salesfinity MCP integration turns Claude into your personal sales analyst, coach, and operations assistant. Below are real-world use cases organized by role — each one is a prompt you can use directly in Claude.
## Who is this for?
Performance analysis, coaching plans, pipeline forecasting, and team operations for VP of Sales, SDR Managers, and team leads.
Self-coaching, daily workflow optimization, prospecting prep, and personal performance tracking for individual contributors.
Reporting, A/B testing, advanced analytics, and power-user workflows useful to anyone on the team.
## How it works
Every use case below is a natural-language prompt you can paste directly into Claude. Behind the scenes, Claude uses the Salesfinity MCP tools to pull your real data, analyze it, and give you actionable answers.
**No dashboards to build. No spreadsheets to wrangle. Just ask.**
Follow the [setup guide](/mcp/claude-ai) to connect your account (takes under a minute).
Each use case includes a ready-to-use prompt. Customize the timeframe, rep names, or metrics to fit your needs.
Claude pulls your live Salesfinity data, runs the analysis, and returns actionable insights — all in natural language.
## Quick examples
Here are a few prompts to get a feel for what's possible:
> "Pull this week's call data across all reps. Compare dials, conversations, and meetings booked vs last week. Flag any rep who dropped more than 20%."
> "What's my conversation-to-meeting rate compared to the team average? What's the single biggest thing I should change?"
> "Generate a clean executive summary of our outbound performance this month — total dials, conversations, meetings, conversion rates, and month-over-month trends."
Explore the full use case library by role below.
# For Sales Reps & SDRs
Source: https://docs.salesfinity.ai/mcp/use-cases/reps
Use cases for individual sales reps and SDRs using Claude x Salesfinity MCP
Prompts and workflows for individual contributors who want to improve their performance, optimize their daily workflow, and close more meetings.
## Self-Coaching & Improvement
### Personal Performance Check-In
Track your own trends without waiting for your manager.
**Prompt:** "Pull my call data for the last 2 weeks. How am I trending on dials, connects, and meetings compared to the prior 2 weeks? Where's my biggest drop-off?"
**What Claude does:** Pulls your call logs and analytics for both periods, calculates the delta on each metric, and identifies your weakest conversion point.
**Tools used:** `get_call_logs`, `get_analytics_overview`
***
### My Best Calls Analysis
Build a personal playbook from your own top performances.
**Prompt:** "Pull my top 5 scored calls this month. What did I do consistently in those calls that I should repeat? Give me a personal playbook based on what's already working for me."
**Tools used:** `get_scored_calls`
***
### My Worst Calls Debrief
Turn bad calls into learning opportunities.
**Prompt:** "Pull my lowest-scored calls this week. What went wrong? Was it my opener, my discovery, my ask, or something else? Give me specific fixes."
**Tools used:** `get_scored_calls`
***
### Conversion Rate Self-Audit
Find the one thing that will make the biggest impact on your numbers.
**Prompt:** "What's my conversation-to-meeting rate compared to the team average? If I'm below average, what's the single biggest thing I should change based on my call patterns?"
**Tools used:** `get_sdr_performance`, `get_scored_calls`
***
### Personal Objection Tracker
Track which objections trip you up and get better responses.
**Prompt:** "Across my conversations this month, what objections am I hearing most? How am I handling them based on call scores? Suggest better responses for my top 3 objections."
**Tools used:** `get_scored_calls`, `get_call_logs`
***
### Talk Track Refinement
Get a data-driven rewrite of your talk track.
**Prompt:** "Pull my last 10 conversations. Am I asking enough discovery questions? Am I pitching too early? Give me a revised talk track outline based on what the data shows."
**Tools used:** `get_scored_calls`, `get_call_logs`
***
## Daily Workflow & Prioritization
### Morning Dial Plan
Start every day with an optimized schedule.
**Prompt:** "Based on my contact lists and historical connect rates by time of day, what should my dialing schedule look like today to maximize conversations?"
**Tools used:** `get_contact_lists`, `get_call_logs`, `get_list_performance`
***
### Follow-Up Priority Queue
Never miss a hot follow-up again.
**Prompt:** "Pull my follow-up tasks. Rank them by urgency and likelihood to convert. Which 5 follow-ups should I hit first thing today?"
**Tools used:** `get_follow_ups`, `get_scored_calls`
***
### Snoozed Contact Check
Stay on top of contacts coming back from snooze.
**Prompt:** "Which of my snoozed contacts are coming due this week? Give me context on why they were snoozed and a suggested re-engagement approach for each."
**Tools used:** `get_snoozed_contacts`
***
### List Selection Helper
Dial the right list at the right time.
**Prompt:** "I have multiple lists assigned to me. Based on connect rates and meeting conversion, which list should I prioritize dialing today?"
**Tools used:** `get_contact_lists`, `get_list_performance`
***
### End-of-Day Recap
Close out every day knowing exactly where you stand.
**Prompt:** "Pull today's numbers for me. How many dials, conversations, meetings? How does today compare to my daily average this month? What should I do differently tomorrow?"
**Tools used:** `get_call_logs`, `get_analytics_overview`
***
## Prospecting & Preparation
### Pre-Call Research Brief
Walk into every dial session fully prepared.
**Prompt:** "I'm about to dial into \[List Name]. Pull the list details and any past call history. What personas am I calling? What's the historical connect rate? Any patterns I should know about?"
**Tools used:** `get_contact_list_by_id`, `get_list_performance`, `get_call_logs`
***
### Title-Specific Talk Track
Customize your pitch by persona.
**Prompt:** "Based on team-wide data, which titles/personas convert best on my lists? Give me a customized opener and value prop for each of the top 3 converting titles."
**Tools used:** `get_call_logs`, `get_scored_calls`, `get_list_performance`
***
### Gatekeeper Strategy
Get past gatekeepers more consistently.
**Prompt:** "Pull calls where the disposition was gatekeeper across my recent activity. How often am I getting past them? What approaches are working for other reps on the team?"
**Tools used:** `get_call_logs`, `get_dispositions`, `get_scored_calls`
***
### Win Pattern Cloning
Copy what's working from your best-performing teammates.
**Prompt:** "Who on my team has the highest meeting conversion rate on the same lists I'm dialing? Pull their scored calls and extract the patterns I should copy."
**Tools used:** `get_sdr_performance`, `get_scored_calls`, `get_list_performance`
# For Everyone
Source: https://docs.salesfinity.ai/mcp/use-cases/shared
Reporting, analytics, and advanced use cases for the entire sales team
Prompts and workflows useful to anyone on the team — reps, managers, and ops alike.
## Reporting & Communication
### Custom Report Builder
Generate any report in seconds, formatted for sharing.
**Prompt:** "Generate a report on \[specific metric] for \[specific time period] for \[specific reps or team]. Format it as a clean summary I can share in Slack."
**What Claude does:** Pulls the relevant data from analytics, call logs, or SDR performance, formats it with clear headers and metrics, and presents it ready to copy-paste.
**Tools used:** `get_analytics_overview`, `get_sdr_performance`, `get_call_logs`
***
### QBR Data Pack
Pull everything you need for a quarterly business review in one prompt.
**Prompt:** "Pull all key outbound metrics for the quarter: total dials, conversations, meetings, conversion rates, rep rankings, list performance, and trend analysis. Organize it for a quarterly business review."
**Tools used:** `get_analytics_overview`, `get_sdr_performance`, `get_list_performance`
***
### Client-Facing Outbound Report
For teams that manage outbound for clients, generate a clean performance report.
**Prompt:** "Generate a white-labeled performance report showing ROI on parallel dialing: total dials, conversations, meetings booked, conversion rates at each stage, and comparison to industry benchmarks."
**Tools used:** `get_analytics_overview`, `get_list_performance`, `get_sdr_performance`
***
### A/B Test Analysis
Measure which scripts, approaches, or strategies actually win.
**Prompt:** "We ran two different opener scripts this month across different reps. Pull the scored calls for each group and compare meeting conversion rates. Which script won and by how much?"
**Tools used:** `get_scored_calls`, `get_sdr_performance`, `get_call_logs`
***
### Disposition Trend Alerting
Catch data quality or timing issues before they tank your numbers.
**Prompt:** "Monitor disposition trends over the last 4 weeks. If voicemail rates are climbing or conversation rates are dropping, flag it early so we can investigate data quality or timing issues."
**Tools used:** `get_call_logs`, `get_dispositions`, `get_analytics_overview`
***
## Advanced & Power User
### AI Call Scoring Calibration
Validate whether your AI call scores actually predict real outcomes.
**Prompt:** "Pull 20 scored calls across the spectrum (high, medium, low scores). Review the scoring criteria against actual outcomes (did the call lead to a meeting?). Are our AI scores predictive of real results?"
**Tools used:** `get_scored_calls`, `get_call_logs`
***
### Multi-Variable Analysis
Identify which combination of factors most predicts a booked meeting.
**Prompt:** "Analyze which combination of factors most predicts a booked meeting: time of day, day of week, list source, rep, persona title, conversation duration, number of discovery questions asked. Rank the variables by impact."
**Tools used:** `get_call_logs`, `get_scored_calls`, `get_list_performance`, `get_sdr_performance`
***
### Competitive Intel from Conversations
Mine your call data for competitive intelligence.
**Prompt:** "Across scored calls this month, are prospects mentioning competitors? Which competitors come up most? What are the common switching triggers or objections related to competitors?"
**Tools used:** `get_scored_calls`
***
### ICP Refinement from Data
Let your actual conversion data tell you who to target.
**Prompt:** "Based on which titles, industries, and company sizes are actually converting into meetings, does our current ICP match reality? Where should we adjust our targeting?"
**Tools used:** `get_call_logs`, `get_list_performance`, `get_scored_calls`, `get_contact_lists`
***
### Coaching ROI Measurement
Prove that your coaching investment is paying off.
**Prompt:** "I coached \[Rep Name] on their discovery questions 3 weeks ago. Pull their before-and-after data. Did their conversation-to-meeting rate improve? By how much?"
**Tools used:** `get_sdr_performance`, `get_scored_calls`, `get_call_logs`