Approve a held enrollment

curl --request POST \
  --url https://client-api.salesfinity.co/v2/sequencer/enrollments/{id}/approve \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "user_id": "507f1f77bcf86cd799439011",
  "note": "Checked with the account owner, OK to proceed"
}
'

import requests

url = "https://client-api.salesfinity.co/v2/sequencer/enrollments/{id}/approve"

payload = {
    "user_id": "507f1f77bcf86cd799439011",
    "note": "Checked with the account owner, OK to proceed"
}
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',
    note: 'Checked with the account owner, OK to proceed'
  })
};

fetch('https://client-api.salesfinity.co/v2/sequencer/enrollments/{id}/approve', 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/enrollments/{id}/approve",
  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',
    'note' => 'Checked with the account owner, OK to proceed'
  ]),
  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/enrollments/{id}/approve"

	payload := strings.NewReader("{\n  \"user_id\": \"507f1f77bcf86cd799439011\",\n  \"note\": \"Checked with the account owner, OK to proceed\"\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/enrollments/{id}/approve")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_id\": \"507f1f77bcf86cd799439011\",\n  \"note\": \"Checked with the account owner, OK to proceed\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://client-api.salesfinity.co/v2/sequencer/enrollments/{id}/approve")

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  \"note\": \"Checked with the account owner, OK to proceed\"\n}"

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

{
  "_id": "507f1f77bcf86cd799439011",
  "sequence": "507f1f77bcf86cd799439011",
  "contact": "507f1f77bcf86cd799439011",
  "user": "<string>",
  "state": "pending",
  "current_step": "<string>",
  "current_step_order": 123,
  "next_step_due_at": "2023-11-07T05:31:56Z",
  "pending_reason": "approval",
  "pause_reason": "<string>",
  "resume_at": "2023-11-07T05:31:56Z",
  "last_reply_category": "<string>",
  "replied_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "open_count": 123,
  "reply_count": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "team": "<string>",
  "creator": "<string>",
  "state_changed_at": "2023-11-07T05:31:56Z",
  "active_at": "2023-11-07T05:31:56Z",
  "approval": {
    "rule_id": "<string>",
    "rule_name": "<string>",
    "reason": "<string>",
    "requested_at": "2023-11-07T05:31:56Z",
    "decided_at": "2023-11-07T05:31:56Z",
    "decided_by": "<string>",
    "decision": "approved",
    "note": "<string>"
  },
  "error_reason": "<string>",
  "enrollment_source": {},
  "last_reply_at": "2023-11-07T05:31:56Z",
  "click_count": 123,
  "deliver_count": 123,
  "bounce_count": 123,
  "opt_out_count": 123,
  "failure_count": 123,
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "message": [
    "user_id must be object id"
  ],
  "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 state 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": "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"
}

Enrollments

Approve a held enrollment

Approves an enrollment a rule of engagement is holding for approval. Find held enrollments with List enrollments and pending_reason=approval; the rule that held one is in its approval field. Once approved, the enrollment becomes active and its first step is scheduled as if the contact had just been enrolled. If its sequence is off, the hold is cleared and the enrollment stays pending until the sequence is turned on.

user_id must be the sequence’s author, the team owner or a team admin, and the person who enrolled the contact cannot approve it unless they are the team owner or an admin. Otherwise the call returns 403. An enrollment that is not held returns 409 (This enrollment is not awaiting approval), so a second approval is refused rather than repeated. The decision, who made it and note are recorded in approval and as an approval_granted event. For many at once use Approve held enrollments in bulk. Counts toward the Sequencer writes rate limit.

POST

sequencer

enrollments

{id}

approve

Approve a held enrollment

curl --request POST \
  --url https://client-api.salesfinity.co/v2/sequencer/enrollments/{id}/approve \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "user_id": "507f1f77bcf86cd799439011",
  "note": "Checked with the account owner, OK to proceed"
}
'

import requests

url = "https://client-api.salesfinity.co/v2/sequencer/enrollments/{id}/approve"

