Series - HaloAgents

Endpoint

POST /api/sdk/series

Programmatically enroll users into or remove users from email series campaigns. This enables third-party apps built on top of the HaloAgents platform to manage series enrollment from their own application logic.

Authentication

Requires your publishable widget key in the Authorization header:

Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx

Request Body

string

required

The action to perform. Must be "enroll" or "remove".

string

required

The user’s external ID (the same ID used with /users/identify).

string

required

The UUID of the series. Found in the dashboard URL when viewing a series (/dashboard/outreach/{series_id}).

string

JWT signed with your Identity Secret (HS256). Required when identity verification is enabled for your workspace. The token’s user_id claim must match the user_id field above. See Identity Verification.

Enroll a User

Enrolling a user adds them to the first step of the series. The system respects:

Send windows and business day constraints configured on the series
Per-user timezone when available
Re-enrollment rules (if enabled on the series, users can re-enter after completing it)
Duplicate prevention via unique constraints

If the user is already actively enrolled, the response indicates this without creating a duplicate.

Example

curl -X POST https://api.haloagents.ai/api/sdk/series \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx" \
  -d '{
    "action": "enroll",
    "user_id": "user_123",
    "series_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Response (enrolled):

{
  "success": true,
  "enrolled": true,
  "scheduled_for": "2025-03-26T14:00:00.000Z"
}

Response (already enrolled):

{
  "success": true,
  "already_enrolled": true,
  "message": "User is already enrolled in this series"
}

Remove a User

Removing a user deletes all their pending recipient rows from the series, effectively stopping them from receiving any further emails. Emails that have already been sent are not affected.

Example

curl -X POST https://api.haloagents.ai/api/sdk/series \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ab_live_xxxxxxxxxxxxxxxx" \
  -d '{
    "action": "remove",
    "user_id": "user_123",
    "series_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }'

Response:

{
  "success": true,
  "removed": true,
  "recipients_removed": 3
}

Error Responses

Status	Error	Description
400	`action, user_id, and series_id are required`	Missing required fields
400	`action must be "enroll" or "remove"`	Invalid action value
400	`Series must be active to enroll users`	Cannot enroll into a draft, paused, or completed series
400	`The specified automation is not a series`	The ID points to a broadcast or other campaign type
404	`User not found`	The `user_id` has not been identified yet. Call `/users/identify` first.
404	`Series not found`	No series with that ID exists for this organization

Notes

The user must be identified via the /users/identify endpoint before they can be enrolled in a series. The user_id must match the external ID used during identification.
Enrollment respects the series’ scheduling rules. The scheduled_for timestamp in the response shows when the first email will be sent.
Removing a user only cancels pending (unsent) emails. Previously sent emails are unaffected.
If the series has re-enrollment disabled and the user has already completed it, the enroll action returns a success response with a message explaining why re-enrollment is not possible.

​Endpoint

​Authentication

​Request Body

​Enroll a User

​Example

​Remove a User

​Example

​Error Responses

​Notes

Endpoint

Authentication

Request Body

Enroll a User

Example

Remove a User

Example

Error Responses

Notes