Journeys

Create a journey

POST/v1/journeys

Requires an API key with the journeys:write scope. About keys and scopes

Creates a multi-step automation in a draft state. A draft saves unfinished: it needs a name and a trigger, but may have no steps yet and send steps without their content; what is given is checked. A journey does not run until it is activated, which needs it whole (409 DRAFT_INCOMPLETE lists each missing field in details.issues); edit it with PATCH /v1/journeys/{id}.

Request body

namestringrequired

1–255 characters

triggerEventstringoptional

The event that starts a run. Required unless dateTrigger is set.

1–128 characters

dateTriggerobject | nulloptional

Starts runs from a date on the contact instead of an event.

5 child attributes

fieldstringrequired

The contact date field the journey runs from.

recurrencestringrequired

once runs on the date a single time; annual repeats every year.

one of once, annual

offsetDaysintegeroptional

Days from the date to start: negative before it, positive after. Defaults to 0.

min -365 · max 365 · default 0

timestringrequired

Time of day to start, as HH:MM in the contact's timezone, else the workspace's.

leapDaystringoptional

For an annual 29 February date in a common year: run on 28 Feb, on 1 Mar, or skip.

one of feb28, mar1, skip · default "feb28"

entryConditionsobjectoptional

Property values the trigger event must carry to start a run; all must match exactly.

default {}

reentryobjectoptional

Whether a contact may enter again. Defaults to once.

default {"mode":"once"}

One of 2 shapes

Once

1 child attribute

mode"once"required

Repeatable

2 child attributes

mode"repeatable"required

cooldownDaysintegeroptional

Days after a run starts before the same contact may enter again.

min 0 · max 3650 · default 0

exitConditionsobject[]optional

Events that end a contact's run early.

at most 10 items · default []

3 child attributes

type"event"required

eventNamestringrequired

The event that ends a contact's run when they do it.

1–128 characters

propertiesobjectoptional

Property values the event must carry to count; all must match exactly.

default {}

stepsobject[]required

The steps, in order. Empty while a draft; going live needs a first step.

at most 50 items

One of 9 shapes

Wait step

4 child attributes

type"wait"required

durationSecondsintegerrequired

How long to wait, in seconds; at most 365 days.

min 1 · max 31536000

windowobjectoptional

Hours the wait may end in, in the contact's local time.

3 child attributes

startHourintegerrequired

Hour of day (0-23) the window opens, inclusive.

min 0 · max 23

endHourintegerrequired

Hour of day (1-24) the window closes; it must be after startHour.

min 1 · max 24

daysinteger[]optional

Days of the week the window is open, 0 = Sunday to 6 = Saturday; every day when left out.

at least 1 item · at most 7 items

nextStepinteger | nulloptional

Index in steps of the step to run next. It must come after this step; null or omitted ends the journey here.

min 0 · max 9007199254740991

Wait-until step

6 child attributes

type"wait_until"required

eventNamestringrequired

The event to wait for.

1–128 characters

whereobject[]optional

Conditions on the event's properties; all must hold.

at least 1 item · at most 5 items

3 child attributes

propertystringrequired

The event property key.

1–64 characters

operatorstringrequired

one of equals, notEquals, gt, gte, lt, lte

valuestring | number | booleanrequired

timeoutSecondsintegerrequired

How long to wait for the event, in seconds: 60 to 90 days.

min 60 · max 7776000

onMatchStepintegerrequired

Index of the step to take when the event happens.

min 0 · max 9007199254740991

onTimeoutStepinteger | nullrequired

Index of the step to take on timeout; null ends the journey.

min 0 · max 9007199254740991

Digest step

3 child attributes

type"digest"required

windowSecondsintegerrequired

How long to gather events, in seconds: 60 to 7 days.

min 60 · max 604800

nextStepinteger | nulloptional

Index in steps of the step to run next. It must come after this step; null or omitted ends the journey here.

min 0 · max 9007199254740991

Email send step

7 child attributes

idstringoptional