payload = {
    "user_id": "507f1f77bcf86cd799439011",
    "note": "Checked with the account owner, OK to proceed"
}
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',
    note: 'Checked with the account owner, OK to proceed'
  })
};

fetch('https://client-api.salesfinity.co/v2/sequencer/enrollments/{id}/approve', 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/enrollments/{id}/approve",
  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',
    'note' => 'Checked with the account owner, OK to proceed'
  ]),
  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/enrollments/{id}/approve"

	payload := strings.NewReader("{\n  \"user_id\": \"507f1f77bcf86cd799439011\",\n  \"note\": \"Checked with the account owner, OK to proceed\"\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/enrollments/{id}/approve")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"user_id\": \"507f1f77bcf86cd799439011\",\n  \"note\": \"Checked with the account owner, OK to proceed\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://client-api.salesfinity.co/v2/sequencer/enrollments/{id}/approve")

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  \"note\": \"Checked with the account owner, OK to proceed\"\n}"

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

{
  "_id": "507f1f77bcf86cd799439011",
  "sequence": "507f1f77bcf86cd799439011",
  "contact": "507f1f77bcf86cd799439011",
  "user": "<string>",
  "state": "pending",
  "current_step": "<string>",
  "current_step_order": 123,
  "next_step_due_at": "2023-11-07T05:31:56Z",
  "pending_reason": "approval",
  "pause_reason": "<string>",
  "resume_at": "2023-11-07T05:31:56Z",
  "last_reply_category": "<string>",
  "replied_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "open_count": 123,
  "reply_count": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "team": "<string>",
  "creator": "<string>",
  "state_changed_at": "2023-11-07T05:31:56Z",
  "active_at": "2023-11-07T05:31:56Z",
  "approval": {
    "rule_id": "<string>",
    "rule_name": "<string>",
    "reason": "<string>",
    "requested_at": "2023-11-07T05:31:56Z",
    "decided_at": "2023-11-07T05:31:56Z",
    "decided_by": "<string>",
    "decision": "approved",
    "note": "<string>"
  },
  "error_reason": "<string>",
  "enrollment_source": {},
  "last_reply_at": "2023-11-07T05:31:56Z",
  "click_count": 123,
  "deliver_count": 123,
  "bounce_count": 123,
  "opt_out_count": 123,
  "failure_count": 123,
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "message": [
    "user_id must be object id"
  ],
  "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 state 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": "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"
}

Approves an enrollment a rule of engagement is holding for approval, so its cadence can start.

How an enrollment comes to be held

An enrollment is held, in pending with pending_reason: "approval", when:

a rule with the hold-for-approval action matched the contact at enrollment; or
someone chose to add a contact a rule blocked. Through the API, that is listing them in force_include on Start an enrollment run.

The enrollment’s approval field names the rule (rule_name) and why it fired (reason), and its timeline has an approval_requested event.

Clearing the queue

# 1. Find everything waiting for a decision
curl 'https://client-api.salesfinity.co/v2/sequencer/enrollments?pending_reason=approval&limit=100' \
  -H 'x-api-key: YOUR_API_KEY'

# 2. Approve one
curl -X POST 'https://client-api.salesfinity.co/v2/sequencer/enrollments/ENROLLMENT_ID/approve' \
  -H 'x-api-key: YOUR_API_KEY' -H 'content-type: application/json' \
  -d '{ "user_id": "MANAGER_ID", "note": "Checked with the account owner, OK to proceed" }'

Once approved, the enrollment becomes active and its first step is scheduled as if the contact had just been enrolled. If its sequence is off, the hold is cleared and the enrollment stays pending until the sequence is turned on.

Who can approve

user_id must be the sequence’s author, the team owner or a team admin. The person who enrolled the contact (the enrollment’s creator) cannot approve it unless they are the team owner or an admin. Anyone else gets 403. An enrollment that is not held returns 409 This enrollment is not awaiting approval, so a second approval is refused rather than repeated. The decision, who made it and the note are recorded in the enrollment’s approval field and as an approval_granted event. To decide on many at once, use Approve held enrollments in bulk. To refuse instead, reject it.

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.

