> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesfinity.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Reimport a contact list into the dialing queue
> Replaces every contact in a list's dialing queue with the saved list's current contacts, exactly as saved. Contacts added to the saved list since the last refill join the queue, and removed ones leave it.
Call it once after a batch of `POST /v1/contact-lists/{id}`, `DELETE /v1/contact-lists/{id}/contacts/{contactId}` or `POST /v1/contact-lists/{id}/merge` calls. Safe to retry: running it again gives the same queue.
The copy adds nothing. Importing the list in the dashboard also marks snooze dates, do-not-call and wrong-number flags, call counts and latest dispositions on the contacts; this call does not, and any such markings already in the queue are discarded. Numbers on the team's do-not-call list are still blocked when dialed.
Returns the dialing queue's record with all its contacts. Its `_id` is the dialing queue's own ID, not the saved list ID you sent.
Refills a list's dialing queue from its saved list. The queue's contacts are replaced by the saved list's current contacts, so contacts you added since the last refill join the queue and contacts you removed leave it.
Call it once after a batch of changes:
1. [Add a contact to a list](/api-reference/endpoint/add-contact), [remove a contact from a list](/api-reference/endpoint/remove-contact) or [merge contact lists](/api-reference/endpoint/merge-lists), as many times as you need.
2. Call this endpoint once, with the saved list's ID.
### Example
```bash theme={"system"}
curl https://client-api.salesfinity.co/v1/contact-lists/csv/6650c1f2a4b8e93d2c1f0a11/reimport \
--request POST \
--header 'x-api-key: YOUR_API_KEY'
```
Response (201), the dialing queue's record:
```json theme={"system"}
{
"_id": "6650c1f2a4b8e93d2c1f0a10",
"name": "Q2 Outbound Prospects",
"source": "csv",
"team": "64f1a2b3c4d5e6f7a8b9c0d1",
"user": "680edc0d1504192884a148e0",
"contacts": [
{
"_id": "6650c1f2a4b8e93d2c1f0a12",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane@acme.com",
"company": "Acme Corp",
"title": "VP of Sales",
"phone_numbers": [
{ "_id": "6650c1f2a4b8e93d2c1f0a13", "type": "direct", "number": "+14155552671" }
],
"custom_fields": [
{ "_id": "6650c1f2a4b8e93d2c1f0a14", "type": "string", "label": "Account tier", "value": "Enterprise" }
],
"email_views": 0,
"sequence_step": 0
}
],
"createdAt": "2026-10-03T14:05:22.470Z",
"updatedAt": "2026-10-03T16:05:03.118Z",
"__v": 0
}
```
The `_id` in the response is the dialing queue's own ID, not the saved list ID you sent. Keep using the saved list ID with this API.
### What the copy does
* It copies the saved contacts exactly. When a rep imports the list in the dashboard, Salesfinity also marks snooze dates, do-not-call and wrong-number flags, call counts and latest dispositions on the contacts. This call adds none of them, and discards any already in the queue.
* Numbers on your team's do-not-call list are still blocked when a rep dials them.
* Safe to retry: running it again leaves the same queue.
* The response contains every contact in the queue, so it grows with the list.
### Errors
| Status | When |
| - | - |
| 404 | No saved list with this ID in your team, or the list has no dialing queue (`CSV contact list not found`). |
| 400 | The `id` is not a valid ID (`Invalid ObjectId format for parameter: id`). |
## OpenAPI
````yaml POST /v1/contact-lists/csv/{id}/reimport
openapi: 3.0.1
info:
title: Salesfinity API
description: >-
The Salesfinity API is a JSON-over-HTTPS REST API for the Salesfinity
parallel dialer.
Use it to manage contact lists and notes, run the Sequencer, read call logs
and AI call
scores, pull team and SDR analytics, and enrich phone numbers and email
addresses. Webhook
subscriptions are managed in the Salesfinity dashboard rather than through
this API.
## Base URL
All requests go to `https://client-api.salesfinity.co`. There is no separate
sandbox host;
see the developer portal for the recommended way to test safely.
## Authentication
Every operation requires an API key sent in the `x-api-key` request header.
Generate a key
in the Salesfinity dashboard under **Settings → Connections → API &
Webhooks**. A key is scoped to a
single team, and every response is filtered to that team.
```bash
curl https://client-api.salesfinity.co/v1/team \
--header 'x-api-key: YOUR_API_KEY'
```
## Errors
Every error the API returns is JSON with the same four fields, so a client
can parse a
failure the same way on every endpoint:
```json
{
"message": "Forbidden resource",
"error": "Forbidden",
"statusCode": 403,
"request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}
```
`statusCode` matches the HTTP status. `error` is the stable reason phrase to
branch on.
`message` is human readable, and is an array of strings when request
validation fails.
`request_id` identifies the request in Salesfinity's logs; include it when
you contact
support. Note that a missing or invalid API key returns **403**, not 401.
## Request IDs
Every response carries an `X-Request-Id` header, and an error body repeats
it as
`request_id`. To trace a request end to end, send your own `X-Request-Id`: 1
to 128
characters of letters, digits, `.`, `_`, `:` and `-`. Otherwise Salesfinity
generates one.
## Request bodies
Bodies are JSON. A field the operation does not define is rejected with
**400**
(`property should not exist`). A body may be up to 10 MB on
`/v1/contact-lists` and
`/v2/sequencer`, and up to 1 MB everywhere else; a larger one gets **413**.
Writes that record a person take a `user_id`: the team member the call acts
as. On
contact lists and notes, a `user_id` that is not on the team gets **400**.
On the Sequencer
it must be an active member, or the call gets **403**.
## Pagination
List endpoints accept `page` (1-based) and `limit` query parameters.
Defaults, maximums and
the response envelope differ by endpoint family, so read the `limit`
parameter and the
response schema on the operation itself. Scored calls and every paged
`/v2/sequencer`
list return `{ data, pagination: { total, page, limit, pages } }`. Call logs
return that shape
when a `filters[...]` parameter is sent, and `{ data, pagination: { total,
page, next } }`
otherwise.
## Rate limits
Limits are per team: every API key on a team shares them. Requests are
counted per bucket in
fixed one-minute windows that start on the minute.
| Bucket | Routes | Requests per minute |
|---|---|---|
| Sequencer reads | `GET /v2/sequencer/*` | 600 |
| Sequencer writes | `POST`, `PATCH`, `PUT` and `DELETE` on
`/v2/sequencer/*` | 300 |
| Heavy reads | `GET /v1/call-log` and `GET /v1/scored-calls` (the lists),
`/v1/analytics/*`, `/v1/sequences` and `/v1/sequences/{id}` | 120 |
| Everything else | All other endpoints | 1200 |
Every response to an authenticated request carries `X-RateLimit-Limit`,
`X-RateLimit-Remaining` and `X-RateLimit-Reset` (seconds until the window
resets). Over the
limit the API returns **429** with a `Retry-After` header giving the seconds
to wait. These
are the current limits; Salesfinity gives notice before lowering them.
## Idempotency
`POST` endpoints outside the Sequencer are not idempotent: cap retries, and
confirm state with
a `GET` before retrying a create. Every `POST /v2/sequencer/*` endpoint
except the three
`/preview` endpoints accepts an `Idempotency-Key` header. Keys are kept for
24 hours per team.
A retry with the same key and the same request replays the original
successful response. The
same key with a different body or path returns **409**, and so does a retry
while the first
request is still running, which is safe to repeat after a moment. A request
that fails frees
its key, so a retry after a 5xx runs the write again: confirm state with a
`GET` before
retrying a create that failed with a 5xx.
version: 1.0.0
termsOfService: https://salesfinity.ai/terms
contact:
name: Salesfinity Support
email: hello@salesfinity.co
url: https://support.salesfinity.ai
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://client-api.salesfinity.co
description: Production. The only public Salesfinity API host.
security:
- ApiKeyAuth: []
tags:
- name: Contact Lists
description: >-
Create, read, merge, and delete CSV contact lists, add or remove the
contacts inside them, and put a list's contacts in its dialing queue.
- name: Teams
description: >-
Read the team that owns the API key, including its members, licenses, and
statuses.
- name: Dispositions
description: Read the default and custom call outcomes configured for the team.
- name: Sequences
description: >-
Read the external CRM sequences that appear on the team's call logs, with
call counts and first and last use. Not the Salesfinity Sequencer, which
is the Sequencer Sequences group.
- name: Call Logs
description: >-
Read the raw call history for the team, with filtering, sorting, and
pagination.
- name: Analytics
description: Aggregated call metrics for the team, by contact list, and by SDR.
- name: Snoozed Contacts
description: Read and manage contacts that have been snoozed out of the dialing queue.
- name: Follow-up Tasks
description: Read follow-up tasks created from call outcomes.
- name: Custom Fields
description: Read the custom field mappings configured for the team.
- name: Scored Calls
description: Read AI-scored calls with per-facet scoring and coaching recommendations.
- name: Notes
description: >-
Attach freeform notes to a person or company, list them, and pin the ones
that matter.
- name: Enrichment
description: >-
Look up phone numbers and work or personal email addresses for a LinkedIn
profile, and check the team's remaining enrichment credits.
- name: Sequencer Sequences
description: >-
Create, configure, enable and duplicate Sequencer cadences, and read their
analytics. Distinct from the Sequences group, which lists sequence names
observed on call logs from an external CRM.
- name: Sequencer Steps
description: The ordered steps that make up a cadence.
- name: Sequencer Templates
description: Reusable email subjects and bodies that email steps send from.
- name: Sequencer Enrollments
description: >-
Contacts inside a sequence: where they are in the cadence, and the verbs
that move them. Bulk verbs take up to 500 enrollments.
- name: Sequencer Enrolment Runs
description: >-
Background enrollment of up to 5,000 contacts at a time, and the preview
that shows what a batch would do.
- name: Sequencer Tasks
description: The rep task queue a cadence produces, plus standalone one-off tasks.
- name: Sequencer Suppression
description: >-
The team do-not-contact list, checked when someone is enrolled and again
before every email is sent.
- name: Sequencer Policies
description: 'Rules of engagement: what may be enrolled, and what happens at each step.'
- name: Sequencer Settings
description: Team-level sequencer settings and sending mailboxes. Read-only.
externalDocs:
description: Salesfinity API documentation
url: https://docs.salesfinity.ai
paths:
/v1/contact-lists/csv/{id}/reimport:
post:
tags:
- Contact Lists
summary: Reimport a contact list into the dialing queue
description: >-
Replaces every contact in a list's dialing queue with the saved list's
current contacts, exactly as saved. Contacts added to the saved list
since the last refill join the queue, and removed ones leave it.
Call it once after a batch of `POST /v1/contact-lists/{id}`, `DELETE
/v1/contact-lists/{id}/contacts/{contactId}` or `POST
/v1/contact-lists/{id}/merge` calls. Safe to retry: running it again
gives the same queue.
The copy adds nothing. Importing the list in the dashboard also marks
snooze dates, do-not-call and wrong-number flags, call counts and latest
dispositions on the contacts; this call does not, and any such markings
already in the queue are discarded. Numbers on the team's do-not-call
list are still blocked when dialed.
Returns the dialing queue's record with all its contacts. Its `_id` is
the dialing queue's own ID, not the saved list ID you sent.
operationId: reimport-contacts
parameters:
- name: id
in: path
required: true
schema:
type: string
example: 6650c1f2a4b8e93d2c1f0a11
description: >-
ID of the saved list, from `POST /v1/contact-lists` or `GET
/v1/contact-lists/csv`. A value that is not a valid ID fails with
400.
responses:
'201':
description: Refilled. The body is the dialing queue's record.
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
content:
application/json:
schema:
$ref: '#/components/schemas/DialingQueueList'
example:
_id: 6650c1f2a4b8e93d2c1f0a10
name: Q2 Outbound Prospects
source: csv
team: 64f1a2b3c4d5e6f7a8b9c0d1
user: 680edc0d1504192884a148e0
contacts:
- _id: 6650c1f2a4b8e93d2c1f0a12
first_name: Jane
last_name: Doe
email: jane@acme.com
company: Acme Corp
title: VP of Sales
phone_numbers:
- _id: 6650c1f2a4b8e93d2c1f0a13
type: direct
number: '+14155552671'
custom_fields:
- _id: 6650c1f2a4b8e93d2c1f0a14
type: string
label: Account tier
value: Enterprise
createdAt: '2026-10-03T14:05:22.470Z'
updatedAt: '2026-10-03T16:05:03.118Z'
__v: 0
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: >-
No saved list with this ID in your team, or the list has no dialing
queue.
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: CSV contact list not found
error: Not Found
statusCode: 404
request_id: 0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
components:
headers:
X-Request-Id:
description: >-
Identifies the request in Salesfinity's logs, and matches `request_id`
in an error body. Echoes the `X-Request-Id` you sent when it is 1 to 128
characters of letters, digits, `.`, `_`, `:` and `-`; otherwise
Salesfinity generates one.
schema:
type: string
example: 0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10
X-RateLimit-Limit:
description: >-
Requests allowed per minute in the rate-limit bucket this request
counted against. Limits are per team: every API key on the team shares
them.
schema:
type: integer
example: 300
X-RateLimit-Remaining:
description: Requests left in the current one-minute window for this bucket.
schema:
type: integer
minimum: 0
example: 0
X-RateLimit-Reset:
description: >-
Seconds until the current window ends and the bucket resets. At least 1
and at most 60.
schema:
type: integer
minimum: 0
example: 12
Retry-After:
description: >-
Seconds to wait before retrying: the time left in the current one-minute
window. At least 1 and at most 60.
schema:
type: integer
minimum: 0
example: 12
schemas:
DialingQueueList:
type: object
description: >-
A list's dialing queue as stored, returned by `POST
/v1/contact-lists/csv/{id}/reimport`. Lists created in the dashboard can
carry further internal fields.
properties:
_id:
type: string
description: >-
ID of the dialing queue. It differs from the saved list ID in the
path.
example: 6650c1f2a4b8e93d2c1f0a10
name:
type: string
example: Q2 Outbound Prospects
source:
type: string
description: '`csv` for every list these endpoints manage.'
example: csv
team:
type: string
description: ID of your team.
example: 64f1a2b3c4d5e6f7a8b9c0d1
user:
type: string
description: ID of the member who owns the list.
example: 680edc0d1504192884a148e0
contacts:
type: array
items:
$ref: '#/components/schemas/CSVContactObject'
description: >-
Every contact now in the dialing queue, copied from the saved list
with the same `_id` values.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
__v:
type: integer
description: Internal document version. Ignore it.
Error:
type: object
title: Error
description: >-
The error envelope returned by every Salesfinity API error response. The
shape is identical across all status codes and all endpoints, and
`request_id` is present on every error the API returns.
required:
- message
- error
- statusCode
- request_id
properties:
message:
description: >-
Human-readable description of the failure. A string for most errors,
and an array of strings when request validation fails, with one
entry per field that did not validate.
oneOf:
- type: string
- type: array
items:
type: string
example: Forbidden resource
error:
type: string
description: >-
Stable HTTP reason phrase for the status code, such as `Forbidden`.
One exception: a 403 from a `/v2/sequencer` write whose `user_id`
has no active plan or seat carries `NO_ACTIVE_PLAN` here. Branch on
this rather than on `message`.
example: Forbidden
statusCode:
type: integer
format: int32
description: >-
HTTP status code, repeated in the body so it survives transports
that drop it.
example: 403
request_id:
type: string
description: >-
Identifies the request in Salesfinity's logs; the same value as the
`X-Request-Id` response header. Include it when you contact support.
example: 0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10
errors:
type: array
items:
type: string
description: >-
Present on a few Sequencer errors, such as a rules-of-engagement
policy whose rules fail the catalog check: one entry per problem.
Other fields an upstream service sends are passed through unchanged
too.
example:
message: Forbidden resource
error: Forbidden
statusCode: 403
request_id: 0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10
CSVContactObject:
type: object
properties:
_id:
type: string
description: >-
The contact's ID in the saved list. Pass it to `DELETE
/v1/contact-lists/{id}/contacts/{contactId}`.
example: 6650c1f2a4b8e93d2c1f0a12
first_name:
type: string
last_name:
type: string
email:
type: string
company:
type: string
title:
type: string
phone_numbers:
type: array
items:
$ref: '#/components/schemas/NumbersDTO'
linkedin:
type: string
website:
type: string
notes:
type: string
account:
type: string
priority:
type: number
timezone:
type: string
external_relations:
type: object
description: >-
Free-form references stored with the contact. `GET
/v1/contact-lists/csv/{id}` regenerates any ObjectId value inside
it; strings and numbers come back as stored.
inactive:
type: boolean
description: >-
Returned only when set. Contacts created through this API never have
it.
custom_fields:
type: array
items:
$ref: '#/components/schemas/CustomFieldInputDTO'
NumbersDTO:
type: object
properties:
_id:
type: string
readOnly: true
description: >-
Assigned by Salesfinity; never send it (an unknown field fails with
400). `GET /v1/contact-lists/csv/{id}` currently returns a new
random value here on every request; the stored value appears in the
responses of `POST /v1/contact-lists`, `POST
/v1/contact-lists/{id}/merge` and `POST
/v1/contact-lists/csv/{id}/reimport`. No endpoint takes it.
example: 6650c1f2a4b8e93d2c1f0a13
type:
type: string
enum:
- mobile
- direct
- office
description: Kind of number.
example: direct
number:
type: string
description: >-
The phone number. Stored exactly as sent, without validation or
reformatting, so send E.164 (`+14155552671`).
example: '+14155552671'
country_code:
type: string
description: ISO 3166-1 alpha-2 country code, such as `US`. Stored as sent.
example: US
extension:
type: string
description: Extension, if the number has one.
example: '204'
required:
- type
- number
CustomFieldInputDTO:
type: object
properties:
_id:
type: string
readOnly: true
description: >-
Assigned by Salesfinity; never send it. `GET
/v1/contact-lists/csv/{id}` currently returns a new random value
here on every request; the stored value appears in the responses of
`POST /v1/contact-lists`, `POST /v1/contact-lists/{id}/merge` and
`POST /v1/contact-lists/csv/{id}/reimport`. No endpoint takes it.
example: 6650c1f2a4b8e93d2c1f0a14
type:
type: string
enum:
- string
- number
- boolean
description: Declared data type of `value`. Not checked against it.
example: string
label:
type: string
maxLength: 100
description: >-
Field name, at most 100 characters. Free text, not checked against
anything. To match the custom fields a CRM import creates, reuse an
`internal_name` from `GET /v1/custom-fields`.
example: Account tier
value:
description: >-
The value: a string, number, boolean or array of strings. Not
validated.
example: Enterprise
required:
- type
- label
responses:
Forbidden:
description: >-
Forbidden. The `x-api-key` header is missing, malformed, revoked, or
belongs to another team. Send a valid key in the `x-api-key` header.
Salesfinity returns 403 (not 401) for a missing, malformed, revoked, or
wrong-team key. On an operation that takes a `user_id`, 403 can also
mean that team member may not do this, for example a Sequencer call
acting as an inactive member; `message` then says why. A `/v2/sequencer`
write whose `user_id` has no active plan or seat gets `error` set to
`NO_ACTIVE_PLAN` instead of `Forbidden`; assign the member a seat.
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Forbidden resource
error: Forbidden
statusCode: 403
request_id: 0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10
TooManyRequests:
description: >-
Too Many Requests. The team has used its per-minute budget for this
rate-limit bucket; the limit is shared by every API key on the team.
Wait the number of seconds in the `Retry-After` header (never more than
60), then retry. The request was refused before it ran, so retrying it
is safe even for a write. Pace bulk work with the
`X-RateLimit-Remaining` and `X-RateLimit-Reset` headers. See
/api-reference/rate-limits.
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
X-RateLimit-Reset:
$ref: '#/components/headers/X-RateLimit-Reset'
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Rate limit of 300 requests per minute exceeded. Retry in 12s.
error: Too Many Requests
statusCode: 429
request_id: 0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10
InternalServerError:
description: >-
Internal Server Error. Something went wrong on the Salesfinity side.
Retry with exponential backoff. If it persists, contact
hello@salesfinity.co with the `request_id` from the body, the request
path and the timestamp. The contact-list, snoozed-contact and note
routes do not validate an ID in the path, and the analytics routes do
not validate `user_ids`: an ID that is not a 24-character hexadecimal
string returns 500 there, and retrying does not help, so check the ID
first.
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Internal server error
error: Internal Server Error
statusCode: 500
request_id: 0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Team-scoped API key generated in the Salesfinity dashboard under
Settings → Connections → API & Webhooks. A missing or invalid key
returns HTTP 403.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.