Join the waitlist

Let us know how we should get in touch with you.

Thank you for your interest! We’re excited to show you what we’re building very soon.

Close
Oops! Something went wrong while submitting the form.

Can You Add People to Unify Sequences Through the API?

Austin Hughes
·
Updated on: November 19, 2026
TL;DR: Yes. RevOps and growth teams can add existing people to published Unify template sequences through the API. Agentic outreach uses a different route: generate drafts in Unify, review or edit them, then approve an enrollment waiting for approval. Check eligibility and sender selection before treating either request as ready to run.

Which sequences support API enrollment?

Use Create enrollment for a published template sequence. The request starts a workflow that can send email and create tasks, so it is an activation action rather than a read-only connection check. Decide which recipient and sequence should run before an external system submits it.

Template enrollment and agentic approval
WorkflowSupported routeBoundary
Published template sequencePOST /sequences/v1/enrollmentsExisting Unify person and eligible sending mailbox required
Agentic recipient draftsGenerate in Unify, inspect copy, then approve the waiting enrollmentCreate enrollment rejects agentic sequences
Progress verificationRetrieve the enrollment and its stepsCreation is not proof of recipient delivery

The Sequences API uses API-key authentication through the X-Api-Key header. Generate the key in Settings → Developers and keep it in your integration’s protected configuration. An external orchestrator is responsible for making the authorized request; an API endpoint does not establish a native connector to every tool.

What must a template-enrollment request contain?

Provide the existing person, published sequence and permitted sender candidates. Resolve these inputs in Unify before implementing the request; a CRM contact identifier is not interchangeable with a Unify person identifier.

  • sequence_id: The published template sequence to run
  • person_id: The existing Unify person who should receive the outreach
  • mailbox_emails: One to ten candidate sending addresses, with one selected at enrollment time
  • Authentication: The authorized API key in the X-Api-Key header

Do not use the enrollment request to create a missing person or silently substitute an email address for person_id. Establish the person’s identity upstream, then retain the relationship between the source record and the Unify record. The integration methods guide helps separate this identity handoff from importing a file or receiving an event.

Review the sequence ruleset before launch. Simultaneous-enrollment settings are checked against the new sequence and the person’s active sequences, with the most restrictive setting applying. The API does not turn a blocked concurrent enrollment into an approved exception.

How should you handle conflicts and eligibility failures?

Read the returned reason before retrying. A 409 response for an active-enrollment conflict is a workflow decision, while a 400 response can identify an unpublished sequence, ineligible mailbox, opt-out, exclusion or re-enrollment restriction.

Enrollment failures and next actions
Response or conditionNext action
409 active-enrollment conflictInspect reason and active_enrollments; review any blocking or unapproved sequence IDs
Reviewed concurrent enrollmentUse allowed_concurrent_sequence_ids only for active sequences the user explicitly approved; policy still applies
400 eligibility failureCorrect the stated cause without changing a valid opt-out merely to obtain success
Uncertain request outcomeReconcile existing enrollment state before another activation attempt

Avoid a retry routine that treats every rejection as temporary. Unify enrollment controls distinguish an unavailable mailbox, an excluded person and a previous enrollment still ending. Keep that reason in the operational record so the person resolving the issue can choose the appropriate action.

What changes for agentic drafts?

Generate recipient drafts in Unify before using the approval endpoint. Agentic sequences started through chat or a list provide a review path; starting from a person’s record generates content and begins outreach without a separate draft-approval step. Choose the review path deliberately when your process requires it.

Use List enrollment steps to inspect the email subject and body for the specific recipient. If email.is_ready is false, preparation is still in progress and the body can be null. An empty response at that point is not approved copy.

Use Update enrollment step to change an unsent recipient email. The body replaces the entire email body for that enrollment, so preserve the variable tokens you still need. Send the last-read email.version_id as version_id to detect intervening edits instead of overwriting a teammate’s changes.

When the recipient copy is ready, Approve enrollment starts an existing enrollment waiting for approval. Success sets is_draft_approval_pending to false. A 409 can mean approval is no longer pending; a 400 can reflect opt-out or do-not-email status. Approval does not generate the initial draft.

How do you verify the handoff?

Retain the returned enrollment ID and retrieve that enrollment after the request. Inspect the person, sequence, selected mailbox and state together. In the API, a draft waiting for approval uses IN_PROGRESS with is_draft_approval_pending set; the deprecated DRAFT value should not drive your new integration.

Keep API state separate from the UI’s queued and started labels. Queued means no step has completed, and automatic email timing remains subject to send schedules and mailbox capacity. Record delivery evidence separately from request acceptance or step progression.

Blank enrollment handoff checklist
Evidence to retainRecorded value
Source identity and matching decision
Unify person ID and published sequence ID
Template or agentic route and review owner
Mailbox candidates and selected mailbox
Eligibility decision and any reviewed concurrent enrollment
Response, enrollment ID and readback state
Unresolved issue and responsible operator

Fill this checklist from an authorized workflow run. Keep the activation decision with the workflow owner, and avoid enabling unattended retries until an ambiguous outcome has a defined reconciliation path. No completed request or delivery result is implied by the blank worksheet.

Explore Unify to review the sequence, recipient and sender together before connecting an external enrollment workflow.

Frequently asked questions

Can the API add someone to a Unify sequence?

Yes. Create enrollment adds an existing Unify person to a published template sequence, subject to eligibility and a valid sending mailbox.

Can Create enrollment generate agentic drafts?

No. That endpoint rejects agentic sequences. Generate drafts in Unify, then use the API to review, edit and approve an existing enrollment waiting for approval.

Can I pass a Salesforce contact ID as person_id?

Use the existing Unify person ID. Resolve the source-to-Unify identity mapping before making the enrollment request.

Does mailbox_emails rotate every email across senders?

No. It supplies candidate mailbox addresses, and one is selected at enrollment time.

Does a successful approval mean the email was delivered?

No. Approval starts the enrollment. Automatic emails remain subject to sending schedules and mailbox capacity; delivery requires separate evidence.

Should I automatically retry a 409 response?

Inspect the endpoint and returned reason first. An enrollment conflict or an approval that is no longer pending requires a different decision from a stale email-copy version.

Glossary

  • Enrollment: One person’s progression through a sequence
  • Template sequence: A published sequence eligible for the create-enrollment route
  • Agentic draft: Recipient-specific content prepared before an applicable approval step
  • Mailbox candidate: An eligible sender address supplied for enrollment-time selection
  • Readback: Retrieving the resulting record to verify its actual state

Sources