Assigned by the server; send it back unchanged so a message keeps its identity when steps move.

uuid

type"send"required

channel"email"required

contentobjectrequired

The email. Any part may be missing on a draft; going live needs subject, sender and design.

5 child attributes

subjectstringoptional

The subject line. Merge tags are allowed.

1–998 characters

previewTextstringoptional

Shown by inboxes after the subject. Merge tags are allowed; keep it near 100 characters.

1–255 characters

fromstringoptional

The sender address, on a verified sending domain.

1–320 characters

replyTostringoptional

Where replies go.

templateSnapshotTemplateSnapshotInputoptional

4 child attributes

schemaVersionintegerrequired

The block format version; use the current one, 1.

min > 0 · max 1000

blocksEmailBlockInput[]required

At most 200 blocks across the entire tree and five levels including the root. Footer blocks must remain at root. Known child fields are validated recursively.

at least 1 item · at most 200 items

themeEmailThemeInputrequired

Theme values this email overrides.

plainTextOverridestring | nulloptional

Plain text sent instead of the version generated from the blocks.

up to 100000 characters

nextStepinteger | nulloptional

Index in steps of the step to run next. It must come after this step; null or omitted ends the journey here.

min 0 · max 9007199254740991

onUnreachableStepintegeroptional

Index of the step to go to when the contact cannot receive this channel; unset skips the send.

min 0 · max 9007199254740991

topicIdstringoptional

Sends only to contacts the topic reaches; unset sends to everyone with consent.

uuid

Push send step

7 child attributes

idstringoptional

Assigned by the server; send it back unchanged so a message keeps its identity when steps move.

uuid

type"send"required

channel"push"required

contentobjectrequired

The notification. Any part may be missing on a draft.

2 child attributes

pushProjectIdstringoptional

The push app to send through.

uuid

pushobjectoptional

The notification content.

13 child attributes

titlestringoptional

The notification title (up to 100 characters).

1–100 characters

bodystringoptional

The notification text (up to 500 characters).

1–500 characters

actionUrlstringoptional

The HTTPS page opened when the notification is tapped.

uri · up to 2048 characters

imageUrlstringoptional

A large picture: web and Android show it; iOS needs the app's service extension.

uri · up to 2048 characters

iconUrlstringoptional

Web only; iOS and Android show the app's own notification icon.

uri · up to 2048 characters

dataobjectoptional

Up to 10 string key-value pairs passed to the app untouched, for deep links and in-app routing.

buttonsobject[]optional

Up to 2 action buttons.

at least 1 item · at most 2 items

collapseKeystringoptional

A newer notification with the same key replaces the older one on the device.

soundstringoptional

The name of a sound the app ships; the device's default if unset.

1–64 characters

badgeintegeroptional

The number shown on the iOS app icon.

min 0 · max 99999

ttlSecondsintegeroptional

Seconds a provider keeps trying an offline device (up to 28 days); defaults to 86400 (one day).

min 0 · max 2419200

urgencystringoptional

high wakes the device now; normal lets it wait for a good moment to save battery. Unset, a transactional push is high and any other normal.

one of high, normal

overridesobjectoptional

Fields that differ on one platform, each replacing the shared one there (a whole data map, not merged key by key). On iOS and Android actionUrl may be an app link such as myapp://orders; the shared one and the web one must be HTTPS.

nextStepinteger | nulloptional

Index in steps of the step to run next. It must come after this step; null or omitted ends the journey here.

min 0 · max 9007199254740991

onUnreachableStepintegeroptional

Index of the step to go to when the contact cannot receive this channel; unset skips the send.

min 0 · max 9007199254740991

topicIdstringoptional

Sends only to contacts the topic reaches; unset sends to everyone with consent.

uuid

Branch step

4 child attributes

type"branch"required

conditionobjectrequired

Event property values to compare with the trigger event; all must match exactly.

onMatchStepintegerrequired

Index of the step to take when the condition matches.

min 0 · max 9007199254740991

onNoMatchStepintegerrequired

Index of the step to take when it does not.

