Skip to main content
POST
Preview an enrollment run
Shows what Start an enrollment run would do with the same body, without doing it. Nothing is enrolled, no contact is created or changed, and no refusal is recorded.

Reading the preview

  • counts covers everyone: total equals will_add plus needs_approval plus excluded.
  • excluded_reasons breaks excluded down by reason, again across everyone.
  • rows is a sample of up to 200 people, with the ones that need explaining first: exclusions, then approvals, then people who would be added. rows_truncated is true when there were more.
  • truncated is true when the source had more than 5,000 usable people; a run takes only the first 5,000.

What the preview cannot see

Anything answerable from data Salesfinity already holds is answered exactly. A few things are not:
  • A rule that needs a live CRM read is listed under unmeasured rather than guessed. It is checked as each person is actually added.
  • Rules using the active_in_other_sequence condition (“Already in another sequence”) are not applied, so a run can refuse people the preview showed as will_add.
  • A contact id that is not on your team is treated as a new person, so it usually shows as will_add; the run skips it as Contact not found.
  • Duplicates inside the batch are not detected; the run enrolls the first and refuses the rest as already enrolled.

From preview to run

Previews last 30 minutes. To enroll exactly the reviewed set, start a run from it with the same sequence and owner_id, because the preview stores the people, not the sequence:
force_include takes the key of rows with overridable: true. Those people are added and held for approval rather than started, so a manager still decides. Starting from a preview that has expired returns 400. The preview takes no Idempotency-Key, ignores force_include, and counts toward the Sequencer writes rate limit even though it changes nothing.

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.

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

What the run would do.

A dry run. Anything answerable from held data is exact; anything needing a live CRM read is reported under unmeasured rather than guessed.

preview_id
string

pv_ followed by 24 hexadecimal characters. Pass it back as a preview source to enroll exactly this set. Expires after 30 minutes.

Example:

"pv_3e7a9c1b5d2f4e6a8c0b2d4f"

counts
object

Totals across the whole set, not only the sample rows. total equals will_add plus needs_approval plus excluded.

excluded_reasons
object[]

How many were excluded for each reason, across the whole set. Only reasons with at least one person are listed.

rows
object[]

Up to 200 sample rows: exclusions first, then people held for approval, then people who would be added.

rows_truncated
boolean

True when there were more than 200 rows and only the first 200 are returned. The counts still cover everyone.

truncated
boolean

The source had more than 5,000 usable people; a run would consider only the first 5,000.

unmeasured
object[]

Rules that could not be evaluated without a live CRM read. They are checked as each person is actually added.