Start an enrollment run

curl --request POST \
  --url https://client-api.salesfinity.co/v2/sequencer/enrollment-runs \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "user_id": "507f1f77bcf86cd799439011",
  "sequence": "66fd0e5a9b8c7d6e5f4a3b21",
  "owner_id": "64b7c2d9e1f0a3b4c5d6e7f8",
  "source": {
    "kind": "contacts",
    "contacts": [
      "6702a1f0c3b2d4e5f6a7b8c9",
      "6702a1f0c3b2d4e5f6a7b8ca"
    ]
  }
}
'

import requests

url = "https://client-api.salesfinity.co/v2/sequencer/enrollment-runs"

payload = {
    "user_id": "507f1f77bcf86cd799439011",
    "sequence": "66fd0e5a9b8c7d6e5f4a3b21",
    "owner_id": "64b7c2d9e1f0a3b4c5d6e7f8",
    "source": {
        "kind": "contacts",
        "contacts": ["6702a1f0c3b2d4e5f6a7b8c9", "6702a1f0c3b2d4e5f6a7b8ca"]
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    user_id: '507f1f77bcf86cd799439011',
    sequence: '66fd0e5a9b8c7d6e5f4a3b21',
    owner_id: '64b7c2d9e1f0a3b4c5d6e7f8',
    source: {
      kind: 'contacts',
      contacts: ['6702a1f0c3b2d4e5f6a7b8c9', '6702a1f0c3b2d4e5f6a7b8ca']
    }
  })
};

