Skip to main content

​
Endpoint

POST /api/sdk/series
Programmatically enroll users into or remove users from email series automations. 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

​
action
string
required
The action to perform. Must be "enroll" or "remove".
​
user_id
string
required
The user’s external ID (the same ID used with /users/identify).
​
series_id
string
required
The UUID of the series automation. Found in the dashboard URL when viewing a series (/dashboard/automation/{series_id}).
​
user_token
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

StatusErrorDescription
400action, user_id, and series_id are requiredMissing required fields
400action must be "enroll" or "remove"Invalid action value
400Series must be active to enroll usersCannot enroll into a draft, paused, or completed series
400The specified automation is not a seriesThe ID points to a broadcast or other automation type
404User not foundThe user_id has not been identified yet. Call /users/identify first.
404Series not foundNo 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.