POST/sequences

POST /sequences

Create a sequence.

View as Markdown

Request

curl -X POST 'https://api.sendheron.com/api/v1/sequences' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json'

Required scopes

The key must carry these:

  • sequences:write

Body parameters

NameTypeRequiredDescription
namestringYesSequence name, unique within the workspace.
triggerTypemanual | contact_created | list_added | tag_added | event | webhookNoWhat enrols contacts on its own once the sequence is active. manual means only explicit enrollments (POST /contacts/{id}/sequences/{seqId}/enroll, the bulk route, or the dashboard). Optional on a draft: the graph's TRIGGER step carries the same information, and a graph write whose TRIGGER step is configured updates this to match, so the usual path is to leave it out here and set it in PUT /sequences/{id}/graph.
triggerConfigobjectNoKeys depend on triggerType, and a key the trigger does not read is refused rather than stored: tagId (UUID of a tag in this workspace) for tag_added, listId (UUID) for list_added, eventName for event, an optional source filter for contact_created. Whether the trigger is complete is checked at activation, so a draft may omit them.

Responses

Returns 201 on success.

400
The payload failed validation, or the request is not valid for the current state. The body's description names the field and says what was wrong with it in words, e.g. "domain: domain must be a bare hostname such as acme.com, with no scheme, path, or port". The error code is stable and safe to branch on; description is for the human reading the log.
401
Missing or invalid API key.
403
Valid key, but it does not carry the required scope. The error code is apiKeys.insufficientScopes and the description names both halves of the problem: "Missing required scope(s): X. This key holds: Y." Neither is a secret, since the required scopes are on this page and the held ones are your own credential, and a bare "Forbidden" costs a debugging pass to work out which of the two it was.
404
No such record in this workspace. An id belonging to a different workspace returns this too, never a 403, because the API will not confirm that a record exists outside the workspace your key was issued in. Read it as "not yours or not there" rather than as "definitely gone".
409
A duplicate, or an idempotency key reused with a different payload.
429
Either rate-limit ceiling was exceeded.
400
A triggerConfig key the trigger type does not read.
409
A sequence with this name already exists in the workspace.

Rate limits

100/min per key, counted against the organization's WRITE ceiling (400/min). Both windows are one minute.