fetch('https://client-api.salesfinity.co/v2/sequencer/enrollment-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://client-api.salesfinity.co/v2/sequencer/enrollment-runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'user_id' => '507f1f77bcf86cd799439011',
    'sequence' => '66fd0e5a9b8c7d6e5f4a3b21',
    'owner_id' => '64b7c2d9e1f0a3b4c5d6e7f8',
    'source' => [
        'kind' => 'contacts',
        'contacts' => [
                '6702a1f0c3b2d4e5f6a7b8c9',
                '6702a1f0c3b2d4e5f6a7b8ca'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://client-api.salesfinity.co/v2/sequencer/enrollment-runs"

	payload := strings.NewReader("{\n  \"user_id\": \"507f1f77bcf86cd799439011\",\n  \"sequence\": \"66fd0e5a9b8c7d6e5f4a3b21\",\n  \"owner_id\": \"64b7c2d9e1f0a3b4c5d6e7f8\",\n  \"source\": {\n    \"kind\": \"contacts\",\n    \"contacts\": [\n      \"6702a1f0c3b2d4e5f6a7b8c9\",\n      \"6702a1f0c3b2d4e5f6a7b8ca\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://client-api.salesfinity.co/v2/sequencer/enrollment-runs")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_id\": \"507f1f77bcf86cd799439011\",\n  \"sequence\": \"66fd0e5a9b8c7d6e5f4a3b21\",\n  \"owner_id\": \"64b7c2d9e1f0a3b4c5d6e7f8\",\n  \"source\": {\n    \"kind\": \"contacts\",\n    \"contacts\": [\n      \"6702a1f0c3b2d4e5f6a7b8c9\",\n      \"6702a1f0c3b2d4e5f6a7b8ca\"\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://client-api.salesfinity.co/v2/sequencer/enrollment-runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_id\": \"507f1f77bcf86cd799439011\",\n  \"sequence\": \"66fd0e5a9b8c7d6e5f4a3b21\",\n  \"owner_id\": \"64b7c2d9e1f0a3b4c5d6e7f8\",\n  \"source\": {\n    \"kind\": \"contacts\",\n    \"contacts\": [\n      \"6702a1f0c3b2d4e5f6a7b8c9\",\n      \"6702a1f0c3b2d4e5f6a7b8ca\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "run_id": "enroll_9c1f4e2a7b3d5c6e8f0a1b2c",
  "sequence": "66fd0e5a9b8c7d6e5f4a3b21",
  "status": "queued",
  "source": {
    "kind": "contacts",
    "label": "2 selected contact(s)"
  },
  "total": 0,
  "processed": 0,
  "enrolled": 0,
  "skipped_count": 0,
  "held_count": 0,
  "truncated": false,
  "sample_skipped": [],
  "cancel_requested": false,
  "created_at": "2026-10-03T14:02:11.482Z"
}

{
  "message": [
    "source.kind must be one of the following values: contacts, contact_list, rows, preview"
  ],
  "error": "Bad Request",
  "statusCode": 400,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Forbidden resource",
  "error": "Forbidden",
  "statusCode": 403,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Sequence not found",
  "error": "Not Found",
  "statusCode": 404,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "This Idempotency-Key was already used with a different request body.",
  "error": "Conflict",
  "statusCode": 409,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Sequence has no steps to enroll into",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "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"
}

{
  "message": "Internal server error",
  "error": "Internal Server Error",
  "statusCode": 500,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Sequencer service unreachable",
  "error": "Bad Gateway",
  "statusCode": 502,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Sequencer service timed out",
  "error": "Gateway Timeout",
  "statusCode": 504,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Enrollment runs

Start an enrollment run

Enrolls up to 5,000 people in one sequence in the background. Returns the run at once, with status: queued and a run_id; poll Get an enrollment run for progress. For 500 or fewer, Add contacts to a sequence enrolls them synchronously and reports each outcome.

source.kind says where the people come from: contacts (existing contact ids), contact_list (a Salesfinity contact list; a run reads at most its first 5,001 entries), rows (prospects you send, created as contacts if they are new; there is no file upload, so parse your CSV and send the rows), or preview (exactly the set a preview returned). Everyone goes through the same checks as any enrollment: the suppression list, the sequence’s rules of engagement and per-owner throttles, and the one-live-enrollment rule. A refusal skips that person and the run carries on; refusals are counted on the run and listed on the sequence’s refusals list.

The sequence, the owner and the source are checked before anything is queued, so a 4xx means nothing was started. A sequence that is off is accepted: its enrollments wait in pending and start when it is turned on. owner_id (default user_id) owns the enrollments and gets their tasks. People in force_include are added despite a rule blocking them, and held for approval. The request body can be up to 10 MB.

A retry without an Idempotency-Key starts a second run, whose people mostly come back as already enrolled, so send one. Counts toward the Sequencer writes rate limit.

POST

sequencer

enrollment-runs

Start an enrollment run

curl --request POST \
  --url https://client-api.salesfinity.co/v2/sequencer/enrollment-runs \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "user_id": "507f1f77bcf86cd799439011",
  "sequence": "66fd0e5a9b8c7d6e5f4a3b21",
  "owner_id": "64b7c2d9e1f0a3b4c5d6e7f8",
  "source": {
    "kind": "contacts",
    "contacts": [
      "6702a1f0c3b2d4e5f6a7b8c9",
      "6702a1f0c3b2d4e5f6a7b8ca"
    ]
  }
}
'

import requests

url = "https://client-api.salesfinity.co/v2/sequencer/enrollment-runs"

payload = {
    "user_id": "507f1f77bcf86cd799439011",
    "sequence": "66fd0e5a9b8c7d6e5f4a3b21",
    "owner_id": "64b7c2d9e1f0a3b4c5d6e7f8",
    "source": {
        "kind": "contacts",
        "contacts": ["6702a1f0c3b2d4e5f6a7b8c9", "6702a1f0c3b2d4e5f6a7b8ca"]
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    user_id: '507f1f77bcf86cd799439011',
    sequence: '66fd0e5a9b8c7d6e5f4a3b21',
    owner_id: '64b7c2d9e1f0a3b4c5d6e7f8',
    source: {
      kind: 'contacts',
      contacts: ['6702a1f0c3b2d4e5f6a7b8c9', '6702a1f0c3b2d4e5f6a7b8ca']
    }
  })
};

fetch('https://client-api.salesfinity.co/v2/sequencer/enrollment-runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://client-api.salesfinity.co/v2/sequencer/enrollment-runs",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'user_id' => '507f1f77bcf86cd799439011',
    'sequence' => '66fd0e5a9b8c7d6e5f4a3b21',
    'owner_id' => '64b7c2d9e1f0a3b4c5d6e7f8',
    'source' => [
        'kind' => 'contacts',
        'contacts' => [
                '6702a1f0c3b2d4e5f6a7b8c9',
                '6702a1f0c3b2d4e5f6a7b8ca'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://client-api.salesfinity.co/v2/sequencer/enrollment-runs"

	payload := strings.NewReader("{\n  \"user_id\": \"507f1f77bcf86cd799439011\",\n  \"sequence\": \"66fd0e5a9b8c7d6e5f4a3b21\",\n  \"owner_id\": \"64b7c2d9e1f0a3b4c5d6e7f8\",\n  \"source\": {\n    \"kind\": \"contacts\",\n    \"contacts\": [\n      \"6702a1f0c3b2d4e5f6a7b8c9\",\n      \"6702a1f0c3b2d4e5f6a7b8ca\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://client-api.salesfinity.co/v2/sequencer/enrollment-runs")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_id\": \"507f1f77bcf86cd799439011\",\n  \"sequence\": \"66fd0e5a9b8c7d6e5f4a3b21\",\n  \"owner_id\": \"64b7c2d9e1f0a3b4c5d6e7f8\",\n  \"source\": {\n    \"kind\": \"contacts\",\n    \"contacts\": [\n      \"6702a1f0c3b2d4e5f6a7b8c9\",\n      \"6702a1f0c3b2d4e5f6a7b8ca\"\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://client-api.salesfinity.co/v2/sequencer/enrollment-runs")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_id\": \"507f1f77bcf86cd799439011\",\n  \"sequence\": \"66fd0e5a9b8c7d6e5f4a3b21\",\n  \"owner_id\": \"64b7c2d9e1f0a3b4c5d6e7f8\",\n  \"source\": {\n    \"kind\": \"contacts\",\n    \"contacts\": [\n      \"6702a1f0c3b2d4e5f6a7b8c9\",\n      \"6702a1f0c3b2d4e5f6a7b8ca\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "run_id": "enroll_9c1f4e2a7b3d5c6e8f0a1b2c",
  "sequence": "66fd0e5a9b8c7d6e5f4a3b21",
  "status": "queued",
  "source": {
    "kind": "contacts",
    "label": "2 selected contact(s)"
  },
  "total": 0,
  "processed": 0,
  "enrolled": 0,
  "skipped_count": 0,
  "held_count": 0,
  "truncated": false,
  "sample_skipped": [],
  "cancel_requested": false,
  "created_at": "2026-10-03T14:02:11.482Z"
}

{
  "message": [
    "source.kind must be one of the following values: contacts, contact_list, rows, preview"
  ],
  "error": "Bad Request",
  "statusCode": 400,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Forbidden resource",
  "error": "Forbidden",
  "statusCode": 403,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Sequence not found",
  "error": "Not Found",
  "statusCode": 404,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "This Idempotency-Key was already used with a different request body.",
  "error": "Conflict",
  "statusCode": 409,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Sequence has no steps to enroll into",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "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"
}

{
  "message": "Internal server error",
  "error": "Internal Server Error",
  "statusCode": 500,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Sequencer service unreachable",
  "error": "Bad Gateway",
  "statusCode": 502,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

{
  "message": "Sequencer service timed out",
  "error": "Gateway Timeout",
  "statusCode": 504,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Enrolls up to 5,000 people in one sequence in the background. The call returns at once with the run, status: queued, and a run_id to poll. For 500 or fewer, Add contacts to a sequence does the same synchronously and reports each outcome in the response. Run a preview first: it shows who would be added and who would not, and changes nothing.

Sources

`source.kind`	Send	Notes
`contacts`	`contacts`: 1 to 5,000 contact ids	An id that is not on your team is skipped as `Contact not found`.
`contact_list`	`contact_list`: a contact list id	A run reads at most the list’s first 5,001 entries. Entries with neither an email nor a LinkedIn handle are skipped.
`rows`	`prospects`: 1 to 5,000 prospects	New people are created as contacts. There is no file upload: parse your CSV and send the rows.
`preview`	`preview_id` from a preview made in the last 30 minutes	Enrolls exactly the reviewed set. Send the same `sequence` and `owner_id` as the preview.

curl -X POST 'https://client-api.salesfinity.co/v2/sequencer/enrollment-runs' \
  -H 'x-api-key: YOUR_API_KEY' -H 'content-type: application/json' \
  -H 'Idempotency-Key: 6c3e8a1f-9b2d-4f7a-a4e5-8d0b3c6f1a92' \
  -d '{
    "user_id": "USER_ID", "sequence": "SEQUENCE_ID", "owner_id": "REP_ID",
    "source": {
      "kind": "rows",
      "prospects": [
        { "email": "[email protected]", "first_name": "Dana", "last_name": "Whitfield", "account": "Northwind", "title": "VP Sales" },
        { "linkedin_username": "sam-ortiz", "first_name": "Sam", "account": "Fabrikam" }
      ]
    }
  }'

The request body can be up to 10 MB.

What happens to each person

Everyone goes through the same checks as any enrollment: the suppression list, the sequence’s rules of engagement, the owner’s throttles on the sequence, and the one-live-enrollment rule. A refusal skips that person and the run carries on. The run counts refusals, and the sequence’s refusals list records each one with its reason. owner_id (default user_id) owns the new enrollments and gets their tasks. People listed in force_include are added despite a rule blocking them, and held for approval.

Before it is queued

The sequence, the owner and the source are checked before anything is queued, so a 4xx means nothing started:

Response	Cause
404	`sequence` or `contact_list` is not on your team.
422	The sequence is archived, has enrollment paused, or has no steps; or `owner_id` is not a member of the team.
400	The body is invalid, or the preview has expired.

A sequence that is off is accepted: its enrollments wait in pending and start when it is turned on.

Following the run

Poll Get an enrollment run every few seconds until status is completed, failed or cancelled. To stop early, cancel the run.

Send an Idempotency-Key. Without one, a retried request starts a second run, whose people mostly come back as already enrolled.

Authorizations

x-api-key

string

header

required

Team-scoped API key generated in the Salesfinity dashboard under Settings → Connections → API & Webhooks. A missing or invalid key returns HTTP 403.

Headers

Idempotency-Key

string

Makes this write safe to retry. Send a unique value, such as a UUID, and send the same value again when you retry the same request. A retry with the same key and the same request (method, path including the query string, and JSON body) returns the original successful response without acting twice. The same key with a different body or path returns 409, and so does a retry while the first request is still running; that one is safe to repeat after a moment. A request that fails frees its key, so a retry runs the write again: after a 5xx on a create, confirm with a GET before retrying. Keys are kept for 24 hours and are scoped to your team.

Body

application/json

user_id

string

required

The team member this call acts as. Must be an active member of the team the API key belongs to.

Example:

"507f1f77bcf86cd799439011"

sequence

string

required

The sequence to enroll into. It can be off; it cannot be archived, have enrollment paused, or have no steps.

source

object

required

Show child attributes

owner_id

string

Who owns the resulting enrollments and gets their tasks. Defaults to user_id. Must be a member of the team; otherwise 422.

force_include

string[]

Preview row keys of people to add even though a rule of engagement blocks them. They are enrolled and held for approval, not started. Only a rule block can be overridden: the suppression list, a live enrollment and the throttles still apply, and keys of people no rule blocks change nothing. At most 5,000. Ignored by the preview.

Maximum array length: 5000

Response

The run, queued. Poll it for progress.

A background enrollment run. Deleted 7 days after it finishes.

run_id

string

enroll_ followed by 24 hexadecimal characters.

Example:

"enroll_9c1f4e2a7b3d5c6e8f0a1b2c"

status

enum<string>

queued: waiting for a worker. fetching: reading the source; total is not known yet. running: enrolling. completed, failed and cancelled are final.

Available options:

queued,

fetching,

running,

completed,

failed,

cancelled

sequence

string

24-character hexadecimal id.

Example:

"507f1f77bcf86cd799439011"

total

integer

Everyone the source yielded, including rows that cannot be attempted. 0 until the source has been read.

processed

integer

How many of total have been dealt with, enrolled or skipped. Progress is processed out of total.

enrolled

integer

People enrolled, including those held for approval.

skipped_count

integer

People not enrolled: refused by a check, or not attemptable (no email or LinkedIn handle, or past the 5,000 cap).

held_count

integer

Enrolled people a rule is holding for approval. Part of enrolled.

truncated

boolean

The source had more than 5,000 usable people; only the first 5,000 were considered.

sample_skipped

object[]

Up to 50 skipped people, each with the reason. Every refusal is also on the sequence's refusals list, except rows that could not be attempted.

Show child attributes

error

string | null

Why the run failed or stopped early. Absent otherwise.

finished_at

string<date-time> | null

When the run reached a final status. Absent while it is in progress.

source

object

What the run was pointed at. A run started from a preview keeps the preview's source and adds preview_id. Runs started in the Salesfinity app from a connected CRM have kind crm and also carry provider, scope and list_id.

Show child attributes

cancel_requested

boolean

A cancel has been asked for. The run stops at its next check, and status changes when it does.

created_at

string<date-time>

When the run was started.

Get started

MCP server

MCP reference

MCP use cases

Dialer API

Calls and analytics API

Enrichment API

Sequencer API

Start an enrollment run

Sources

What happens to each person

Before it is queued

Following the run

Authorizations

Headers

Body

Response

​Sources

​What happens to each person

​Before it is queued

​Following the run

Authorizations

Headers

Body

Response

Sources

What happens to each person

Before it is queued

Following the run