min 0 · max 9007199254740991

Filter step

5 child attributes

type"filter"required

modestringrequired

once checks the rules here only; continuous re-checks them before every later step.

one of once, continuous

rulesobjectrequired

The contact must match these rules.

One of 2 shapes

Match all

1 child attribute

allobject[]required

Every rule or nested group must match.

at least 1 item · at most 20 items

Match any

1 child attribute

anyobject[]required

At least one rule or nested group must match.

at least 1 item · at most 20 items

onMatchStepintegerrequired

Index of the step to take when the contact matches.

min 0 · max 9007199254740991

onNoMatchStepinteger | nulloptional

Index of the step to take when they do not; null ends the journey.

min 0 · max 9007199254740991

Split step

3 child attributes

type"split"required

pathsobject[]required

Paths checked in order; the first whose rules match is taken.

at least 1 item · at most 5 items

2 child attributes

rulesobjectrequired

The contact takes this path when they match.

One of 2 shapes

Match all
Match any

nextStepintegerrequired

Index of the step this path leads to.

min 0 · max 9007199254740991

otherwiseStepinteger | nullrequired

Index of the step to take when no path matches; null ends the journey.

min 0 · max 9007199254740991

Action step

3 child attributes

type"action"required

actionobjectrequired

What this step does to the contact.

One of 5 shapes

Set attribute

3 child attributes

kind"set_attribute"required
keystringrequired: The contact attribute's key.
valuestring | number | boolean | nullrequired: The value to set; null clears it.

Add to or remove from list attribute

3 child attributes

kindstringrequired: one of add_to_attribute, remove_from_attribute
keystringrequired: The contact attribute's key.
valuestring | number | booleanrequired: The one item to add to, or remove from, the list; other items are kept.

Add to group

2 child attributes

kind"add_to_group"required

groupIdstringrequired

The group to add the contact to.

uuid

Remove from group

2 child attributes

kind"remove_from_group"required

groupIdstringrequired

The group to remove the contact from.

uuid

Send webhook

3 child attributes

kind"webhook"required

webhookIdstringrequired

The webhook endpoint to notify.

uuid

dataobjectoptional

Extra data sent in the journey.action payload.

default {}

nextStepinteger | nulloptional

Index in steps of the step to run next. It must come after this step; null or omitted ends the journey here.

min 0 · max 9007199254740991

messageLimitsMessageLimitUseInputoptional

For the whole journey: a person over a limit skips that send and moves on.

2 child attributes

applybooleanrequired
retryHoursintegeroptional: min 0 · max 48

utmobject | nulloptional

Link tags for the journey's email, as on campaigns; unset follows the workspace.

6 child attributes

enabledbooleanrequired
sourcestringoptional: 1–100 characters
mediumstringoptional: 1–100 characters
campaignstringoptional: 1–100 characters
contentstringoptional: 1–100 characters
termstringoptional: 1–100 characters

maxEntriesinteger | nulloptional

The most runs the journey starts over its life; null or unset has no cap.

min > 0 · max 100000000

Returns

Returns 201 Created with a Journey in data. Otherwise returns an error; Errors lists every code and which to retry.

idstringrequired

uuid

namestringrequired

triggerEventstringrequired

The event that starts a run.

dateTriggerobject | nullrequired

The contact date that starts runs, for a date journey; otherwise null.

5 child attributes

fieldstringrequired

The contact date field the journey runs from.

recurrencestringrequired

once runs on the date a single time; annual repeats every year.

one of once, annual

offsetDaysintegerrequired

Days from the date to start: negative before it, positive after. Defaults to 0.

min -365 · max 365 · default 0

timestringrequired

Time of day to start, as HH:MM in the contact's timezone, else the workspace's.

leapDaystringrequired

For an annual 29 February date in a common year: run on 28 Feb, on 1 Mar, or skip.

one of feb28, mar1, skip · default "feb28"

entryConditionsobjectrequired

Property values the trigger event must carry to start a run.

reentryobjectrequired

