Create journey

curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/journeys \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "Welcome series",
  "description": "Onboard new users over their first week.",
  "audience": {
    "kind": "segment",
    "included_segment_ids": [
      "3f7c1e90-0000-0000-0000-000000000001"
    ],
    "excluded_segment_ids": []
  },
  "nodes": [
    {
      "kind": "send_push",
      "template_id": "9a8b7c6d-0000-0000-0000-000000000001"
    },
    {
      "kind": "wait",
      "duration_seconds": 86400
    },
    {
      "kind": "send_email",
      "template_id": "9a8b7c6d-0000-0000-0000-000000000002"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    name: 'Welcome series',
    description: 'Onboard new users over their first week.',
    audience: {
      kind: 'segment',
      included_segment_ids: ['3f7c1e90-0000-0000-0000-000000000001'],
      excluded_segment_ids: []
    },
    nodes: [
      {kind: 'send_push', template_id: '9a8b7c6d-0000-0000-0000-000000000001'},
      {kind: 'wait', duration_seconds: 86400},
      {kind: 'send_email', template_id: '9a8b7c6d-0000-0000-0000-000000000002'}
    ]
  })
};

fetch('https://api.onesignal.com/apps/{app_id}/journeys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.onesignal.com/apps/{app_id}/journeys"

payload = {
    "name": "Welcome series",
    "description": "Onboard new users over their first week.",
    "audience": {
        "kind": "segment",
        "included_segment_ids": ["3f7c1e90-0000-0000-0000-000000000001"],
        "excluded_segment_ids": []
    },
    "nodes": [
        {
            "kind": "send_push",
            "template_id": "9a8b7c6d-0000-0000-0000-000000000001"
        },
        {
            "kind": "wait",
            "duration_seconds": 86400
        },
        {
            "kind": "send_email",
            "template_id": "9a8b7c6d-0000-0000-0000-000000000002"
        }
    ]
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.onesignal.com/apps/{app_id}/journeys",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Welcome series',
    'description' => 'Onboard new users over their first week.',
    'audience' => [
        'kind' => 'segment',
        'included_segment_ids' => [
                '3f7c1e90-0000-0000-0000-000000000001'
        ],
        'excluded_segment_ids' => [
                
        ]
    ],
    'nodes' => [
        [
                'kind' => 'send_push',
                'template_id' => '9a8b7c6d-0000-0000-0000-000000000001'
        ],
        [
                'kind' => 'wait',
                'duration_seconds' => 86400
        ],
        [
                'kind' => 'send_email',
                'template_id' => '9a8b7c6d-0000-0000-0000-000000000002'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.onesignal.com/apps/{app_id}/journeys"

	payload := strings.NewReader("{\n  \"name\": \"Welcome series\",\n  \"description\": \"Onboard new users over their first week.\",\n  \"audience\": {\n    \"kind\": \"segment\",\n    \"included_segment_ids\": [\n      \"3f7c1e90-0000-0000-0000-000000000001\"\n    ],\n    \"excluded_segment_ids\": []\n  },\n  \"nodes\": [\n    {\n      \"kind\": \"send_push\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000001\"\n    },\n    {\n      \"kind\": \"wait\",\n      \"duration_seconds\": 86400\n    },\n    {\n      \"kind\": \"send_email\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000002\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.onesignal.com/apps/{app_id}/journeys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"name\": \"Welcome series\",\n  \"description\": \"Onboard new users over their first week.\",\n  \"audience\": {\n    \"kind\": \"segment\",\n    \"included_segment_ids\": [\n      \"3f7c1e90-0000-0000-0000-000000000001\"\n    ],\n    \"excluded_segment_ids\": []\n  },\n  \"nodes\": [\n    {\n      \"kind\": \"send_push\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000001\"\n    },\n    {\n      \"kind\": \"wait\",\n      \"duration_seconds\": 86400\n    },\n    {\n      \"kind\": \"send_email\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000002\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

HttpResponse<String> response = Unirest.post("https://api.onesignal.com/apps/{app_id}/journeys")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"name\": \"Welcome series\",\n  \"description\": \"Onboard new users over their first week.\",\n  \"audience\": {\n    \"kind\": \"segment\",\n    \"included_segment_ids\": [\n      \"3f7c1e90-0000-0000-0000-000000000001\"\n    ],\n    \"excluded_segment_ids\": []\n  },\n  \"nodes\": [\n    {\n      \"kind\": \"send_push\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000001\"\n    },\n    {\n      \"kind\": \"wait\",\n      \"duration_seconds\": 86400\n    },\n    {\n      \"kind\": \"send_email\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000002\"\n    }\n  ]\n}")
  .asString();

using RestSharp;


var options = new RestClientOptions("https://api.onesignal.com/apps/{app_id}/journeys");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "<authorization>");
request.AddJsonBody("{\n  \"name\": \"Welcome series\",\n  \"description\": \"Onboard new users over their first week.\",\n  \"audience\": {\n    \"kind\": \"segment\",\n    \"included_segment_ids\": [\n      \"3f7c1e90-0000-0000-0000-000000000001\"\n    ],\n    \"excluded_segment_ids\": []\n  },\n  \"nodes\": [\n    {\n      \"kind\": \"send_push\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000001\"\n    },\n    {\n      \"kind\": \"wait\",\n      \"duration_seconds\": 86400\n    },\n    {\n      \"kind\": \"send_email\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000002\"\n    }\n  ]\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

{
  "id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "app_id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
  "name": "Welcome series",
  "description": "Onboard new users over their first week.",
  "state": "draft",
  "created_at": "2026-06-01T14:00:00Z",
  "updated_at": "2026-06-01T14:00:00Z",
  "started_at": null,
  "archived_at": null,
  "created_source": "public_api",
  "audience": {
    "kind": "segment",
    "included_segment_ids": [
      "3f7c1e90-0000-0000-0000-000000000001"
    ],
    "excluded_segment_ids": [],
    "future_additions_only": false
  },
  "early_exit": null,
  "reentry_rules": null,
  "schedule": null,
  "nodes": [
    {
      "id": "11111111-0000-0000-0000-000000000001",
      "kind": "send_push",
      "template_id": "9a8b7c6d-0000-0000-0000-000000000001"
    },
    {
      "id": "11111111-0000-0000-0000-000000000002",
      "kind": "wait",
      "duration_seconds": 86400
    },
    {
      "id": "11111111-0000-0000-0000-000000000003",
      "kind": "send_email",
      "template_id": "9a8b7c6d-0000-0000-0000-000000000002"
    }
  ],
  "concurrency_key": "dcae4794fee16e450e448e37a6f8d0a5a7335755ff8cc76606e3d04b2f574e46"
}

{
  "errors": [
    {
      "code": "invalid-payload",
      "title": "did not contain a required property of 'name'",
      "meta": {
        "attribute": "base",
        "path": "name"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "journey-not-entitled",
      "title": "Journeys are not enabled for this app",
      "meta": {}
    }
  ]
}

POST

apps

{app_id}

journeys

Create journey

curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/journeys \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "name": "Welcome series",
  "description": "Onboard new users over their first week.",
  "audience": {
    "kind": "segment",
    "included_segment_ids": [
      "3f7c1e90-0000-0000-0000-000000000001"
    ],
    "excluded_segment_ids": []
  },
  "nodes": [
    {
      "kind": "send_push",
      "template_id": "9a8b7c6d-0000-0000-0000-000000000001"
    },
    {
      "kind": "wait",
      "duration_seconds": 86400
    },
    {
      "kind": "send_email",
      "template_id": "9a8b7c6d-0000-0000-0000-000000000002"
    }
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    name: 'Welcome series',
    description: 'Onboard new users over their first week.',
    audience: {
      kind: 'segment',
      included_segment_ids: ['3f7c1e90-0000-0000-0000-000000000001'],
      excluded_segment_ids: []
    },
    nodes: [
      {kind: 'send_push', template_id: '9a8b7c6d-0000-0000-0000-000000000001'},
      {kind: 'wait', duration_seconds: 86400},
      {kind: 'send_email', template_id: '9a8b7c6d-0000-0000-0000-000000000002'}
    ]
  })
};

fetch('https://api.onesignal.com/apps/{app_id}/journeys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.onesignal.com/apps/{app_id}/journeys"

payload = {
    "name": "Welcome series",
    "description": "Onboard new users over their first week.",
    "audience": {
        "kind": "segment",
        "included_segment_ids": ["3f7c1e90-0000-0000-0000-000000000001"],
        "excluded_segment_ids": []
    },
    "nodes": [
        {
            "kind": "send_push",
            "template_id": "9a8b7c6d-0000-0000-0000-000000000001"
        },
        {
            "kind": "wait",
            "duration_seconds": 86400
        },
        {
            "kind": "send_email",
            "template_id": "9a8b7c6d-0000-0000-0000-000000000002"
        }
    ]
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.onesignal.com/apps/{app_id}/journeys",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Welcome series',
    'description' => 'Onboard new users over their first week.',
    'audience' => [
        'kind' => 'segment',
        'included_segment_ids' => [
                '3f7c1e90-0000-0000-0000-000000000001'
        ],
        'excluded_segment_ids' => [
                
        ]
    ],
    'nodes' => [
        [
                'kind' => 'send_push',
                'template_id' => '9a8b7c6d-0000-0000-0000-000000000001'
        ],
        [
                'kind' => 'wait',
                'duration_seconds' => 86400
        ],
        [
                'kind' => 'send_email',
                'template_id' => '9a8b7c6d-0000-0000-0000-000000000002'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.onesignal.com/apps/{app_id}/journeys"

	payload := strings.NewReader("{\n  \"name\": \"Welcome series\",\n  \"description\": \"Onboard new users over their first week.\",\n  \"audience\": {\n    \"kind\": \"segment\",\n    \"included_segment_ids\": [\n      \"3f7c1e90-0000-0000-0000-000000000001\"\n    ],\n    \"excluded_segment_ids\": []\n  },\n  \"nodes\": [\n    {\n      \"kind\": \"send_push\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000001\"\n    },\n    {\n      \"kind\": \"wait\",\n      \"duration_seconds\": 86400\n    },\n    {\n      \"kind\": \"send_email\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000002\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.onesignal.com/apps/{app_id}/journeys")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"name\": \"Welcome series\",\n  \"description\": \"Onboard new users over their first week.\",\n  \"audience\": {\n    \"kind\": \"segment\",\n    \"included_segment_ids\": [\n      \"3f7c1e90-0000-0000-0000-000000000001\"\n    ],\n    \"excluded_segment_ids\": []\n  },\n  \"nodes\": [\n    {\n      \"kind\": \"send_push\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000001\"\n    },\n    {\n      \"kind\": \"wait\",\n      \"duration_seconds\": 86400\n    },\n    {\n      \"kind\": \"send_email\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000002\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

HttpResponse<String> response = Unirest.post("https://api.onesignal.com/apps/{app_id}/journeys")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"name\": \"Welcome series\",\n  \"description\": \"Onboard new users over their first week.\",\n  \"audience\": {\n    \"kind\": \"segment\",\n    \"included_segment_ids\": [\n      \"3f7c1e90-0000-0000-0000-000000000001\"\n    ],\n    \"excluded_segment_ids\": []\n  },\n  \"nodes\": [\n    {\n      \"kind\": \"send_push\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000001\"\n    },\n    {\n      \"kind\": \"wait\",\n      \"duration_seconds\": 86400\n    },\n    {\n      \"kind\": \"send_email\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000002\"\n    }\n  ]\n}")
  .asString();

using RestSharp;


var options = new RestClientOptions("https://api.onesignal.com/apps/{app_id}/journeys");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "<authorization>");
request.AddJsonBody("{\n  \"name\": \"Welcome series\",\n  \"description\": \"Onboard new users over their first week.\",\n  \"audience\": {\n    \"kind\": \"segment\",\n    \"included_segment_ids\": [\n      \"3f7c1e90-0000-0000-0000-000000000001\"\n    ],\n    \"excluded_segment_ids\": []\n  },\n  \"nodes\": [\n    {\n      \"kind\": \"send_push\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000001\"\n    },\n    {\n      \"kind\": \"wait\",\n      \"duration_seconds\": 86400\n    },\n    {\n      \"kind\": \"send_email\",\n      \"template_id\": \"9a8b7c6d-0000-0000-0000-000000000002\"\n    }\n  ]\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

{
  "id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "app_id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
  "name": "Welcome series",
  "description": "Onboard new users over their first week.",
  "state": "draft",
  "created_at": "2026-06-01T14:00:00Z",
  "updated_at": "2026-06-01T14:00:00Z",
  "started_at": null,
  "archived_at": null,
  "created_source": "public_api",
  "audience": {
    "kind": "segment",
    "included_segment_ids": [
      "3f7c1e90-0000-0000-0000-000000000001"
    ],
    "excluded_segment_ids": [],
    "future_additions_only": false
  },
  "early_exit": null,
  "reentry_rules": null,
  "schedule": null,
  "nodes": [
    {
      "id": "11111111-0000-0000-0000-000000000001",
      "kind": "send_push",
      "template_id": "9a8b7c6d-0000-0000-0000-000000000001"
    },
    {
      "id": "11111111-0000-0000-0000-000000000002",
      "kind": "wait",
      "duration_seconds": 86400
    },
    {
      "id": "11111111-0000-0000-0000-000000000003",
      "kind": "send_email",
      "template_id": "9a8b7c6d-0000-0000-0000-000000000002"
    }
  ],
  "concurrency_key": "dcae4794fee16e450e448e37a6f8d0a5a7335755ff8cc76606e3d04b2f574e46"
}

{
  "errors": [
    {
      "code": "invalid-payload",
      "title": "did not contain a required property of 'name'",
      "meta": {
        "attribute": "base",
        "path": "name"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "journey-not-entitled",
      "title": "Journeys are not enabled for this app",
      "meta": {}
    }
  ]
}

Beta. The Journeys API is in beta. Endpoints and response fields can still change.

Overview

Create a new Journey programmatically. A journey is defined by an entry audience and an ordered list of nodes.

Journeys are always created in the draft state. The request accepts only writable fields: sending a server-controlled field such as state or id returns a 400 validation error. Activate a journey with the Update journey API or from the OneSignal dashboard.

Server-assigned id fields on nodes and branches are rejected on create with a 400 validation error. Use client_node_id if you need to reference a node from elsewhere in the same request.

How to use this API

Authenticate with your App API Key. The authenticated key must have permission to create journeys. Only name is required. Sending an empty nodes array creates a journey with only its required defaults.

{
  "name": "Welcome series",
  "description": "Onboard new users over their first week.",
  "audience": {
    "kind": "segment",
    "included_segment_ids": ["YOUR_SEGMENT_ID"],
    "excluded_segment_ids": []
  },
  "nodes": [
    { "kind": "send_push", "template_id": "YOUR_TEMPLATE_ID" },
    { "kind": "wait", "duration_seconds": 86400 },
    { "kind": "send_email", "template_id": "YOUR_TEMPLATE_ID" }
  ]
}

Define the audience

The audience sets who enters the journey. It is either segment-based or event-triggered. Segments are referenced by UUID; every segment id (here, in early_exit, and in segment_membership branch conditions) must be a valid UUID that references an existing segment, or the request is rejected.

{
  "audience": {
    "kind": "segment",
    "included_segment_ids": ["YOUR_SEGMENT_ID"],
    "excluded_segment_ids": [],
    "future_additions_only": false
  }
}

{
  "audience": {
    "kind": "event_trigger",
    "name": "purchase",
    "attributes": [
      [{ "key": "item_count", "operator": "greater_or_equal", "value": "5" }]
    ]
  }
}

future_additions_only applies only to segment audiences and defaults to false. When true, only users who newly match the segment after the journey is activated can enter. Users already in the segment at activation never enter, even if they leave and rejoin later. For event-triggered audiences, attributes is a list of condition groups. Send a single group, whose conditions are AND’d together; sending more than one group is rejected. Valid operators are equal, not_equal, less, less_or_equal, greater_or_equal, greater, is, is_not, exists, not_exists, before, and after. The value field is not required for exists and not_exists. An event name is limited to 255 characters, and each attribute key to 255 and value to 1024. equal, not_equal, less, less_or_equal, greater_or_equal, and greater compare numerically: value must be a number (sent as a string, e.g. "5" or "19.99"). A non-numeric value on these operators is rejected. Use is and is_not to compare non-numeric values such as a currency code or plan name.

Add nodes

nodes is an ordered list. Linear nodes run in sequence. Each node requires a kind, plus the fields for that kind.

[
  { "kind": "wait", "duration_seconds": 3600 },
  { "kind": "send_push", "template_id": "YOUR_TEMPLATE_ID" },
  { "kind": "send_iam", "iam_id": "YOUR_IAM_ID", "user_ttl_seconds": 86400 },
  { "kind": "send_webhook", "webhook_id": "YOUR_WEBHOOK_ID" },
  { "kind": "tag", "assignments": { "loyalty_tier": "gold", "churned": "" } }
]

{
  "kind": "time_window",
  "relative_to": "schedule_in_timezone",
  "time_zone": "America/New_York",
  "use_user_time_zone": false,
  "windows": [
    { "start": { "hour": 9 }, "end": { "hour": 17 }, "day_of_week": 1 }
  ]
}

Each window’s day_of_week (1–7, where 1 is Monday) is a sibling of start and end, not nested inside them. start and end hold only hour and minute. A window with no day_of_week applies to every day of the week. Each window must span at least 15 minutes. A day-agnostic window is stored as seven per-day windows and returned in its original day-agnostic form, so a node read from a response can be sent back unchanged. One consequence: seven per-day windows that all share the same start and end are also returned as a single day-agnostic window. windows apply only when relative_to is schedule_in_timezone. With relative_to: "last_active_time" a journey must not send windows; doing so is rejected. A last_active_time node is returned without a windows key, so a node read from a response can be sent back unchanged. A send_push, send_email, or send_sms node’s template_id must reference an existing template of the matching channel (a push template for send_push, an email template for send_email, an SMS template for send_sms), or the request is rejected. Likewise a send_iam node’s iam_id and a send_webhook node’s webhook_id must reference existing resources. You may omit these ids while drafting, but a send node requires its id before the journey can go live. A wait node’s duration_seconds must be between 60 seconds and 1 year (31556952 seconds). These bounds are enforced on create and on every update, in every state. A tag node’s assignments keys are limited to 255 characters and values to 1024. An empty string value removes the tag. A node’s optional annotation is limited to 255.

Branching nodes

Branching nodes nest their sub-graphs inline through branches. After a branching node resolves, flow continues to the next sibling node.

{
  "kind": "split_range",
  "randomize_on_entry": false,
  "branches": [
    { "weight": 50, "nodes": [{ "kind": "send_push", "template_id": "YOUR_TEMPLATE_ID" }] },
    { "weight": 50, "nodes": [] }
  ]
}

{
  "kind": "yes_no",
  "branches": [
    {
      "condition": {
        "kind": "segment_membership",
        "included_segment_ids": ["YOUR_SEGMENT_ID"],
        "excluded_segment_ids": []
      },
      "nodes": [{ "kind": "send_email", "template_id": "YOUR_TEMPLATE_ID" }]
    },
    { "nodes": [] }
  ]
}

{
  "kind": "wait_until",
  "branches": [
    {
      "condition": { "kind": "event_trigger", "name": "purchase", "attributes": [] },
      "nodes": [{ "kind": "tag", "assignments": { "converted": "true" } }]
    }
  ],
  "expiration": { "duration_seconds": 604800, "exits": true }
}

split_range takes between 2 and 20 branches, and their weights must sum to 100. randomize_on_entry defaults to false. When true, the node assigns each user to a branch at random on entry.
yes_no requires exactly two branches. The branch with a condition is the “yes” branch; the branch without one is the “no” branch.
wait_until takes between 1 and 10 condition branches. The optional expiration timer exits the journey when exits is true, or continues to convergence when false. Its duration_seconds follows the same 60 second to 1 year bounds as a wait node. Omit expiration (or set it to null) to wait indefinitely.

Branch conditions

yes_no and wait_until branches use a condition object selected by its kind:

`kind`	Fields
`segment_membership`	`included_segment_ids`, `excluded_segment_ids` (segment UUIDs)
`on_notification_action`	`action`, plus `sending_node_id` or `client_node_id` to reference the sending node
`event_trigger`	`name`, `attributes`, optional `entry_event_match_attributes`

An on_notification_action condition branches on what a user did with a message sent earlier in the same journey. The sending node it references must be a message node (send_push, send_email, send_sms, send_iam, or send_webhook) that sits earlier in the flow than the branching node. On create, the sending node has no server id yet. Give it a client_node_id that is unique within the journey, and send that same value on the condition. client_node_id on the condition is write-only: the API resolves it to the sending node’s id.

{
  "nodes": [
    {
      "kind": "send_push",
      "client_node_id": "welcome_push",
      "template_id": "YOUR_TEMPLATE_ID"
    },
    {
      "kind": "yes_no",
      "branches": [
        {
          "condition": {
            "kind": "on_notification_action",
            "action": "clicked",
            "client_node_id": "welcome_push"
          },
          "nodes": [{ "kind": "send_email", "template_id": "YOUR_TEMPLATE_ID" }]
        },
        { "nodes": [] }
      ]
    }
  ]
}

Which actions are meaningful depends on the sending node’s channel:

Sending node	Supported actions
`send_push`	`received`, `clicked`
`send_email`	`received`, `clicked`, `opened`
`send_sms`	`received`, `opened`
`send_iam`	`clicked`, `opened`

A send_webhook node reports no user actions, so no action applies to it. An action outside this table is accepted by the API but never matches, so the branch is never taken. An event_trigger condition’s attributes use the same list-of-lists shape and operators as an event-triggered audience. Its optional entry_event_match_attributes is a list of objects, each with two fields, used to match an incoming event against the event that entered the user into the journey:

{
  "entry_event_match_attributes": [
    { "entry_event_key": "product_id", "incoming_event_key": "product_id" }
  ]
}

entry_event_key is the property on the entry event; incoming_event_key is the property on the incoming event compared against it. Both are required and must be non-blank.

Lifecycle and early exit

Optionally configure schedule, reentry_rules, and early_exit at the journey level.

{
  "schedule": { "start_at": "2026-07-01T14:00:00Z", "stop_at": "2026-08-01T14:00:00Z" },
  "reentry_rules": { "duration_seconds": 86400 },
  "early_exit": {
    "rules": {
      "on_segment": { "included_segment_ids": ["YOUR_SEGMENT_ID"] },
      "on_event": { "name": "exit_event" },
      "on_session": true,
      "when_not_in_audience": true
    },
    "tag_on_early_exit": { "has_exited": "true" }
  }
}

schedule timestamps must use UTC (Z or +00:00). A start_at must be at least 5 minutes in the future, and a stop_at must be in the future and later than start_at.
reentry_rules sets how long a user must wait before re-entering. duration_seconds must be at least 600 (10 minutes); a shorter value is rejected. Omit reentry_rules or send null to disallow re-entry.
early_exit removes a user before the journey completes. At least one rule must be set under rules; an early_exit that configures no rule is rejected. Send early_exit: null to remove early exit entirely.

Response

A successful request returns 201 Created with the full journey in its draft state, including server-assigned id fields and a concurrency_key. Pass that concurrency_key unchanged on a later Update journey request to avoid overwriting a concurrent change. Activate the draft by sending state: "active" on that same endpoint. The journey id and state, and node and branch id fields, are server-controlled. Sending any of them is rejected with 400 invalid-payload. A body app_id is ignored: the journey is always created under the app in the URL, and the response returns that app_id.

Error responses

Status	Code	Description
400	`invalid-payload`	The request failed validation. This covers schema failures (for example, an unknown node `kind`, an unknown property, or a server-controlled field) and business-logic failures (for example, `split_range` branch weights that do not sum to 100). `meta.path` points to the offending field when applicable.
403	`journey-not-entitled`	Journeys are not enabled for this app.
429		Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying. See Rate limits.

Coded errors use the shape { "errors": [{ "code", "title", "meta" }] }; for validation errors the failing field is in meta.attribute, with meta.path for the offending property. Branch on code and meta, not on title, whose wording can change between releases.

Headers

Authorization

string

default:Key YOUR_APP_API_KEY

required

Your App API key with prefix Key. See Keys & IDs.

Content-Type

string

default:application/json; charset=utf-8

required

Path Parameters

app_id

string

default:YOUR_APP_ID

required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

Body

application/json

name

string

default:YOUR_JOURNEY_NAME

required

Journey name.

description

string | null

Optional journey description.

audience

segment · object

The journey entry audience. Either a segment-based or event-triggered audience.

segment
event_trigger

Show child attributes

early_exit

object | null

Conditions that remove a user from the journey before it completes. At least one rule must be set under rules; an early_exit that configures no rule is rejected. Send null to remove early exit entirely, or null for an individual rule to drop just that rule.

Show child attributes

reentry_rules

object | null

Controls whether and how soon a user can re-enter the journey. null means re-entry is not allowed.

Show child attributes

schedule

object | null

Optional future start and/or stop time. null means no scheduled activation.

Show child attributes

nodes

object[]

Ordered list of journey nodes. Server-assigned id fields are rejected on create with a 400 validation error.

A journey node. The kind field selects the shape. Branching nodes (split_range, yes_no, wait_until) nest their sub-graphs inline via branches[].nodes.

Show child attributes

Response

201

Full journey representation returned by the detail and create endpoints.

string

Journey UUID. Read-only.

app_id

string

UUID of the app the journey belongs to. Read-only.

name

string

Journey name, up to 300 characters.

description

string | null

Journey description, up to 1024 characters. Defaults to an empty string.

state

enum<string>

Journey state. Read-only. New journeys are created as draft. processing is a transient state while an activation is in progress, and archived is a journey that has been stopped. Change it through the state field on Update journey.

Available options:

draft,

scheduled,

processing,

active,

archived

created_at

string

ISO 8601 creation time. Read-only.

updated_at

string

ISO 8601 last-update time. Read-only.

started_at

string | null

ISO 8601 time the journey was activated, or null. Read-only. May stay null briefly after you set state to active: activation is enqueued for processing, and started_at populates once the journey finishes processing and becomes active.

archived_at

string | null

ISO 8601 time the journey was archived, or null. Read-only.

created_source

string | null

Origin of the journey, for example public_api or dashboard. Read-only.

audience

segment · object

The journey entry audience. Either a segment-based or event-triggered audience.

segment
event_trigger

Show child attributes

early_exit

object | null

Show child attributes

reentry_rules

object | null

Controls whether and how soon a user can re-enter the journey. null means re-entry is not allowed.

Show child attributes

schedule

object | null

Optional future start and/or stop time. null means no scheduled activation.

Show child attributes

nodes

object[]

Ordered list of journey nodes.

A journey node. The kind field selects the shape. Branching nodes (split_range, yes_no, wait_until) nest their sub-graphs inline via branches[].nodes.

Show child attributes

concurrency_key

string

Opaque optimistic-concurrency token. Read-only. Pass it back on update to guard against overwriting a concurrent change (409 journey-stale). Send it back exactly as read from this response; do not construct or parse it.

Using the REST APIs

API reference

Create journey

Overview

How to use this API

Define the audience

Add nodes

Branching nodes

Branch conditions

Lifecycle and early exit

Response

Error responses

Headers

Path Parameters

Body

Response

​Overview

​How to use this API

​Define the audience

​Add nodes

​Branching nodes

​Branch conditions

​Lifecycle and early exit

​Response

​Error responses

Headers

Path Parameters

Body

Response

Overview

How to use this API

Define the audience

Add nodes

Branching nodes

Branch conditions

Lifecycle and early exit

Response

Error responses