Path Parameters

string

required

24-character enrollment id.

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"

note

string

Approve and reject record it on the approval decision and its timeline event. Resume, finish and retry accept it but do not store it.

Maximum string length: 1000

Response

The enrollment as it is after the call.

One contact's position in one sequence. A response can also carry internal bookkeeping fields not listed here; do not rely on them.

_id

string

24-character hexadecimal id.

Example:

"507f1f77bcf86cd799439011"

sequence

string

24-character hexadecimal id.

Example:

"507f1f77bcf86cd799439011"

contact

string

24-character hexadecimal id.

Example:

"507f1f77bcf86cd799439011"

user

string

Owning team member. Their queue gets the tasks.

state

enum<string>

pending: enrolled but not started, either held for approval or waiting for the sequence to be turned on. active: working through the steps. paused: stopped until resumed. finished, bounced, opted_out and failed are terminal.

Available options:

pending,

active,

paused,

finished,

bounced,

opted_out,

failed

current_step

string | null

Id of the step the enrollment is on: the next step to run, or the step whose task is open.

current_step_order

integer | null

The order of current_step in the sequence.

next_step_due_at

string<date-time> | null

When current_step is due to run. Null while the enrollment is pending, waiting on an open task, paused, or ended.

pending_reason

enum<string> | null

approval while a rule of engagement is holding the enrollment for a manager. Absent on a pending enrollment that is only waiting for its sequence to be turned on.

Available options:

approval,

null

pause_reason

string | null

Why it is paused: the pause_reason sent to Pause an enrollment, or one Salesfinity set, such as sequence_disabled, replied, out_of_office, policy, outcome_rule, account_action, schedule_closed or transient_error.

resume_at

string<date-time> | null

When a paused enrollment resumes itself. Absent when it waits for someone to resume it.

last_reply_category

string | null

How the most recent reply was classified: interested, meeting_request, not_interested, out_of_office, wrong_person, unsubscribe_request, auto_reply or unknown.

replied_at

string<date-time> | null

finished_at

string<date-time> | null

When the enrollment was finished.

open_count

integer

Opens recorded on this enrollment's emails.

reply_count

integer

Replies recorded from this contact.

created_at

string<date-time>

When the contact was enrolled.

team

string

The team's id.

creator

string

The team member who enrolled the contact: the user_id of the call that created the enrollment. Can differ from the owner.

state_changed_at

string<date-time>

When state last changed.

active_at

string<date-time>

When the enrollment first became active. Absent until then.

approval

object | null

The approval hold, when a rule held this enrollment: which rule and why and, once decided, who decided, when, the decision and the note. Null if no rule ever held it.

Show child attributes

error_reason

string | null

Why the enrollment failed, when state is failed. Cleared by a retry.

enrollment_source

object | null

Set when Salesfinity created the enrollment itself, for example from a follow-up rule. Null when a person or an API call enrolled the contact.

last_reply_at

string<date-time>

When the most recent reply arrived.

click_count

integer

Link clicks recorded on this enrollment's emails.

deliver_count

integer

Emails confirmed delivered.

bounce_count

integer

Bounces recorded.

opt_out_count

integer

Opt-outs recorded.

failure_count

integer

Errors on the current step so far. Reset to 0 by a retry.

updated_at

string<date-time>

When the enrollment last changed.

Get started

MCP server

MCP reference

MCP use cases

Dialer API

Calls and analytics API

Enrichment API

Sequencer API

Approve a held enrollment

How an enrollment comes to be held

Clearing the queue

Who can approve

Authorizations

Headers

Path Parameters

Body

Response

​How an enrollment comes to be held

​Clearing the queue

​Who can approve

Authorizations

Headers

Path Parameters

Body

Response

How an enrollment comes to be held

Clearing the queue

Who can approve