Whether a contact may enter again.

One of 2 shapes

Once

1 child attribute

mode"once"required

Repeatable

2 child attributes

mode"repeatable"required

cooldownDaysintegerrequired

Days after a run starts before the same contact may enter again.

min 0 · max 3650 · default 0

exitConditionsobject[]required

Events that end a contact's run early.

3 child attributes

type"event"required

eventNamestringrequired

The event that ends a contact's run when they do it.

1–128 characters

propertiesobjectrequired

Property values the event must carry to count; all must match exactly.

default {}

stepsobject[]required

The steps, in order.

One of 9 shapes

Wait step

4 child attributes

type"wait"required

durationSecondsintegerrequired

How long to wait, in seconds; at most 365 days.

min 1 · max 31536000

windowobjectoptional

Hours the wait may end in, in the contact's local time.

3 child attributes

startHourintegerrequired

Hour of day (0-23) the window opens, inclusive.

min 0 · max 23

endHourintegerrequired

Hour of day (1-24) the window closes; it must be after startHour.

min 1 · max 24

daysinteger[]optional

Days of the week the window is open, 0 = Sunday to 6 = Saturday; every day when left out.

at least 1 item · at most 7 items

nextStepinteger | nulloptional

Index in steps of the step to run next. It must come after this step; null or omitted ends the journey here.

min 0 · max 9007199254740991

Wait-until step

6 child attributes

type"wait_until"required

eventNamestringrequired

The event to wait for.

1–128 characters

whereobject[]optional

Conditions on the event's properties; all must hold.

at least 1 item · at most 5 items

3 child attributes

propertystringrequired

The event property key.

1–64 characters

operatorstringrequired

one of equals, notEquals, gt, gte, lt, lte

valuestring | number | booleanrequired

timeoutSecondsintegerrequired

How long to wait for the event, in seconds: 60 to 90 days.

min 60 · max 7776000

onMatchStepintegerrequired

Index of the step to take when the event happens.

min 0 · max 9007199254740991

onTimeoutStepinteger | nullrequired

Index of the step to take on timeout; null ends the journey.

min 0 · max 9007199254740991

Digest step

3 child attributes

type"digest"required

windowSecondsintegerrequired

How long to gather events, in seconds: 60 to 7 days.

min 60 · max 604800

nextStepinteger | nulloptional

Index in steps of the step to run next. It must come after this step; null or omitted ends the journey here.

min 0 · max 9007199254740991

Email send step

7 child attributes

idstringoptional

Assigned by the server; send it back unchanged so a message keeps its identity when steps move.

uuid

type"send"required

channel"email"required

contentobjectrequired

The email, as saved.

7 child attributes

subjectstringoptional

The subject line. Merge tags are allowed.

1–998 characters

previewTextstringoptional

Shown by inboxes after the subject. Merge tags are allowed; keep it near 100 characters.

1–255 characters

htmlstringoptional

The HTML body. Rendered from the design when one is set.

1–512000 characters

textstringoptional

The plain-text alternative.

1–512000 characters

fromstringoptional

The sender address, on a verified sending domain.

1–320 characters

replyTostringoptional

Where replies go.

templateSnapshotTemplateSnapshotoptional

4 child attributes

schemaVersionintegerrequired

The block format version; use the current one, 1.

min > 0 · max 1000

blocksEmailBlock[]required

At most 200 blocks across the entire tree and five levels including the root. Footer blocks must remain at root. Known child fields are validated recursively.

at least 1 item · at most 200 items

themeEmailThemerequired

Theme values this email overrides.

plainTextOverridestring | nulloptional

Plain text sent instead of the version generated from the blocks.

up to 100000 characters

nextStepinteger | nulloptional

Index in steps of the step to run next. It must come after this step; null or omitted ends the journey here.

min 0 · max 9007199254740991

onUnreachableStepintegeroptional

Index of the step to go to when the contact cannot receive this channel; unset skips the send.

min 0 · max 9007199254740991

topicIdstringoptional

