POST
Create an automation flow

Authorizations

Authorization
string
header
required

A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.

Headers

Idempotency-Key
string
required

A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.

Body

application/json

A flow ALWAYS lands as a draft with no published graph, so this route can never mail anybody: publishing a version and taking it live are two further explicitly named calls. status and live_version_id are refused by name for that reason. THE STEP GRAPH IS NOT ON THIS BODY. It lives in an immutable version, so changing the program means POSTing to .../versions; this body carries only who enters the flow and under what policy.

name
string
required

What the merchant sees in their own dashboard. Unique per store, so a repeat is 409 name_taken rather than a second program nobody can tell apart from the first. At most 200 bytes.

trigger_type
enum<string>
required

What admits a contact. event enrolls whoever performs a named behaviour, segment_entry enrolls whoever joins a segment, and manual enrolls only who is explicitly pushed through .../enroll. It has no default and cannot be inferred.

Available options:
event,
segment_entry,
manual
trigger_event_name
string

REQUIRED when trigger_type is event. A trigger that does not carry the thing it triggers on could never fire, so it is 400 invalid_flow rather than a flow that silently enrolls nobody.

trigger_segment_id
string

REQUIRED when trigger_type is segment_entry, for the same reason.

reenrollment
enum<string>

Whether someone who has been through this program may enter it again. An omitted key stores never, which is the conservative one: it is the difference between a welcome series and a loop that mails the same person every week.

Available options:
never,
after_exit,
after_cooldown
reenroll_cooldown_secs
integer

How long after_cooldown waits before a contact is eligible again. REQUIRED and non-zero when reenrollment is after_cooldown; meaningless on the other two.

exit_on_event_names
string[]

Behavioural events that end a run early, so a contact who converts stops receiving the rest of the sequence. Empty means a run only ends by reaching an exit step.

Response

Created

data
object