Xulo Docs

REST API

Targeting

Name one target per call. A segment, a tag, a list of Subscription IDs, or a list of External IDs.

View as Markdown

A call names exactly one of these targets. None, or more than one, returns 422 with "Name one segment, or a tag, or the subscriptions, or the external ids. Do not mix them."

Every target reaches subscribed installs only. A list takes up to 500 ids and answers 200. A segment or a tag reaches every subscribed install that matches, up to 1,000,000 in one send. Sent now to an audience with someone in it, it answers 202 with status: "queued" and goes out in the background. See Send notification and Scheduling.

A segment

JSON
{ "included_segments": ["Opened in the last 7 days"] }

Name one audience. The name is matched without regard to case.

Name Audience
Subscribed or Subscribed Users Installs with push allowed and a token
Opened in the last 7 days Installs that opened the app in the last 7 days
Not opened for 30 days Installs that have not opened the app for 30 days
Test devices Installs you marked as test devices
The name of a saved segment That segment. See Segments.

More than one name returns 422 with "Send to one segment." A name that is not on the app returns 422 with "That segment is not on this app." An audience of more than 1,000,000 devices returns 422 with "This send reaches 1,200,000 devices. One send reaches at most 1,000,000."

A tag

JSON
{ "tag": { "key": "plan", "value": "pro", "include_missing": false } }

Matches subscribed installs whose person has the tag key set to value.

Field Notes
key Required. Up to 40 characters.
value Required. Text, up to 120 characters.
include_missing Optional, false by default. When true, people who do not have the key at all are included too.

In the dashboard, the audience of a tag send reads Devices tagged "plan" = "pro". With include_missing set to true it reads Devices tagged "plan" = "pro", plus devices that don't have this tag.

"0" is a value like any other. A tag of "0" does not match "1". See Tags.

A tag send has the same 1,000,000-device cap as a segment send.

Subscription IDs

JSON
{ "include_subscription_ids": ["00000000-0000-4000-8000-000000000001"] }

Up to 500 Subscription IDs, each a UUID. Each id is matched to a subscribed install of this app by its Subscription ID. If none has it, an install imported from OneSignal with that old Player ID matches.

An id that matches no subscribed install is skipped and counted in skipped. The call does not fail. A value that is not a UUID returns 422. More than 500 returns 422.

External IDs

JSON
{ "include_external_ids": ["USER_ID", "5"] }

Up to 500 External IDs. Each matches the subscribed installs logged in with that External ID, so one person with two phones gets it on both. A number is read as text, so 5 and "5" are the same. More than 500 returns 422.