Sends only to contacts the topic reaches; unset sends to everyone with consent.

uuid

Push send step

7 child attributes

idstringoptional

Assigned by the server; send it back unchanged so a message keeps its identity when steps move.

uuid

type"send"required

channel"push"required

contentobjectrequired

The notification. Any part may be missing on a draft.

2 child attributes

pushProjectIdstringoptional

The push app to send through.

uuid

pushobjectoptional

The notification content.

13 child attributes

titlestringoptional

The notification title (up to 100 characters).

1–100 characters

bodystringoptional

The notification text (up to 500 characters).

1–500 characters

actionUrlstringoptional

The HTTPS page opened when the notification is tapped.

uri · up to 2048 characters

imageUrlstringoptional

A large picture: web and Android show it; iOS needs the app's service extension.

uri · up to 2048 characters

iconUrlstringoptional

Web only; iOS and Android show the app's own notification icon.

uri · up to 2048 characters

dataobjectoptional

Up to 10 string key-value pairs passed to the app untouched, for deep links and in-app routing.

buttonsobject[]optional

Up to 2 action buttons.

at least 1 item · at most 2 items

collapseKeystringoptional

A newer notification with the same key replaces the older one on the device.

soundstringoptional

The name of a sound the app ships; the device's default if unset.

1–64 characters

badgeintegeroptional

The number shown on the iOS app icon.

min 0 · max 99999

ttlSecondsintegeroptional

Seconds a provider keeps trying an offline device (up to 28 days); defaults to 86400 (one day).

min 0 · max 2419200

urgencystringoptional

high wakes the device now; normal lets it wait for a good moment to save battery. Unset, a transactional push is high and any other normal.

one of high, normal

overridesobjectoptional

nextStepinteger | nulloptional

Index in steps of the step to run next. It must come after this step; null or omitted ends the journey here.

min 0 · max 9007199254740991

onUnreachableStepintegeroptional

Index of the step to go to when the contact cannot receive this channel; unset skips the send.

min 0 · max 9007199254740991

topicIdstringoptional

Sends only to contacts the topic reaches; unset sends to everyone with consent.

uuid

Branch step

4 child attributes

type"branch"required

conditionobjectrequired

Event property values to compare with the trigger event; all must match exactly.

onMatchStepintegerrequired

Index of the step to take when the condition matches.

min 0 · max 9007199254740991

onNoMatchStepintegerrequired

Index of the step to take when it does not.

min 0 · max 9007199254740991

Filter step

5 child attributes

type"filter"required

modestringrequired

once checks the rules here only; continuous re-checks them before every later step.

one of once, continuous

rulesobjectrequired

The contact must match these rules.

One of 2 shapes

Match all

1 child attribute

allobject[]required

Every rule or nested group must match.

at least 1 item · at most 20 items

Match any

1 child attribute

anyobject[]required

At least one rule or nested group must match.

at least 1 item · at most 20 items

onMatchStepintegerrequired

Index of the step to take when the contact matches.

min 0 · max 9007199254740991

onNoMatchStepinteger | nullrequired

Index of the step to take when they do not; null ends the journey.

min 0 · max 9007199254740991

Split step

3 child attributes

type"split"required

pathsobject[]required

Paths checked in order; the first whose rules match is taken.

at least 1 item · at most 5 items

2 child attributes

rulesobjectrequired

The contact takes this path when they match.

One of 2 shapes

Match all
Match any

nextStepintegerrequired

Index of the step this path leads to.

min 0 · max 9007199254740991

otherwiseStepinteger | nullrequired

Index of the step to take when no path matches; null ends the journey.

min 0 · max 9007199254740991

Action step

3 child attributes

type"action"required

actionobjectrequired

What this step does to the contact.

One of 5 shapes

Set attribute

3 child attributes

kind"set_attribute"required
keystringrequired: The contact attribute's key.
valuestring | number | boolean | nullrequired: The value to set; null clears it.

Add to or remove from list attribute

3 child attributes

kindstringrequired: one of add_to_attribute, remove_from_attribute
keystringrequired: The contact attribute's key.
valuestring | number | booleanrequired: The one item to add to, or remove from, the list; other items are kept.

Add to group

2 child attributes

kind"add_to_group"required

groupIdstringrequired

The group to add the contact to.

uuid

Remove from group

2 child attributes

kind"remove_from_group"required

groupIdstringrequired

The group to remove the contact from.

uuid

Send webhook

3 child attributes

kind"webhook"required

webhookIdstringrequired

The webhook endpoint to notify.

uuid

dataobjectrequired

Extra data sent in the journey.action payload.

default {}

nextStepinteger | nulloptional

Index in steps of the step to run next. It must come after this step; null or omitted ends the journey here.

min 0 · max 9007199254740991

messageLimitsMessageLimitUserequired

2 child attributes

applybooleanrequired
retryHoursintegeroptional: min 0 · max 48

utmobject | nullrequired

Link tags for the journey's email; null follows the workspace.

6 child attributes

enabledbooleanrequired
sourcestringoptional: 1–100 characters
mediumstringoptional: 1–100 characters
campaignstringoptional: 1–100 characters
contentstringoptional: 1–100 characters
termstringoptional: 1–100 characters

maxEntriesinteger | nullrequired

The most runs the journey starts over its life; null has no cap.

min > 0 · max 9007199254740991

enrolledCountintegerrequired

Runs ever started.

min 0 · max 9007199254740991

statusstringrequired

ended: nobody enters and runs in progress were exited; it cannot restart.

one of draft, active, paused, ended

revisionintegerrequired

Raised by every edit. Send it back as expectedRevision on the update so a change made since you read it is refused instead of overwritten.

min > 0 · max 2147483647

createdAtstringrequired

date-time

updatedAtstringrequired

date-time

curl -X POST https://api.kirora.io/v1/journeys \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend specials",
    "steps": [
      {
        "type": "wait",
        "durationSeconds": 1
      }
    ]
  }'

const response = await fetch('https://api.kirora.io/v1/journeys', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.KIRORA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Weekend specials",
    "steps": [
      {
        "type": "wait",
        "durationSeconds": 1
      }
    ]
  }),
});
const { data } = await response.json();

import os

import requests

response = requests.post(
    "https://api.kirora.io/v1/journeys",
    headers={
        "Authorization": f"Bearer {os.environ['KIRORA_API_KEY']}",
    },
    json={
        "name": "Weekend specials",
        "steps": [
            {
                "type": "wait",
                "durationSeconds": 1,
            },
        ],
    },
)
data = response.json()["data"]

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "name": "Weekend specials",
	  "steps": [
	    {
	      "type": "wait",
	      "durationSeconds": 1
	    }
	  ]
	}`)
	req, err := http.NewRequest("POST", "https://api.kirora.io/v1/journeys", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("KIRORA_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var out struct {
		Data json.RawMessage `json:"data"`
	}
	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
		panic(err)
	}
}

Response · 201

{
  "data": {
    "id": "018f2a4e-6b1c-7d3e-9f40-37386ae05a6b",
    "name": "Weekend specials",
    "triggerEvent": "triggerEvent_example",
    "dateTrigger": {
      "field": "field_example",
      "recurrence": "once",
      "offsetDays": 0,
      "time": "time_example",
      "leapDay": "feb28"
    },
    "entryConditions": {},
    "reentry": {
      "mode": "once"
    },
    "exitConditions": [
      {
        "type": "event",
        "eventName": "Order Completed",
        "properties": {}
      }
    ],
    "steps": [
      {
        "type": "wait",
        "durationSeconds": 1
      }
    ],
    "messageLimits": {
      "apply": true
    },
    "utm": {
      "enabled": true
    },
    "maxEntries": 1,
    "enrolledCount": 0,
    "status": "draft",
    "revision": 1,
    "createdAt": "2030-03-14T09:30:00Z",
    "updatedAt": "2030-03-14T09:30:00Z"
  }
}

Example values are generated from the schema.