# Data Formats JSON schemas for API requests and responses. Schemas define the structure, types, and validation rules for data exchanged with the API. # Attributes > Attributes appear on channels and Named Users. You can target an audience using attribute selectors. Available attribute types are Text, Number, Date, and JSON. {{< tip >}} Use [compound selectors](/docs/developer/rest-api/ua/schemas/audience-selection/#compoundselector) to negate (NOT) or select a value range. {{< /tip >}} ## Array {#attributesarray} The array can hold string, number, boolean, objects, and array. Accepts numbers and strings for integer/number type attributes, but your string must be convertible to a number or the request will fail. Objects must be valid JSON or the request will fail. **Array items — One of:** - [Array]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#attributesarray) --- ## Attribute assignment {#attributesobject} [Jump to examples ↓](#attributesobject-examples) - **`attributes`** `array` **REQUIRED** The attributes that you want to set for, or remove from, your `audience`. You can have both `set` and `remove` actions in the same request. Min items: 1 **One of:** - [Set Attribute]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#setattributeobject) Add a new attribute, or edit the value of an existing attribute, for the audience. - [Remove Attribute]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#removeattributeobject) Remove an existing attribute from the audience. **Used in:** - [Named User update]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#updatenameduser) - [Set or remove attributes on a Contact]({{< ref "/developer/rest-api/ua/operations/contacts/" >}}#modifycontactattributes) - [Set or remove attributes on channels]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelattributes) - [Set or remove attributes on Named Users]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#modifynameduserattributes) **Examples** *Attributes assignment* ```json { "attributes": [ { "action": "remove", "key": "minor_league" }, { "action": "set", "key": "position", "value": "LF" } ] } ``` --- ## Custom and predefined Attributes {#attributes} Attributes associated with a channel or Named User. This object contains predefined attributes that you enable and assign to the channel, or custom attributes that you create and assign. This object enumerates predefined attributes, but you can [create your own in the Airship dashboard](/docs/guides/audience/attributes/adding/). [Jump to examples ↓](#attributes-examples) - **`account_creation`** `string` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when the user created their account. Format: `date-time` - **`advertising_id`** `string` The IDFA associated with a user. - **`age`** `integer` The user's age. - **`altitude`** `number` The altitude associated with a user. - **`birthdate`** `string` The user's birthdate. - **`city`** `string` The city associated with the user. - **`company`** `string` The company that a user is associated with. - **`country`** `string` The country associated with the user. - **`email`** `string` A user's email address. - **`first_name`** `string` The first name of a user. - **`full_name`** `string` A user's first and last names. - **`gender`** `string` A user's gender. - **`home_phone`** `integer` The user's home phone number — similar to an SMS channel `msisdn`. - **`last_name`** `string` The last name of a user. - **`latitude`** `number` The latitude associated with a user — maybe their default location. - **`longitude`** `number` The longitude associated with a user — maybe their default location. - **`loyalty_tier`** `string` The loyalty program tier that a user is associated with, e.g., gold, platinum, etc. - **`mobile_phone`** `integer` The user's mobile phone number — similar to an SMS channel `msisdn`. - **`region`** `string` The state, province, principality, etc. associated with the user. - **`title`** `string` A default attribute. You must enable this attribute in the dashboard before you can assign it. - **`username`** `string` A user's username — generally a part of their login information. - **`work_phone`** `integer` The user's work phone number — similar to an SMS channel `msisdn`. - **`zipcode`** `integer` A user's zipcode. This is different from the SMS channel `ua_ndc` attribute, that records user's area code or phone number prefix. - **`*`** `object` **One of:** - `string` - `number` - `integer` **Used in:** - [Channel listing]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannels) - [Channel lookup]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannel) - [Look up an email address]({{< ref "/developer/rest-api/ua/operations/email/" >}}#getemailchannel) - [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser) - [SMS channel lookup]({{< ref "/developer/rest-api/ua/operations/sms/" >}}#getsmschannel) **Examples** *Example Attributes object* ```json { "device_attributes": { "ua_device_os": "10", "ua_country": "US", "ua_device_model": "SM-G973U", "ua_local_tz": "America/Los_Angeles", "ua_app_version": "2020-02-01T002322-goat", "ua_location_settings": "true", "ua_language": "en", "ua_sdk_version": "13.1.0", "ua_carrier": "Verizon " }, "attributes": { "first_name": "Cool", "last_name": "Person", "birthdate": "1983-03-15T00:00:00", } } ``` --- ## Date Attribute selector {#dateattribute} An attribute object with a `DATE` schema type. Performs absolute date comparisons for ISO-formatted date values or a relative date comparisons given an integer `value` and `precision`, e.g., `days`, `months`. Use a date attribute to target a channel or Named User based on the date values. [Jump to examples ↓](#dateattribute-examples) - **`attribute`** `string` **REQUIRED** The key for the date attribute that you previously defined in the Airship UI, e.g., `"birth_date"`. Min length: 1, Max length: 256 - **`operator`** `string` **REQUIRED** The operator used to evaluate the attribute expression. The `operator` that you use with a date attribute will determine which additional properties will be required in the object. See table for required fields. | Operator | Required properties | |---|---| | `is_empty` | `attribute` | | `before` | `attribute`, `value`, `precision`\* | | `after` | `attribute`, `value`, `precision`\* | | `range` | `attribute`, `value` | | `equals` | `attribute`, `value`, `precision`\*\* | \* *`precision` is required, but enum values are different than with an equals operator* \*\* *`precision` is required, but enum values are different than with a before or after operator* **Date Attribute Operators**: * `is_empty`— Evaluates to true if a channel or Named User does not have a value for the attribute. * `before`— Value is one of: - *String*, ISO 8601 inclusive date, optionally including an offset, e.g., `2007-03-01T13:00:00+08:00`. The value will be converted and stored as UTC. - *Integer*, Relative number of units from the current time (i.e., now) into the past. Example: `"before": 20` indicates "at least 20 years ago" given a `precision` of `years`. - *String* with the value `"now"`, representing the current date-time, i.e., "before now". When using the `now` value, no `precision` is required. **Note**: When using the `before` operator, precision value must be one of `years`, `months`, `days`, `hours`, or `minutes`. * `after`— Values for `after` behave identically to `before`, as described above. * `range`— An ISO 8601 time interval. The format consists of an inclusive start and an exclusive end time date separated with a `/`, e.g., `2019-03-01T13:00:00/2019-05-11T15:30:00`. `range` does not have a precision. * `equals`— allows for selecting specific or non-specific dates as determined by the `precision` provided in the attribute object. **Note**: When using the `equals` operator, `precision` must be one of: - `day` — an integer which represents the day of the month or "now". - `month` — an integer which represents the month of the year starting with 1 for Jan or "now" which will use the value of the current month. - `month_day` — a string in the format of "mm-dd" which represents a month and day. Ex. 05-04 is May 4th. Value can also be "now". If today is 2020-03-09, then value will be "03-09". - `year_month` — a string in the format of "yyyy-mm" which represents a year and month. Ex. 2020-05 is May 2020. Value can also be "now". If today is 2020-03-09, then value will be "2020-03". - `year_month_day` — a string in the format of "yyyy-mm-dd" which represents a specific year, month, and day. Ex. 2020-05-04. Value can also be "now". If today is 2020-03-09, then value will be "2020-03-09". - or value can be "now" which is the current date-time. Possible values: `is_empty`, `before`, `after`, `range`, `equals` - **`precision`** `string` The precision, expressed as a timing interval unit, that Airship uses to evaluate a date attribute expression. Possible values: `years`, `months`, `days`, `hours`, `minutes`, `day`, `month`, `month_day`, `year_month`, `year_month_day` - **`relative_to`** `string` Specifies whether the date is in the `future` or in the `past`. If missing, it defaults to `past`. Possible values: `future`, `past` - **`value`** `object` **One of:** - `string` A [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format). - `integer` An integer specifying the relative number of units, e.g., `days`, `years`, from the current time into the past. **Used in:** - [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment) - [Create Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#createsegment) - [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments) - [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment) - [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule) - [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules) - [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate) - [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification) - [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush) - [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments) - [Segment lookup]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#getsegment) - [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush) - [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions) - [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule) - [Update Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#updatesegment) - [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush) - [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate) - [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment) **Examples** *Date Attribute example* ```json { "audience": { "attribute": "birth_date", "operator": "equals", "precision": "month_day", "value": "05-04" } } ``` *Add four days to the current date* ```json { "audience": { "attribute": "day_of_travel", "operator": "equals", "value": "4", "precision": "days", "relative_to": "future" } } ``` *Compound selector using before and after date operators* ```json { "audience": { "AND": [ { "attribute": "birth_date", "operator": "after", "value": 55, "precision": "years" }, { "attribute": "birth_date", "operator": "before", "value": 40, "precision": "years" } ] }, "device_types": [ "android" ], "notification": { "alert": "Hello, Generation X!" } } ``` *Audience who purchased jeans* ```json { "audience": { "attribute": "item_purchased", "operator": "contains", "value": "jeans" } } ``` *Audience who did not purchase jeans* ```json { "audience": { "NOT":{ "attribute": "item_purchased", "operator": "contains", "value": "jeans" } } } ``` *Audience who did not make any purchase* ```json { "audience": { "attribute": "item_purchased", "operator": "is_empty", } } ``` *Integer value range* ```json { "audience": { "AND":[ { "attribute": "size", "operator": "greater", "value":12 }, { "attribute": "size", "operator": "less", "value": 15 } ] } } ``` --- ## Device Attributes {#device-attributes} Native attribute properties that Airship gathers automatically assigns to a channel. Varies by channel type. See: [Default Attributes](/docs/reference/data-collection/attributes/#default-attributes). For segmentation, when using `ua_app_version`, `ua_sdk_version`, or `ua_device_os`, only semantic versioning formatting is accepted, and anything after the third decimal place is excluded, e.g., `12.2.3-alpha` is compared as `12.2.3`. You can use operators `equals`, `contains`, `less`, `greater`, `is_empty` with values in the formats `1`, `1.2`, `1.2.3`. - **`ua_app_version`** `string` The app version that the channel uses. - **`ua_browser_name`** `string` The browser associated with a web channel. - **`ua_browser_type`** `string` The browser type associated with a web channel. Possible values: `mobile`, `desktop` - **`ua_browser_version`** `string` The browser version associated with a web channel. - **`ua_carrier`** `string` The cellular carrier of the device associated with an app channel. - **`ua_country`** `string` The 2-letter country code for an app or web channel. - **`ua_country_code`** `string` The country dialing code derived from the MSISDN associated with an SMS channel. - **`ua_device_model`** `string` The model of the device associated with an app channel. - **`ua_device_os`** `string` The operating system of the device associated with an app channel. - **`ua_language`** `string` The 2-letter language code for an app or web channel. - **`ua_local_tz`** `string` The time zone that the SDK registers for an app or web channel. - **`ua_location_settings`** `string` If `true`, location settings are enabled for an app channel. Possible values: `true`, `false` - **`ua_ndc`** `string` The National Destination Code aka area code derived from the MSISDN on an SMS channel. - **`ua_rcs_enabled`** `string` Rich Communication Services (RCS) capability for an SMS channel. Set to `true` when an RCS upgrade delivery receipt is received. Possible values: `true` - **`ua_sdk_version`** `string` The Airship SDK version associated with an app or web channel. - **`ua_subdivision`** `string` The ISO 3166-2 code derived from the MSISDN on an SMS channel. **Used in:** - [Channel listing]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannels) - [Channel lookup]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannel) - [Look up an email address]({{< ref "/developer/rest-api/ua/operations/email/" >}}#getemailchannel) - [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser) - [SMS channel lookup]({{< ref "/developer/rest-api/ua/operations/sms/" >}}#getsmschannel) --- ## JSON Attribute selector {#jsonattribute} An attribute object with a `JSON` schema type. Performs value comparisons based on the JSON value for an attribute on a channel or Named User. [Jump to examples ↓](#jsonattribute-examples) - **`attribute`** `string` **REQUIRED** The name of the attribute. Min length: 1, Max length: 1024 - **`where`** `object` **REQUIRED** An object that filters on the JsonPath expression that you provide. **OBJECT PROPERTIES** - **`compare_as`** `string` Selects the property type for comparison. Possible values: `text`, `number`, `date`, `boolean` - **`operator`** `string` **REQUIRED** The operator used to evaluate the attribute expression. If the JsonPath expression maps to an array, the only available operators are `is_empty`, `not_empty`, `contains`, or `not_contains`. Possible values: `equals`, `contains`, `not_contains`, `less`, `less_eq`, `greater`, `greater_eq`, `range`, `before`, `after`, `is_empty`, `not_empty` - **`precision`** `string` Used only for date values. Possible values: `minutes`, `days`, `months`, `years` - **`property`** `string` **REQUIRED** The JsonPath expression that will be used to look up the value in a predefined attribute, for example `"$.x['store']['book'][0]['title']"`. This is different from selecting based on primitive string attributes, because the JsonPath expression can map to a single attribute or an array of attributes. See [JsonPath](https://github.com/json-path/JsonPath) for more information about JsonPath expressions and usage. - **`relative_to`** `string` Used only for date values. Possible values: `future`, `past` - **`value`** `object` The value of the property you are filtering for in the `where` object. Use `compare_as` to select the type for comparison. This is required for all operators except `is_empty` and `not_empty`. **One of:** - `string` - `number` - `boolean` **Used in:** - [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment) - [Create Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#createsegment) - [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments) - [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment) - [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule) - [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules) - [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate) - [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification) - [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush) - [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments) - [Segment lookup]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#getsegment) - [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush) - [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions) - [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule) - [Update Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#updatesegment) - [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush) - [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate) - [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment) **Examples** *JSON Attribute examples* ```json { // Example 1 "audience": { "attribute": "books_on_books", "where": { "property": "$.x.store.book[*].title", "operator": "equals", "value": "Dracula", "compare_as": "text" } } } { // Example 2 "audience": { "attribute": "oh_look_a_book", "where": { "property": "$.x['store']['book'][0]['title']", "operator": "equals", "value": "Dracula", "compare_as": "text" } } } { // Example 3 "audience": { "attribute": "another_one", "where": { "property": "$.x.store.codes[*].sneakers", "operator": "equals", "value": 178394549, "compare_as": "number" } } } { // Example 4 "audience": { "attribute": "and_one_more", "where": { "property": "$.x['store']['codes'][0]['available']", "operator": "equals", "value": "true", "compare_as": "boolean" } } } ``` --- ## NPS survey Attributes {#npssurveyattributes} Attributes automatically generated by Airship based on data from your NPS surveys. - **`ua_nps_category`** `string` A category based on the score a user submits in an NPS survey. Scores of 9 and 10 are categorized as `promoter`, 7 and 8 are categorized as `passive`, and 0-6 are `detractor`. - **`ua_nps_score`** `number` The score (0-10) a user submits in an NPS (Net Promoter Score) survey. --- ## Number Attribute selector {#numberattribute} An attribute object with a `NUMBER` schema type. Performs value comparisons based on the number value for an attribute on a channel or Named User. [Jump to examples ↓](#numberattribute-examples) - **`attribute`** `string` **REQUIRED** The key for the number attribute that you previously defined in the Airship UI, e.g., `"lifetime_value"`. Min length: 1, Max length: 256 - **`operator`** `string` **REQUIRED** The operator used to evaluate the attribute expression. Possible values: `equals`, `contains`, `less`, `greater`, `is_empty` - **`value`** `number` **REQUIRED** The value of the number attribute that you are targeting. For example, `15000`. **Used in:** - [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment) - [Create Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#createsegment) - [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments) - [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment) - [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule) - [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules) - [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate) - [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification) - [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush) - [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments) - [Segment lookup]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#getsegment) - [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush) - [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions) - [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule) - [Update Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#updatesegment) - [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush) - [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate) - [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment) **Examples** *Number Attribute example* ```json { "audience": { "attribute": "lifetime_value", "operator": "greater", "value": 15000 } } ``` --- ## Remove Attribute {#removeattributeobject} Remove an existing attribute from the audience. [Jump to examples ↓](#removeattributeobject-examples) - **`action`** `string` **REQUIRED** Indicate that you want to `remove` an attribute from the audience. Possible values: `remove` - **`key`** `string` **REQUIRED** The attribute ID for the attribute you want to set. JSON attribute key values must be in format `#`. See [JSON Attributes](/docs/guides/audience/attributes/about/#json-attributes) in *About Attributes*. Max length: 64 - **`timestamp`** `string` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when the attribute changed. If you don't enter a timestamp, Airship uses the current time. Format: `date-time` **Used in:** - [Named User update]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#updatenameduser) - [Set or remove attributes on a Contact]({{< ref "/developer/rest-api/ua/operations/contacts/" >}}#modifycontactattributes) - [Set or remove attributes on channels]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelattributes) - [Set or remove attributes on Named Users]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#modifynameduserattributes) **Examples** *Remove Attribute* ```json { "action": "remove", "key": "minor_league" } ``` --- ## Set Attribute {#setattributeobject} Add a new attribute, or edit the value of an existing attribute, for the audience. [Jump to examples ↓](#setattributeobject-examples) - **`action`** `string` **REQUIRED** Indicate that you want to `set` an attribute on the audience. Possible values: `set` - **`key`** `string` **REQUIRED** The attribute ID for the attribute you want to set. JSON attribute key values must be in format `#`. See [JSON Attributes](/docs/guides/audience/attributes/about/#json-attributes) in *About Attributes*. Max length: 64 - **`timestamp`** `string` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when the attribute changed. If you don't enter a timestamp, Airship uses the current time. Format: `date-time` - **`value`** `object` **REQUIRED** The value that you want to set for an attribute. Accepts numbers and strings for integer/number type attributes, but your string must be convertible to a number or the request will fail. You can also set an object, which must be valid JSON or the request will fail. **One of:** - `string` - `number` - - **`exp`** `number` The JSON attribute expiration date, set as the number of seconds since the epoch (January 1st, 1970). After expiration, Airship ignores the Attribute where used in segmentation and personalization. If omitted, Airship automatically sets a value of 90 days from the current date and time. The maximum expiry delay for a JSON Attribute is 731 days. **Used in:** - [Named User update]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#updatenameduser) - [Set or remove attributes on a Contact]({{< ref "/developer/rest-api/ua/operations/contacts/" >}}#modifycontactattributes) - [Set or remove attributes on channels]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelattributes) - [Set or remove attributes on Named Users]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#modifynameduserattributes) **Examples** *Set Attribute with string value* ```json { "action": "set", "key": "position", "value": "LF" } ``` *Set JSON Attribute with its required object value* ```json { "action": "set", "key": "position#instance_42", "value": { "exp": 1731531110, "name": "LeftField", "rank": 2, "active" true, "extras": [ "rookie", "mvp" ] } } ``` --- ## Text Attribute selector {#textattribute} An attribute object with a `TEXT` schema type. Evaluates for the inclusion or exclusion of a text (string) attribute on a channel or Named User. [Jump to examples ↓](#textattribute-examples) - **`attribute`** `string` **REQUIRED** The key for the text attribute that you previously defined in the Airship UI, e.g., `"item_purchased"`. Min length: 1, Max length: 256 - **`operator`** `string` **REQUIRED** The operator used to evaluate the attribute expression. Possible values: `equals`, `contains`, `less`, `greater`, `is_empty` - **`value`** `string` **REQUIRED** The string you want to match when evaluating the attribute expression, e.g., `"jeans"`. Max length: 255 **Used in:** - [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment) - [Create Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#createsegment) - [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments) - [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment) - [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule) - [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules) - [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate) - [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification) - [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush) - [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments) - [Segment lookup]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#getsegment) - [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush) - [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions) - [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule) - [Update Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#updatesegment) - [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush) - [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate) - [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment) **Examples** *Text Attribute example* ```json { "audience": { "attribute": "item_purchased", "operator": "contains", "value": "jeans" } } ``` --- # Audience limits > Schemas for audience limits, additional audience checks, and ban list parameters. ## Audience limits object {#audiencelimitsobject} Defines limits to be applied to Push Notifications and standard in-app messages (not In-App Automations or Scenes) only. See [Audience Limit](/docs/guides/messaging/messages/delivery/delivery/#audience-limit) in the *Message delivery* user guide for additional information and limitations. [Jump to examples ↓](#audiencelimitsobject-examples) - **`max_recipients`** `integer` The maximum number of recipients a push can be delivered to. **Used in:** - [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment) - [Create pipeline (automated message)]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#createpipeline) - [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments) - [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment) - [Individual pipeline lookup]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getpipeline) - [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule) - [List existing pipelines]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getpipelines) - [List filtered pipelines]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getfilteredpipelines) - [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules) - [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification) - [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush) - [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush) - [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments) - [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush) - [Send message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#bulksendpush) - [Update pipeline]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#updatepipeline) - [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule) - [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush) - [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment) - [Validate message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatebulksendpush) - [Validate pipeline]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#validatepipeline) **Examples** *Audience limits* ```json { "options": { "audience_limits": { "max_recipients": 1000 } } } ``` --- ## Ban List parameters {#banlistparametersobject} A list of parameters, where the key and value are both strings, that will be used to override the default values set for variables in a [Ban List](/docs/guides/audience/segmentation/ban-lists/) request URL. [Jump to examples ↓](#banlistparametersobject-examples) - **`*`** `string` Example: `[object Object]` **Used in:** - [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment) - [Create pipeline (automated message)]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#createpipeline) - [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments) - [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment) - [Individual pipeline lookup]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getpipeline) - [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule) - [List existing pipelines]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getpipelines) - [List filtered pipelines]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#getfilteredpipelines) - [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules) - [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification) - [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush) - [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush) - [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments) - [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush) - [Send message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#bulksendpush) - [Update pipeline]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#updatepipeline) - [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule) - [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush) - [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment) - [Validate message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatebulksendpush) - [Validate pipeline]({{< ref "/developer/rest-api/ua/operations/automation/" >}}#validatepipeline) **Examples** *Ban List parameters* ```json { "ban_list_parameters": { "category": "api-cat" } } ``` --- # Audience selection > Objects that help you select and target an audience. ## Atomic selector {#atomicselector} Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag. [Jump to examples ↓](#atomicselector-examples) **One of:** - `string` The simplest selector, which targets the entire audience. - **Tag selector** `object` A tag is an arbitrary bit of metadata used for targeting devices. A tag specifier may or may not have an associated group declaration, indicating a `tag group` the tag belongs to, for example, `{"tag": "silver-member", "group": "loyalty"}`. If no tag group is specified, the default `device` group is used. - **`group`** `string` - **`tag`** `object` **REQUIRED** **One of:** - `string` - `array` - **Segment selector** `object` The Segment ID. - **`segment`** `object` **REQUIRED** **One of:** - `string` - `array` - **Channel selector** `object` The unique channel identifier used to target an open channel device or web device, i.e., web browser. - **`channel`** `object` **REQUIRED** **One of:** - `string` - `array` - **Named User selector** `object` A `named_user` is an alternate, non-unique name, mapped to a user profile in a different database, e.g., CRM, that can be used to target devices associated with that profile. - **`named_user`** `object` **REQUIRED** **One of:** - `string` - `array` - **Fire OS channel selector** `object` The unique channel identifier used to target a Fire OS device. - **`amazon_channel`** `object` **REQUIRED** **One of:** - `string` - `array` - **Android channel selector** `object` The unique channel identifier used to target an Android device. - **`android_channel`** `object` **REQUIRED** **One of:** - `string` - `array` - **Open channel selector** `object` The unique channel identifier used to target a device on an open platform. - **`open_channel`** `object` **REQUIRED** **One of:** - `string` - `array` - `string` A long or short code the app is configured to send from. For example, `12345`. - **SMS ID selector** `object` Selects a single SMS device. The `msisdn` must be `opted_in` to receive notifications. - **`msisdn`** `string` **REQUIRED** The recipient phone number. Min length: 1, Max length: 128 - **`sender`** `string` **REQUIRED** The sender that the app is configured to send SMS messages from. Min length: 1, Max length: 128 - **Static list selector** `object` A `static_list` is a subset of your audience defined by a CSV file containing Channel IDs or Named Users. - **`static_list`** `object` **REQUIRED** **One of:** - `string` - `array` - **Subscription List selector** `object` An single instance or array of subscription list IDs. - **`subscription_list`** `object` **REQUIRED** **One of:** - `string` - `array` - [Text Attribute selector]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#textattribute) An attribute object with a `TEXT` schema type. Evaluates for the inclusion or exclusion of a text (string) attribute on a channel or Named User. - [Number Attribute selector]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#numberattribute) An attribute object with a `NUMBER` schema type. Performs value comparisons based on the number value for an attribute on a channel or Named User. - [Date Attribute selector]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#dateattribute) An attribute object with a `DATE` schema type. Performs absolute date comparisons for ISO-formatted date values or a relative date comparisons given an integer `value` and `precision`, e.g., `days`, `months`. Use a date attribute to target a channel or Named User based on the date values. - [JSON Attribute selector]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#jsonattribute) An attribute object with a `JSON` schema type. Performs value comparisons based on the JSON value for an attribute on a channel or Named User. - **Alias selector** `object` A legacy mechanism used for mapping devices to a customer ID, e.g., a CRM identifier. Superseded by `named_user`. - **`alias`** `object` **REQUIRED** **One of:** - `string` - `array` - **APID selector** `object` A legacy identifier for targeting Android and Windows devices, superseded by `android_channel`. - **`apid`** `object` **REQUIRED** **One of:** - `string` - `array` - [Activity audience object]({{< ref "/developer/rest-api/ua/schemas/event-segmentation/" >}}#activityobject) The `activity` object defines the target audience based on lifecycle actions or Custom Event activity, using comparison operators on activity count and recency. Optionally include a `where` object, which filters for specific activity values. In the example to the right, the target audience is users who have opened your app from a notification from the "neowise" campaign at least twice, 3 days ago. - `string` A special selector used in Pipelines to indicate that the audience of the push is composed of the device or devices that activated the trigger. See [Pipeline objects](/docs/developer/rest-api/ua/schemas/pipeline-objects/) for more information. **Used in:** - [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment) - [Create Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#createsegment) - [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments) - [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment) - [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule) - [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules) - [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate) - [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification) - [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush) - [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments) - [Segment lookup]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#getsegment) - [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush) - [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions) - [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule) - [Update Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#updatesegment) - [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush) - [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate) - [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment) **Examples** *Example audience selection by tag* ```json { "audience": { "tag": "sfGiants", "group": "favorite_teams" } } ``` *Example SMS channel audience* ```json { "audience" : { "sms_id" : { "sender" : "12345", "msisdn" : "15552243311" } } } ``` *Example audience segment* ```json { "audience" : { "segment" : "" } } ``` *Example audience of Named Users* ```json { "audience" : { "named_user" : "user-id-54320" } } ``` *Example audience of static list* ```json { "audience" : { "static_list" : "name_of_list" } } ``` --- ## Audience selector (max 100) {#audienceselector100} An audience selector forms the expression that determines the set of channels to target. **One of:** - [Compound selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#compoundselector) Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. - [Atomic selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#atomicselector) Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag. **Used in:** - [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions) --- ## Audience selector (max 1000) {#audienceselector1000} An audience selector forms the expression that determines the set of channels to target. **One of:** - [Compound selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#compoundselector) Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. - [Atomic selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#atomicselector) Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag. **Used in:** - [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment) - [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments) - [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment) - [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule) - [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules) - [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate) - [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification) - [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush) - [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments) - [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush) - [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule) - [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush) - [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate) - [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment) --- ## Compound selector {#compoundselector} Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. [Jump to examples ↓](#compoundselector-examples) **One of:** - **AND selector** `object` AND selector - **`AND`** `array` Min items: 1, Max items: 10 **One of:** - [Compound selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#compoundselector) Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. - [Atomic selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#atomicselector) Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag. - **OR Selector** `object` OR selector - **`OR`** `array` Min items: 1, Max items: 10 **One of:** - [Compound selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#compoundselector) Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. - [Atomic selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#atomicselector) Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag. - **NOT Selector** `object` NOT selector - **`NOT`** `object` **One of:** - [Compound selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#compoundselector) Compound selectors combine boolean operators (AND, OR, or NOT) with atomic or nested compound selectors. - [Atomic selector]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#atomicselector) Atomic selectors are the simplest way to identify a single device, i.e., app or browser installation, or a group of devices. These selectors are either a unique identifier for the device such as a Channel ID or metadata that maps to the device (or multiple devices) such as a tag. **Used in:** - [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment) - [Create Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#createsegment) - [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments) - [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment) - [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule) - [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules) - [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate) - [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification) - [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush) - [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments) - [Segment lookup]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#getsegment) - [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush) - [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions) - [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule) - [Update Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#updatesegment) - [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush) - [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate) - [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment) **Examples** *Example with implicit `OR`* ```json { "audience" : { "tag" : ["apples", "oranges", "bananas"] } } ``` *Example with nested selectors* ```json { "audience": { "AND": [ {"OR": [ {"tag": "sports"}, {"tag": "entertainment"} ]}, {"tag": "language_en"} ] } } ``` *Example `NOT` selector* ```json { "audience": { "AND": [ { "tag": "Federer fan" }, { "NOT": { "tag": "Messi fan" } } ] } } ``` --- # Bulk sending > Schemas for bulk sending operations, including scheduled bulk sends. Bulk sending allows you to target recipients by providing audience identifiers at send time. ## Bulk send object {#bulksendobject} A bulk send object describes everything about a [Send message with bulk ID](/docs/developer/rest-api/ua/operations/bulk-sending/#bulksendpush) or [Schedule message with bulk ID](/docs/developer/rest-api/ua/operations/bulk-sending/#schedulebulksendpush) notification. The acceptable fields are identical to a standard push with two exceptions. The audience field can only be a single `bulk_id` and there can only be one `device_type`. [Jump to examples ↓](#bulksendobject-examples) - **`audience`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`bulk_id`** `string` **REQUIRED** A unique string obtained from the [Create bulk send audience operation](/docs/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) to target an audience for bulk sending. Format: `uuid` - **`campaigns`** `object` <[Campaigns object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#campaignsobject)> An object specifying custom campaign categories related to the notification. - **`device_types`** `array[string]` **REQUIRED** An array containing exactly one targeted platform. Min items: 1, Max items: 1 Possible values: `android`, `amazon`, `ios`, `web`, `sms`, `mms`, `email`, `open::open_platform_name` - **`feed_references`** `object` <[Feed references object]({{< ref "/developer/rest-api/ua/schemas/external-data-feeds-references/" >}}#feedreferences)> An object used to indicate that an external data feed should be invoked, the name of the feed to invoke, and the way in which to invoke it. You can only include a feed if you include a `templates` object in the payload or set the `personalization` option to `true`. - **`global_attributes`** `object` The global attributes object may contain an arbitrary set of keys and values, including arrays and nested objects, which will be added to the global attributes rendering namespace for this push. Top-level keys must start with a letter and cannot start with the reserved sequence ``ua_``. If the global attributes object is nonempty, it implies the ``personalization: true`` option. - **`in_app`** `object` <[In-app message]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#inappobject)> A JSON object describing an in-app message payload. - **`localizations`** `array` <[Localization object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#localization)> An array of localizations. Channels bearing the specified language/country combination will receive the corresponding message. - **`message`** `object` **One of:** - [Message Center object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#messageobject) A Message Center message. - [Message Center with template]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#messageobjectwithtemplate) Use a `template` with a message center message. You can reference a template by ID, or use `{{handlebars}}` directly in your message. - **`message_type`** `string` <[Message type]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#messagetype)> Indicates the purpose of a message. Possible values: `transactional`, `commercial` - **`notification`** `object` <[Notification object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#notificationobject)> The notification payload that is required unless either `message` or `in_app` is present. You can provide an `alert` and any platform overrides that apply to the `device_type` platforms you specify. - **`options`** `object` <[Push options]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#pushoptions)> A JSON dictionary for specifying non-payload options related to the delivery of the push. - **`orchestration`** `object` An object used to indicate the strategy to employ when deciding which channels to target for a contact. An orchestration object can be stored in Airship as the default strategy. If the orchestration section is included in a push payload, it will override the configured default value. The overall default strategy is `fan_out`. **OBJECT PROPERTIES** - **`channel_priority`** `array[string]` An array of channel types in priority order. Required if `type` is set to `channel_priority`. - **`type`** `string` **REQUIRED** The name of the orchestration strategy to employ. Possible values: `channel_priority`, `fan_out`, `triggering_channel`, `last_active` - **`snippet_references`** `object` <[Snippet references object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#snippetreferences)> An object used to indicate that a set of snippets should be loaded for use in message content. Use the following syntax in your payload: `{{> your_snippet_name }}` to reference the snippet content within a notification or rich message. See [Snippets](/docs/guides/personalization/content/snippets/) to see how to create a snippet in the Airship dashboard. **Used in:** - [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush) - [Send message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#bulksendpush) - [Validate message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatebulksendpush) **Examples** *Bulk send object* ```json { "audience" : { "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22" }, "device_types" : [ "open::rcs" ], "notification" : { "alert" : "Welcome to the winter sale!!" }, "campaigns": { "categories": ["winter sale", "west coast"] } } ``` --- ## Scheduled bulk send object {#scheduledbulksendobject} A scheduled bulk send object wraps a [bulk send object](/docs/developer/rest-api/ua/schemas/others/#bulksendobject). It describes when the notification should be sent, an optional name for the notification, and the object defining the notification itself, which must be a bulk send object or [Templated message content](/docs/developer/rest-api/ua/schemas/others/#templatedmessagecontent). The scheduled date must be within 60 days. [Jump to examples ↓](#scheduledbulksendobject-examples) - **`name`** `string` A name for the scheduled push message. - **`push`** `object` **REQUIRED** **One of:** - [Bulk send object]({{< ref "/developer/rest-api/ua/schemas/bulk-sending/" >}}#bulksendobject) A bulk send object describes everything about a [Send message with bulk ID](/docs/developer/rest-api/ua/operations/bulk-sending/#bulksendpush) or [Schedule message with bulk ID](/docs/developer/rest-api/ua/operations/bulk-sending/#schedulebulksendpush) notification. The acceptable fields are identical to a standard push with two exceptions. The audience field can only be a single `bulk_id` and there can only be one `device_type`. - [Templated message content]({{< ref "/developer/rest-api/ua/schemas/bulk-sending/" >}}#templatedmessagecontent) Customers may use a template to specify message content instead of using static specification. The request format is consistent with Template Schemes. See description [Platform Override Templates](/docs/developer/rest-api/ua/schemas/platform-overrides-with-templates/). All columns (for CSV) or keys (for JSON) not prefixed with `ua_` are considered merge fields. Prefixed columns/keys are not usable in template evaluation. If the value of a delivery variable is also needed in the template, the requester should duplicate it into an unprefixed column. No verification is done in this API that the provided set of merge values matches the fields of the template. Customers using the UI will pass through a step where they'll be alerted that some template field has no matching column in the uploaded CSV. Custom Create and Send fields are not limited to strings and can contain numbers, booleans, arrays, hierarchical JSON, etc. Merge fields are allowed to use nested property names in CSV upload headers by using a subset of legal [Handlebars](/docs/guides/personalization/handlebars/) template expression syntax. - **`schedule`** `object` **REQUIRED** As defined by the [Schedule object](/docs/developer/rest-api/ua/schemas/schedules/#scheduleobject), but only the `scheduled_time` key is valid. **OBJECT PROPERTIES** - **`scheduled_time`** `string` **REQUIRED** The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when you want to perform your Create and Send operation. Users will receive the notification as soon as possible after the specified date-time. Format: `date-time` **Used in:** - [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush) **Examples** *Scheduled bulk send object* ```json { "schedule": { "scheduled_time" : "2024-11-07T12:00:00" }, "name" : "scheduled bulk send", "push" : { "audience" : { "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22" }, "device_types" : [ "open::rcs" ], "notification" : { "alert" : "Hope you voted" }, "campaigns": { "categories": ["midterms2024", "getoutthevote2024"] } } } ``` --- ## Templated message content {#templatedmessagecontent} Customers may use a template to specify message content instead of using static specification. The request format is consistent with Template Schemes. See description [Platform Override Templates](/docs/developer/rest-api/ua/schemas/platform-overrides-with-templates/). All columns (for CSV) or keys (for JSON) not prefixed with `ua_` are considered merge fields. Prefixed columns/keys are not usable in template evaluation. If the value of a delivery variable is also needed in the template, the requester should duplicate it into an unprefixed column. No verification is done in this API that the provided set of merge values matches the fields of the template. Customers using the UI will pass through a step where they'll be alerted that some template field has no matching column in the uploaded CSV. Custom Create and Send fields are not limited to strings and can contain numbers, booleans, arrays, hierarchical JSON, etc. Merge fields are allowed to use nested property names in CSV upload headers by using a subset of legal [Handlebars](/docs/guides/personalization/handlebars/) template expression syntax. [Jump to examples ↓](#templatedmessagecontent-examples) - **`template`** `object` **One of:** - [Create and Send to email channels]({{< ref "/developer/rest-api/ua/schemas/create-and-send/" >}}#email) The payload for a Create and Send operation to email channels. When sending to email channels, `device_types` must be set to `email`. - [Create and Send to SMS channels]({{< ref "/developer/rest-api/ua/schemas/create-and-send/" >}}#sms) The payload for a Create and Send operation to SMS channels. When sending to SMS channels, `device_types` must be set to `sms`. - [Create and Send MMS notification]({{< ref "/developer/rest-api/ua/schemas/create-and-send/" >}}#mms) The payload for a Create and Send operation that sends a multimedia payload (MMS) to SMS channels. When sending an MMS payload, `device_types` must be set to `mms`. - [Create and Send to open channels]({{< ref "/developer/rest-api/ua/schemas/create-and-send/" >}}#open) The payload for a Create and Send operation to open channels. When sending to open channels, the `device_type` must be set to `open::`. **Used in:** - [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush) **Examples** *Example templated Send a message with bulk ID* ```json { "audience" : { "bulk_id" : "36d5a261-0454-40f5-b952-942c4b2b0f22" }, "device_types" : [ "open::rcs" ], "notification" : { "open::rcs" : { "template": { "template_id" : "09641749-f288-46e6-8dc6-fae592e8c092" } } } } ``` *Example templated Create and Send a message* ```json { "audience": { "create_and_send": [ { "ua_address": "some-person@example.com", "ua_commercial_opted_in": "2023-04-01T18:45:30", "ua_open_tracking_opted_in": "2023-04-01T18:45:30", "name": "Some Person, Esq.", "totalPurchases": "$ 239.85", "items": [ { "text": "New Line Sneakers", "image": "https://marketing-image-production.example.com/uploads/newlinesneakers.png", "price": "$ 79.95" }, { "text": "Old Line Sneakers", "image": "https://marketing-image-production.example.com/uploads/oldlinesneakers.png", "price": "$ 79.95" }, { "text": "Blue Line Sneakers", "image": "https://marketing-image-production.example.com/uploads/bluelinesneakers.png", "price": "$ 79.95" } ], "receipt": true, "onlineAccount": { "username": "coolUser", "email_receipt": true, "email": "someone@example.com" }, "userAddress": { "address01": "1234 Fake St.", "address02": "Apt. 123", "city": "Place", "state": "CO", "zip": "80202" }, "num_of_purchases": 4 }, { "ua_address": "some-other-person@example.com", "ua_commercial_opted_in": "2023-04-01T18:45:30", "ua_click_tracking_opted_in": "2023-04-01T18:45:30", "name": "The Honorable Some Other Person" } ] }, "device_types": [ "email" ], "notification": { "email": { "template": { "fields": { "subject": "Hi there, {{name}}", "plaintext_body": "Your \n{{#each items}} {{this.text}} {{this.price}} {{/each}}\n are on the way{{#with userAddress}} to {{address01}}{{/with}}!" } }, "sender_name": "Ultimate Sender", "message_type": "transactional", "sender_address": "no-reply@valid-sender-example.com", "reply_to": "no-reply@valid-sender-example.com" } } } ``` *Example CSV audience with nested keys* ```text/csv ua_address,ua_commercial_opted_in,name,address.city,address.state,items.[0].name,items.[0].code,items.[1].name,items.[1].code someone@example.com,2023-04-01T18:45:30,Joe Someone,Portland,OR,Rubber Gloves,abaccgdsagsde,Bleach Alternative,cacadgdesgaga else@example.com,2023-04-21T16:13:01,Sir Else,Seattle,WA,Flashlight,zxcvxcbzxcbza,Shovel,aldfkghalsdkg ``` *Equivalent JSON audience definition* ```json { "audience": { "create_and_send" : [ { "ua_address" : "someone@example.com", "ua_commercial_opted_in" : "2023-04-01T18:45:30", "name" : "Joe Someone", "address" : { "city" : "Portland", "state" : "OR" }, "items" : [ { "name" : "Rubber Gloves", "code" : "abaccgdsagsde" }, { "name" : "Bleach Alternative", "code" : "cacadgdesgaga" } ] }, { "ua_address" : "else@example.com", "ua_commercial_opted_in" : "2023-04-21T16:13:01", "name" : "Sir Else", "address" : { "city" : "Seattle", "state" : "WA" }, "items" : [ { "name" : "Flashlight", "code" : "zxcvxcbzxcbza" }, { "name" : "Shovel", "code" : "aldfkghalsdkg" } ] } ] } } ``` --- # Channels > Schemas for channel management, including channel objects, registration, updates, and channel associations. ## Channel listing object {#channellistingobject} Describes a channel listing object. [Jump to examples ↓](#channellistingobject-examples) - **`address`** `string` The address to send push notifications to when `device_type` is `email` or `open`. For all other `device_type` values, this key is replaced with `push_address`. Example: `email@example.com` - **`alias`** `string` **DEPRECATED** Displays the alias associated with the channel, if one exists. Aliases are the precursor to Named Users, our user mapping system. If you are using aliases, please upgrade to Named Users. Listed as `null` when not set. Example: `alias_nope` Nullable: true - **`attributes`** `object` <[Custom and predefined Attributes]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#attributes)> A dictionary of attributes that you've associated with the channel. See the [Attributes guide](/docs/guides/audience/attributes) for more information about creating and assigning attributes. The attributes listed here are "predefined" by Airship, but you can create new attributes in the Airship dashboard. Attributes associated with a channel or Named User. This object contains predefined attributes that you enable and assign to the channel, or custom attributes that you create and assign. This object enumerates predefined attributes, but you can [create your own in the Airship dashboard](/docs/guides/audience/attributes/adding/). - **`background`** `boolean` If true, the device can receive background push notifications. If false, it cannot. This field only appears for iOS devices. - **`channel_id`** `string` The unique channel identifier for a device. Format: `uuid` Example: `9c36e8c7-5a73-47c0-9716-99fd3d4197d5` - **`commercial_opted_in`** `string` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when a user gave explicit permission to receive commercial emails. Format: `date-time` - **`commercial_opted_out`** `string` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when a user explicitly denied permission to receive commercial emails. Format: `date-time` - **`created`** `string` The creation [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) of this channel. Format: `date-time` Read only: true - **`device_attributes`** `object` <[Device Attributes]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#device_attributes)> Native attribute properties that Airship gathers automatically assigns to a channel. Varies by channel type. See: [Default Attributes](/docs/reference/data-collection/attributes/#default-attributes). For segmentation, when using `ua_app_version`, `ua_sdk_version`, or `ua_device_os`, only semantic versioning formatting is accepted, and anything after the third decimal place is excluded, e.g., `12.2.3-alpha` is compared as `12.2.3`. You can use operators `equals`, `contains`, `less`, `greater`, `is_empty` with values in the formats `1`, `1.2`, `1.2.3`. - **`device_type`** `string` Specifies the device platform for a channel. Possible values: `ios`, `android`, `amazon`, `web`, `open`, `email`, `sms` - **`email_address`** `string` The email address associated with the email channel when `device_type` is `email`. Example: `name@example.com` - **`installed`** `boolean` If true, the channel is installed. If false, it is uninstalled. - **`ios`** `object` <[iOS channel object]({{< ref "/developer/rest-api/ua/schemas/channels/" >}}#ioschannelobject)> Contains parameters that apply when the `device_type` is set to `ios`. - **`last_registration`** `string` The last registration [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) of this channel, if known. Format: `date-time` Nullable: true Read only: true - **`msisdn`** `string` The phone number associated with the SMS channel. Must be numeric characters only, without leading zeros. Max length: 15 Example: `15035556789` - **`named_user_id`** `string` A customer-chosen ID that represents the device user, e.g., CRM ID. This ID cannot have leading or trailing whitespace. Listed as `null` when not set. Min length: 1, Max length: 128 Example: `john_doe` Nullable: true - **`open`** `object` <[Open channel options]({{< ref "/developer/rest-api/ua/schemas/channels/" >}}#openchanneloptionsobject)> Contains options that apply when the `device_type` is set to `open`. - **`opt_in`** `boolean` If true, the channel is opted in to push notifications. If false, it is not. Required for all types except email. - **`opt_in_date`** `string` `(SMS only)` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when the SMS channel gave permission to receive messages. Format: `date-time` Example: `2022-07-07T03:23:13` - **`opt_out_date`** `string` `(SMS only)` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when the SMS channel opted out of receiving messages. Format: `date-time` Example: `2022-07-08T03:23:13` - **`push_address`** `string` Required if `opt_in` is true. The address to send push notifications to for all `device_type` values other than `email` and `open`. When `device_type` is `email` or `open`, this key is replaced with `address`. Example: `FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660` Nullable: true - **`subscription_lists`** `array` <[Subscription List object]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#subscriptionlistobject)> Lists all the subscription lists that this channel is subscribed to. - **`suppression_state`** `string` If an email channel is suppressed, the reason for its suppression. Email channels with any suppression state set will not have any delivery to them fulfilled. If a more specific reason is not known, use `imported`. Possible values: `spam_complaint`, `commercial_spam_complaint`, `bounce`, `imported` - **`tag_groups`** `object` <[Tag Group object]({{< ref "/developer/rest-api/ua/schemas/tags/" >}}#taggroupobject)> One or more tag group objects (including [Device Property Tags](/docs/reference/device-property-tags/)) associated with this channel. Tags belong to Tag Groups. Tag Groups appear within the `tags` object for a Named User or the `tag_groups` object for a channel. See also [Device Properties](/docs/reference/data-collection/device-properties/) ``ua_`` is a reserved prefix for Airship-specific tag groups. A Tag Group has two parts: a "name" string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters. - **`tags`** `array[string]` An array of tags associated with this channel. Min items: 0, Max items: 1000 Example: `Federer fan,Messi fan` - **`transactional_opted_in`** `string` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when a user gave explicit permission to receive transactional emails. Users do not need to opt-in to receive transactional emails unless they have previously opted out. Format: `date-time` - **`transactional_opted_out`** `string` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when a user explicitly denied permission to receive transactional emails. Format: `date-time` - **`web`** `object` Contains parameters that apply when the `device_type` is set to `web`. **OBJECT PROPERTIES** - **`subscription`** `object` The web subscription. This optional field is not present for cases where a browser is registered (for purposes of Feature Flags) but isn't opted-in to push notifications. **OBJECT PROPERTIES** - **`keys`** `object` Encryption keys required for signing the push package. **OBJECT PROPERTIES** - **`auth`** `string` The authentication secret. - **`p256dh`** `string` The public key. - **`user_agent_string`** `string` The full user agent string. **Used in:** - [Channel listing]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannels) - [Channel lookup]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannel) - [Look up an email address]({{< ref "/developer/rest-api/ua/operations/email/" >}}#getemailchannel) - [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser) - [SMS channel lookup]({{< ref "/developer/rest-api/ua/operations/sms/" >}}#getsmschannel) **Examples** *Example iOS channel* ```json { "channel_id": "b8f9b663-0a3b-cf45-587a-be880946e881", "device_type": "ios", "installed": true, "background": true, "opt_in": false, "push_address": "FE66489F304DC75B8D6E8200DFF8A456E8DAEACEC428B427E9518741C92C6660", "created": "2020-08-08T20:41:06", "last_registration": "2020-05-01T18:00:27", "named_user_id": "some_id_that_maps_to_your_systems", "alias": null, "tags": [ "tag1", "tag2" ], "tag_groups": { "sports fan": ["Federer fan", "Messi fan"], "music fan": [ "Beyonce", "Muse" ], "ua_locale_country": [ "US" ], "ua_locale_language": [ "en" ] }, "ios": { "badge": 0, "quiettime": { "start": null, "end": null }, "tz": "America/Los_Angeles" } } ``` --- ## Email channel associated by Contact {#emailchannelassociatedbycontactobject} An email channel associated with a Contact. [Jump to examples ↓](#emailchannelassociatedbycontactobject-examples) - **`channel_id`** `string` The unique identifier. Format: `uuid` - **`commercial_opted_in`** `string` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when a user gave explicit permission to receive commercial emails. Format: `date-time` - **`email_address`** `string` The email address corresponding to the channel. - **`type`** `string` The channel type. Possible values: `email` **Examples** *Example* ```json { "type": "email", "channel_id": "463c4643-a16c-48da-9585-f2c5406f828b", "email_address": "d*******r@example.com", "commercial_opted_in": "2024-02-11T00:00:00" } ``` --- ## iOS channel object {#ioschannelobject} Contains parameters that apply when the `device_type` is set to `ios`. - **`badge`** `integer` The iOS badge number. Must be greater than zero. Format: `int32` - **`quiettime`** `object` Quiet time settings. Requires presence of `tz`. **OBJECT PROPERTIES** - **`end`** `string` Quiet time end in `HH:MM` format. Example: `07:30` Nullable: true - **`start`** `string` Quiet time start in `HH:MM` format. Example: `21:30` Nullable: true - **`scheduled_summary`** `boolean` If true, the scheduled summary notification status is enabled. - **`time_sensitive`** `boolean` If true, the time sensitive notification status is enabled. - **`tz`** `string` The channel's time zone. A list of possible time zone values is maintained at the [IANA Time Zone Database](http://www.iana.org/time-zones). Example: `America/Los_Angeles` Nullable: true **Used in:** - [Channel listing]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannels) - [Channel lookup]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannel) - [Look up an email address]({{< ref "/developer/rest-api/ua/operations/email/" >}}#getemailchannel) - [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser) - [SMS channel lookup]({{< ref "/developer/rest-api/ua/operations/sms/" >}}#getsmschannel) --- ## Open channel options {#openchanneloptionsobject} Contains options that apply when the `device_type` is set to `open`. - **`identifiers`** `object` A set of up to 100 key:value pairs representing identifiers for this channel in your own delivery systems and delivered as a part of webhook payloads. Example: `[object Object]` - **`old_address`** `string` If a channel exists for the value of `old_address`, replaces that channel's address with the value of `address`. Use infrequently, such as when an end user's phone number or email address permanently changes. - **`open_platform_name`** `string` **REQUIRED** The name of the open channel that this `channel_id` is registered on. Example: `Slack` **Used in:** - [Channel listing]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannels) - [Channel lookup]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#getchannel) - [Look up an email address]({{< ref "/developer/rest-api/ua/operations/email/" >}}#getemailchannel) - [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser) - [SMS channel lookup]({{< ref "/developer/rest-api/ua/operations/sms/" >}}#getsmschannel) --- ## SMS channel associated by Contact {#smschannelassociatedbycontactobject} An SMS channel associated with a Contact. [Jump to examples ↓](#smschannelassociatedbycontactobject-examples) - **`channel_id`** `string` The unique identifier. Format: `uuid` - **`msisdn`** `string` The phone number corresponding to the channel. - **`opt_in`** `boolean` If true, the channel is opted in to push notifications. If false, it is not. - **`sender`** `string` The sender corresponding to the channel. - **`type`** `string` The channel type. Possible values: `sms` **Examples** *Example* ```json { "type": "sms", "channel_id": "a537ac78-ef4f-4f74-8536-6fd620549186", "sender": "1234", "msisdn": "*******3379", "opt_in": true } ``` --- # Contacts > Schemas for managing Contacts, including batch operations, anonymous contact resolution, and channel contact operations. ## Contacts scoped batch item {#contactsscopedbatchitem} Contains `scope` and `subscription_lists` and/or `tags`. At least one of `subscription_lists` or `tags` must be provided. [Jump to examples ↓](#contactsscopedbatchitem-examples) - **`scope`** `array` <[Scopes]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#scopes)> **REQUIRED** - **`subscription_lists`** `object` <[Named User Subscription List object]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#namedusersubscriptionlistsobject)> Defines the Subscription List changes. - **`tags`** `array[object]` **Used in:** - [Scoped Contact batch operations]({{< ref "/developer/rest-api/ua/operations/contacts/" >}}#performscopedcontactbatchoperations) **Examples** *Example contacts scoped batch item* ```json { "scope": ["web", "email", "app"], "subscription_lists": { "subscribe": ["subscription_1", "subscription_2"], "unsubscribe": ["subscription_3"] } } ``` --- # Content objects > Schemas for [Content](/developer/rest-api/ua/operations/content/) templates and per-channel `content` payloads. ## App and web content template object {#appandwebtemplatesobject} The app and web push fields for a template. [Jump to examples ↓](#appandwebtemplatesobject-examples) - **`alert`** `string` **REQUIRED** The text that will display in your push notification. - **`icon`** `string` A string representing a URL or an image file included in the application's resources. - **`summary`** `string` Supplemental text displayed with the notification. - **`title`** `string` A heading that appears above the notification text when applicable. **Used in:** - [Create content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#createcontenttemplate) - [Create or update content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplatebyexternalid) - [List content templates]({{< ref "/developer/rest-api/ua/operations/content/" >}}#listcontenttemplates) - [Look up a content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplate) - [Look up a content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplatebyexternalid) - [Update content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplate) **Examples** *Example app and web template object* ```json { "title": "Shoe sale on {{level}} floor!", "alert": "All the shoes are on sale {{name}}!", "summary": "Don't miss out!", "icon": "shoes" } ``` --- ## Content template object {#contenttemplateobject} A reusable template containing fields for a message type. Can be referenced by its UUID or a customer-defined external ID. [Jump to examples ↓](#contenttemplateobject-examples) - **`content`** `object` **REQUIRED** The content of the given type, using the associated model object below. **One of:** - [Email content template object]({{< ref "/developer/rest-api/ua/schemas/content-objects/" >}}#emailtemplatesobject) The email-specific fields for a template. - [SMS content template object]({{< ref "/developer/rest-api/ua/schemas/content-objects/" >}}#smstemplatesobject) The SMS-specific fields for a template. - [Open channel content template object]({{< ref "/developer/rest-api/ua/schemas/content-objects/" >}}#openchanneltemplatesobject) The open channel-specific fields for a template. - [App and web content template object]({{< ref "/developer/rest-api/ua/schemas/content-objects/" >}}#appandwebtemplatesobject) The app and web push fields for a template. - [Message Center content template object]({{< ref "/developer/rest-api/ua/schemas/content-objects/" >}}#messagecentertemplatesobject) The Message Center-specific fields for a template. - **`created_at`** `string` The [date-time](#date-time-format) when this template was created. Format: `date-time` Read only: true - **`description`** `string` The description of the template. - **`external_id`** `string` An optional ID for referencing this template in future API calls. Must be unique within your project. - **`feed_references`** `object` <[Feed references object]({{< ref "/developer/rest-api/ua/schemas/external-data-feeds-references/" >}}#feedreferences)> An object used to indicate that an external data feed should be invoked, the name of the feed to invoke, and the way in which to invoke it. You can only include a feed if you include a `templates` object in the payload or set the `personalization` option to `true`. - **`id`** `string` The unique ID assigned to the template. Used to retrieve or reference the template in other endpoints. Format: `uuid` Read only: true - **`modified_at`** `string` The [date-time](#date-time-format) when this template was last modified. Format: `date-time` Read only: true - **`name`** `string` **REQUIRED** The human-readable name of the template. - **`snippet_references`** `object` <[Snippet references object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#snippetreferences)> An object used to indicate that a set of snippets should be loaded for use in message content. Use the following syntax in your payload: `{{> your_snippet_name }}` to reference the snippet content within a notification or rich message. See [Snippets](/docs/guides/personalization/content/snippets/) to see how to create a snippet in the Airship dashboard. - **`type`** `string` **REQUIRED** The type of message. Possible values: `email`, `sms`, `open`, `app`, `web`, `message_center` **Used in:** - [Create content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#createcontenttemplate) - [Create or update content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplatebyexternalid) - [List content templates]({{< ref "/developer/rest-api/ua/operations/content/" >}}#listcontenttemplates) - [Look up a content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplate) - [Look up a content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplatebyexternalid) - [Update content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplate) **Examples** *Example content template object* ```json { "id": "ef34a8d9-0ad7-491c-86b0-aea74da15161", "external_id": "customer-defined-id", "name": "Welcome Message", "description": "Our welcome message", "type": "email", "content": { "subject": "Welcome!", "html_body": "Hi, {{first_name}}! {{>copyright}}", "plaintext_body": "Hi, {{first_name}}!" }, "created_at": "2020-08-17T11:10:02Z", "modified_at": "2020-08-17T11:10:02Z", "feed_references": { "feeds": [ { "name": "featured_product" } ], "defaults": { "featured_product": { "category": "featured" } } }, "snippet_references": { "snippets": [ { "name": "copyright" } ] } } ``` --- ## Email content template object {#emailtemplatesobject} The email-specific fields for a template. [Jump to examples ↓](#emailtemplatesobject-examples) - **`html_body`** `string` **REQUIRED** The HTML content of the email. - **`plaintext_body`** `string` **REQUIRED** The plaintext content of the email. - **`subject`** `string` **REQUIRED** The email subject. **Used in:** - [Create content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#createcontenttemplate) - [Create or update content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplatebyexternalid) - [List content templates]({{< ref "/developer/rest-api/ua/operations/content/" >}}#listcontenttemplates) - [Look up a content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplate) - [Look up a content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplatebyexternalid) - [Update content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplate) **Examples** *Example email template object* ```json { "subject": "Welcome!", "html_body": "Hi, {{first_name}}!", "plaintext_body": "Hi, {{first_name}}!" } ``` --- ## Message Center content template object {#messagecentertemplatesobject} The Message Center-specific fields for a template. [Jump to examples ↓](#messagecentertemplatesobject-examples) - **`html_body`** `string` **REQUIRED** The body of the message. This can be a full HTML message. - **`title`** `string` A heading that appears above the message and in the Message Center inbox. **Used in:** - [Create content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#createcontenttemplate) - [Create or update content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplatebyexternalid) - [List content templates]({{< ref "/developer/rest-api/ua/operations/content/" >}}#listcontenttemplates) - [Look up a content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplate) - [Look up a content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplatebyexternalid) - [Update content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplate) **Examples** *Example Message Center template object* ```json { "html_body": "

Richtext body goes here

Unsubscribe

", "title": "Message Center Notification" } ``` --- ## Open channel content template object {#openchanneltemplatesobject} The open channel-specific fields for a template. [Jump to examples ↓](#openchanneltemplatesobject-examples) - **`alert`** `string` **REQUIRED** The text that will display in your open channel message. - **`media_attachment`** `string` The URL for media you want to include in your message. - **`summary`** `string` Supplemental text displayed with the notification. - **`title`** `string` A heading that appears above the notification text when applicable. **Used in:** - [Create content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#createcontenttemplate) - [Create or update content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplatebyexternalid) - [List content templates]({{< ref "/developer/rest-api/ua/operations/content/" >}}#listcontenttemplates) - [Look up a content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplate) - [Look up a content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplatebyexternalid) - [Update content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplate) **Examples** *Example open channel template object* ```json { "title": "SMS Alert!", "alert": "A shorter alert for SMS users", "summary": "A longer summary of text alongside the notification", "media_attachment": "https://example.com/cat_standing_up.jpeg" } ``` --- ## SMS content template object {#smstemplatesobject} The SMS-specific fields for a template. [Jump to examples ↓](#smstemplatesobject-examples) - **`alert`** `string` **REQUIRED** The SMS content. **Used in:** - [Create content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#createcontenttemplate) - [Create or update content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplatebyexternalid) - [List content templates]({{< ref "/developer/rest-api/ua/operations/content/" >}}#listcontenttemplates) - [Look up a content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplate) - [Look up a content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplatebyexternalid) - [Update content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplate) **Examples** *Example SMS template object* ```json { "alert": "My SMS message" } ``` --- # Create and Send > Objects and samples for [`/create-and-send`](/developer/rest-api/ua/operations/bulk-sending/#createandsend) endpoints. A full object can contain parts of schedule, template, audience, and platform override objects (for `email`, `sms`, or `open::` platforms). The `notification` payload for Create and Send objects supports both stored and inline templates. Using inline templates, you can define and populate variables to personalize notifications to your new channels. {{< note >}} You cannot update channel information or opt-in status using Create and Send. If you want to update channels, refer to the appropriate email, SMS, or open channel endpoints. {{< /note >}} ## Create and Send MMS notification {#mms} The payload for a Create and Send operation that sends a multimedia payload (MMS) to SMS channels. When sending an MMS payload, `device_types` must be set to `mms`. [Jump to examples ↓](#mms-examples) - **`audience`** `object` **REQUIRED** **One of:** - **SMS audience for Create and Send payloads** `object` The SMS information and opt-in parameters for the audience you want to send to. Unknown MSISDNs are registered as new channels. - **`create_and_send`** `array[object]` **REQUIRED** Each object in the array represents an MSISDN you want to send to. Unknown MSISDNs are registered as new channels. Channel registration fields are prefixed with `ua_` and have the same requirements as the [SMS channel registration endpoint](/docs/developer/rest-api/ua/operations/sms/#registersmschannel). All other fields represent variables if `notification` specifies a `template`. Max items: 1000 - - **`bulk_id`** `string` **REQUIRED** A unique string obtained from the [Create bulk send audience operation](/docs/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) to target an audience for bulk sending. Format: `uuid` - **`device_types`** `array[string]` **REQUIRED** The platform you want to send notifications to. Possible values: `email`, `mms`, `sms`, `open::` - **`notification`** `object` **REQUIRED** **OBJECT PROPERTIES** - **`mms`** `object` **REQUIRED** A platform override for MMS messages; `device_types` must be set to `mms`. A notification with a platform override that does not match your `device_types` will result in a 400 error. **One of:** - [MMS platform overrides]({{< ref "/developer/rest-api/ua/schemas/platform-overrides/" >}}#mmsoverrideobject) Provides the content for a push to MMS channels. If `sms` is in the `device_type` array, your request may include this object. It cannot be combined with an SMS Platform Override as a single push can only include either an SMS or MMS payload. - [MMS notification with inline template]({{< ref "/developer/rest-api/ua/schemas/platform-overrides-with-templates/" >}}#mmsoverridewithtemplate) Template and notification overrides for a Create and Send payload with `device_types` set to `mms`. With a template, you can provide and populate variables and conditional statements based on those variables. Conditionals begin with `{{#operator}}` and end with `{{/operator}}`. For more information, see [Handlebars](/docs/guides/personalization/handlebars/). **Used in:** - [Create and Send a message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#createandsend) - [Schedule a Create and Send message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulecreateandsendoperations) - [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush) - [Validate Create and Send payload]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatecreateandsendpayload) **Examples** *Example Create and Send for MMS without template* ```json { "audience": { "create_and_send": [ { "ua_msisdn": "15558675309", "ua_sender": "15551234567", "ua_opted_in": "2020-11-11T18:45:30", } ] }, "device_types": [ "mms" ], "notification": { "mms": { "fallback_text": "Delivery failed, but you should still check this out.", "subject" : "Hey, thanks for subscribing!", "slides": [ { "text": "Check this out!", "media": { "url": "https://i.example.com/1t466Om.jpg", "content_type": "image/jpeg", "content_length": 52918 } } ] } } } ``` --- ## Create and Send to email channels {#email} The payload for a Create and Send operation to email channels. When sending to email channels, `device_types` must be set to `email`. [Jump to examples ↓](#email-examples) - **`audience`** `object` **REQUIRED** **One of:** - **Email audience for Create and Send payloads** `object` The email addresses and opt-in agreements for the audience you want to send to. Unknown addresses are registered as new channels. - **`create_and_send`** `array[object]` **REQUIRED** Each object in the array represents an email address you want to send to. Unknown addresses are registered as new channels. Channel registration fields are prefixed with `ua_` and have the same requirements as the [email registration endpoint](/docs/developer/rest-api/ua/operations/email/#registeremailchannel). You cannot provide optional channel registration fields using this endpoint (like `locale_language` for email channels). All other fields represent variables if `notification` specifies a `template`. Max items: 1000 - - **`bulk_id`** `string` **REQUIRED** A unique string obtained from the [Create bulk send audience operation](/docs/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) to target an audience for bulk sending. Format: `uuid` - **`campaigns`** `object` <[Campaigns object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#campaignsobject)> An object specifying custom campaign categories related to the notification. - **`device_types`** `array[string]` **REQUIRED** The platform you want to send notifications to. Possible values: `email`, `mms`, `sms`, `open::` - **`notification`** `object` **REQUIRED** An `alert` notification or a platform override matching the value in `device types`. A notification with a platform override that does not match your `device_types` will result in a 400 error. **OBJECT PROPERTIES** - **`email`** `object` You can either provide the standard object that you would provide when performing a `/api/push` to an email platform, or you can provide some of the email platform override fields along with an inline template. **One of:** - [Email overrides]({{< ref "/developer/rest-api/ua/schemas/platform-overrides/" >}}#emailoverrideobject) Notification fields specific to email messages. This object is required when `email` is specified in the payload's `device_types` field. - [Email notification with template]({{< ref "/developer/rest-api/ua/schemas/platform-overrides-with-templates/" >}}#emailoverridewithtemplate) Notification fields specific to email messages with an inline template for use in a [Create and Send](/docs/developer/rest-api/ua/operations/bulk-sending/#createandsend) payload. Using a template enables you to provide and populate variables in your notification. You can also add conditional statements based on those variables, determining message text that to send to each member of your audience. Conditionals begin with `{{#operator}}` and end with `{{/operator}}`. For more information, see [Handlebars](/docs/guides/personalization/handlebars/). **Used in:** - [Create and Send a message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#createandsend) - [Schedule a Create and Send message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulecreateandsendoperations) - [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush) - [Validate Create and Send payload]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatecreateandsendpayload) **Examples** *Example object* ```json { "audience": { "create_and_send" : [ { "ua_address": "new@example.com", "ua_commercial_opted_in": "2020-11-29T10:34:22" }, { "ua_address" : "ben@example.com", "ua_commercial_opted_out": "2020-11-29T12:45:10" }, { "ua_address" : "mary@example.com", "ua_email_suppression_state": "BOUNCE" } ] }, "device_types" : [ "email" ], "notification" : { "email": { "subject": "Welcome to the Winter Sale! ", "html_body": "

Seasons Greetings

Check out our winter deals!

Unsubscribe

", "plaintext_body": "Greetings! Check out our latest winter deals! [[ua-unsubscribe href=\"http://unsubscribe.urbanairship.com/email/success.html\"]]", "message_type": "transactional", "sender_name": "Airship", "sender_address": "team@airship.com", "reply_to": "no-reply@airship.com", "click_tracking": false, "open_tracking": false, "attachments": [ { "id": "0e10a6b9-725c-4f6b-9af2-9ef5b31328c0", }, { "id": "5503b5fe-ed69-4609-bef6-6fef0e6e428f" } ] } }, "campaigns": { "categories": ["winter sale", "west coast"] } } ``` --- ## Create and Send to open channels {#open} The payload for a Create and Send operation to open channels. When sending to open channels, the `device_type` must be set to `open::`. [Jump to examples ↓](#open-examples) - **`audience`** `object` **REQUIRED** **One of:** - **Open audience for Create and Send payloads** `object` The Open channel addresses and opt-in information for the audience you want to send to. Unknown addresses are registered as new channels. - **`create_and_send`** `array[object]` **REQUIRED** Each object in the array represents an Open channel address you want to send to. Unknown addresses are registered as new channels. Channel registration fields are prefixed with `ua_` and have the same requirements as open channel registration. Max items: 1000 - - **`bulk_id`** `string` **REQUIRED** A unique string obtained from the [Create bulk send audience operation](/docs/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) to target an audience for bulk sending. Format: `uuid` - **`campaigns`** `object` <[Campaigns object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#campaignsobject)> An object specifying custom campaign categories related to the notification. - **`device_types`** `array[string]` **REQUIRED** The platform you want to send notifications to. Possible values: `email`, `mms`, `sms`, `open::` - **`notification`** `object` **REQUIRED** An `alert` notification or a platform override matching the value in `device types`. A notification with a platform override that does not match your `device_types` will result in a 400 error. **OBJECT PROPERTIES** - **`open::open_platform_name`** `object` <[Open channel overrides with template]({{< ref "/developer/rest-api/ua/schemas/platform-overrides-with-templates/" >}}#openchanneloverridewithtemplate)> Use a `template` with an open channel-specific message. You can reference a template by ID, or use `{{handlebars}}` directly in your message. **Used in:** - [Create and Send a message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#createandsend) - [Schedule a Create and Send message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulecreateandsendoperations) - [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush) - [Validate Create and Send payload]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatecreateandsendpayload) **Examples** *Example object* ```json { "audience" : { "create_and_send": [ { "ua_address" : "36d5a261-0454-40f5-b952-942c4b2b0f22", "name": "Perry" } ] }, "device_types" : [ "open::smart_fridge" ], "notification" : { "open::smart_fridge": { "alert" : "Hey {{name}}, you're out of ice cream!" } }, "campaigns": { "categories": ["needs_ice_cream", "cookies_and_cream"] } } ``` --- ## Create and Send to SMS channels {#sms} The payload for a Create and Send operation to SMS channels. When sending to SMS channels, `device_types` must be set to `sms`. [Jump to examples ↓](#sms-examples) - **`audience`** `object` **REQUIRED** **One of:** - **SMS audience for Create and Send payloads** `object` The SMS information and opt-in parameters for the audience you want to send to. Unknown MSISDNs are registered as new channels. - **`create_and_send`** `array[object]` **REQUIRED** Each object in the array represents an MSISDN you want to send to. Unknown MSISDNs are registered as new channels. Channel registration fields are prefixed with `ua_` and have the same requirements as the [SMS channel registration endpoint](/docs/developer/rest-api/ua/operations/sms/#registersmschannel). All other fields represent variables if `notification` specifies a `template`. Max items: 1000 - - **`bulk_id`** `string` **REQUIRED** A unique string obtained from the [Create bulk send audience operation](/docs/developer/rest-api/ua/operations/bulk-sending/#bulkuploadcreateandsendplatform) to target an audience for bulk sending. Format: `uuid` - **`campaigns`** `object` <[Campaigns object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#campaignsobject)> An object specifying custom campaign categories related to the notification. - **`device_types`** `array[string]` **REQUIRED** The platform you want to send notifications to. Possible values: `email`, `mms`, `sms`, `open::` - **`notification`** `object` **REQUIRED** An `alert` notification or a platform override matching the value in `device types`. A notification with a platform override that does not match your `device_types` will result in a 400 error. **OBJECT PROPERTIES** - **`sms`** `object` **One of:** - [SMS platform overrides]({{< ref "/developer/rest-api/ua/schemas/platform-overrides/" >}}#smsoverrideobject) Provides override options when `sms` is one of the `device_types` specified in the payload. - [SMS notification with template]({{< ref "/developer/rest-api/ua/schemas/platform-overrides-with-templates/" >}}#smsoverridewithtemplate) Notification fields specific to SMS messages with an inline template for use in a [Create and Send](/docs/developer/rest-api/ua/operations/bulk-sending/#createandsend) payload. Using a template enables you to provide and populate variables in your notification. You can also add conditional statements based on those variables, determining message text that to send to each member of your audience. Conditionals begin with `{{#operator}}` and end with `{{/operator}}`. For more information, see [Handlebars](/docs/guides/personalization/handlebars/). **Used in:** - [Create and Send a message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#createandsend) - [Schedule a Create and Send message]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulecreateandsendoperations) - [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush) - [Validate Create and Send payload]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatecreateandsendpayload) **Examples** *Example object* ```json { "audience": { "create_and_send" : [ { "ua_msisdn": "15558675309", "ua_sender": "12345", "ua_opted_in": "2020-11-11T18:45:30" } ] }, "device_types" : [ "sms" ], "notification" : { "sms": { "alert": "Check out our winter sale! https://www.example.com/amazingly/long/url-that-I-want-to-shorten", "expiry": 172800, "shorten_links": true } }, "campaigns": { "categories": ["winter sale", "west coast"] } } ``` --- # Event segmentation > Event Segmentation lets you target audiences based on lifecycle actions or Custom Events that have occurred. To Segment based on event activity, include an [Activity Object](/developer/rest-api/ua/schemas/event-segmentation/#activityobject) in your audience, and an optional [Where Object](/developer/rest-api/ua/schemas/event-segmentation/#whereobject) to filter on specific event properties. ## Activity audience object {#activityobject} The `activity` object defines the target audience based on lifecycle actions or Custom Event activity, using comparison operators on activity count and recency. Optionally include a `where` object, which filters for specific activity values. In the example to the right, the target audience is users who have opened your app from a notification from the "neowise" campaign at least twice, 3 days ago. [Jump to examples ↓](#activityobject-examples) - **`activity`** `string` **REQUIRED** The target event activity, e.g., `app_open`. Default event values are enumerated below. If you create a custom or predefined event that you wish to segment users on, you must register the event in the Airship dashboard. See [Manage events](/docs/guides/audience/events/manage/). Possible values: `app_open`, `message_received`, `message_center_read`, `message_center_delivered`, `message_center_deleted`, `in_app_message_display`, `in_app_message_resolution`, `in_app_message_expiration`, `screen_view`, `web_session`, `web_click`, `short_link_click`, `first_seen`, `sms_aborted`, `sms_delivered`, `sms_dispatched`, `sms_expired`, `sms_failed`, `sms_rejected`, `sms_undeliverable`, `sms_unknown`, `email_bounce`, `email_click`, `email_delay`, `email_delivered`, `email_injection`, `email_open`, `email_unsubscribe`, `scene_displayed`, `scene_completed`, `scene_incomplete`, `survey_displayed`, `survey_submitted`, `survey_not_submitted` - **`after`** `object` A date value for an absolute comparison or an integer value for a relative comparison. **One of:** - `string` A [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format), for example: `"after": "2020-08-01T12:00:00"`. - `integer` - **`before`** `object` A date value for an absolute comparison or an integer value for a relative comparison. **One of:** - `string` A [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format), for example: `"before": "2020-08-01T12:00:00"`. - `integer` - **`metric`** `string` The metric you are targeting for the event. When using the metric `count` or `total_value`, `operator` and `value` are required. When using either `first` or `last`, `operator` and `value` are not allowed. Use one of the following combinations instead: * `before`/`precision` * `after`/`precision` * `on`/`on_precision` | Metric | Description | |---|---| | `count` | Evaluate based on the number of event occurrences. | | `total_value` | Evaluate based on the cumulative event `value` associated with the target user. | | `last` | Evaluate based on the last occurrence of an event for a given user/time window. | | `first` | Evaluate based on the first occurrence of an event for a given user/time window. | Possible values: `count`, `total_value`, `last`, `first` - **`on`** `string` Use `on` in conjunction with the `first` or `last` metric to indicate either a specific date or period with precision. Use either: * A date in ISO 8601 format, e.g., `2020-08-10T17:28:34+0000` or * An integer that, when combined with the `on_precision` property, specifies the time period. For example, use `"on": 12` with `"on_precision: "month"` to target events that occurred in December. **One of:** - `string` A [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format). - `integer` - **`on_precision`** `string` When using the `first` or `last` metric with the `on` property to target events on. For example, for the 5th of any month, or only in March, use `on_precision`. Possible values: `day`, `month`, `month_day`, `year_month`, `year_month_day` - **`operator`** `string` **REQUIRED** The comparison operator used to evaluate the activity expression. Use these operators (greater/less than, equal to, equal or greater/equal or less) when the `metric` is either `count` or `total_value`. Possible values: `greater`, `less`, `equals`, `greater_eq`, `less_eq` - **`precision`** `string` If using a relative number (integer) for the `before`/`after`/`on` property, the `precision` value will be interpreted as the number of time units ago, e.g., *7 days ago*. Defaults to `days`. Possible values: `days`, `weeks`, `months`, `years` Default: `days` - **`value`** `number` **REQUIRED** The value that the `operator` uses to evaluate the target audience. - **`where`** `object` <[Where object]({{< ref "/developer/rest-api/ua/schemas/event-segmentation/" >}}#whereobject)> `where` is an object that filters on the existence of prior user activity, specified by event properties that you provide. **Used in:** - [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment) - [Create Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#createsegment) - [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments) - [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment) - [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule) - [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules) - [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate) - [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification) - [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush) - [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments) - [Segment lookup]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#getsegment) - [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush) - [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions) - [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule) - [Update Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#updatesegment) - [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush) - [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate) - [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment) **Examples** *Activity audience object* ```json { "audience": { "activity": "app_open", "operator": "greater", "value": 2, "after": 3, "precision": "days", "where": { "property": "/_triggering_push/campaigns/categories", "operator": "equals", "value": "neowise" } } } ``` --- ## Where object {#whereobject} `where` is an object that filters on the existence of prior user activity, specified by event properties that you provide. [Jump to examples ↓](#whereobject-examples) - **`compare_as`** `string` Selects the property type for comparison. Possible values: `text`, `number`, `date`, `boolean` - **`operator`** `string` **REQUIRED** The operator in question Possible values: `greater`, `less`, `equals`, `greater_eq`, `less_eq`, `contains`, `present`, `range`, `before`, `after` - **`precision`** `string` Used only for date values. Possible values: `minutes`, `days`, `months`, `years` - **`property`** `string` **REQUIRED** The Custom Event property on which to filter for inclusion in the audience. See [Event Segmentation Properties](/docs/guides/audience/events/events/#events-reference) for properties reference. - **`relative_to`** `string` Used only for date values. Possible values: `future`, `past` - **`value`** `object` **REQUIRED** The value of the property you are filtering for in the `where` object. Use `compare_as` to select the type for comparison. **One of:** - `string` A [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format), e.g., `2020-08-10T17:28:34+0000`. - `number` - `boolean` **Used in:** - [Create experiment (A/B Test)]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#createexperiment) - [Create Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#createsegment) - [Experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiments) - [Experiment lookup]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getexperiment) - [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule) - [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules) - [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate) - [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification) - [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush) - [Scheduled experiment listing]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#getscheduledexperiments) - [Segment lookup]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#getsegment) - [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush) - [Subscribe or unsubscribe channels to/from subscription lists]({{< ref "/developer/rest-api/ua/operations/channels/" >}}#modifychannelsubscriptions) - [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule) - [Update Segment]({{< ref "/developer/rest-api/ua/operations/segments/" >}}#updatesegment) - [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush) - [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate) - [Validate experiment]({{< ref "/developer/rest-api/ua/operations/a-b-tests/" >}}#validateexperiment) **Examples** *Example payload to an audience of users who have opened your app as a result of receiving a specific push ID. * ```json { "audience": { "activity": "app_open", "metric": "count", "operator": "greater", "value": 0, "where": { "property": "/_triggering_push/push_id", "operator": "equals", "compare_as": "text", "value": "636abb88-5642-4035-998d-a04c93c499ad" } }, "device_types": [ "ios", "android" ], "notification": { "alert": "Did you get that thing I sent you?" } } ``` --- # External Data Feeds references > A push request property specifying which [External Data Feeds](/guides/personalization/sources/external-data-feeds/) should be invoked and with what parameters in order to support personalization from feed content. {{< important >}} You must first [create an external data feed in the dashboard](/docs/guides/personalization/sources/external-data-feeds/), then you can refer to its ID as the `name` in the feed references object. The Coupons service is a type of external data feed. See [Coupons](/docs/guides/personalization/sources/coupons/) for formatting and usage information. {{< /important >}} ## Feed references object {#feedreferences} An object used to indicate that an external data feed should be invoked, the name of the feed to invoke, and the way in which to invoke it. You can only include a feed if you include a `templates` object in the payload or set the `personalization` option to `true`. [Jump to examples ↓](#feedreferences-examples) - **`defaults`** `object` Default parameter values for your feed. These values override any defaults you set for your feed in the Airship Dashboard. - **`feeds`** `array[object]` **REQUIRED** An array of feeds that you want to use to personalize your message. **Used in:** - [Create content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#createcontenttemplate) - [Create or update content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplatebyexternalid) - [List a specific schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedule) - [List content templates]({{< ref "/developer/rest-api/ua/operations/content/" >}}#listcontenttemplates) - [List schedules]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#getschedules) - [Look up a content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplate) - [Look up a content template by external ID]({{< ref "/developer/rest-api/ua/operations/content/" >}}#getcontenttemplatebyexternalid) - [Schedule a notification]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#schedulenotification) - [Schedule a templated push]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#scheduletemplatedpush) - [Schedule message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#schedulebulksendpush) - [Send a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#sendpush) - [Send message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#bulksendpush) - [Update content template]({{< ref "/developer/rest-api/ua/operations/content/" >}}#updatecontenttemplate) - [Update schedule]({{< ref "/developer/rest-api/ua/operations/schedules/" >}}#updateschedule) - [Validate a push]({{< ref "/developer/rest-api/ua/operations/push/" >}}#validatepush) - [Validate message with bulk ID]({{< ref "/developer/rest-api/ua/operations/bulk-sending/" >}}#validatebulksendpush) **Examples** *Example push external data feeds request* ```http POST /api/push HTTP/1.1 Authorization: Basic Accept: application/vnd.urbanairship+json; version=3 Content-Type: application/json { "device_types": ["ios"], "audience": { "tag": "earlyBirds" }, "notification": { "alert": "{{#feed \"featured_product\"}}Hello, {{user}}, could I interest you in {{product_name}} today?{{/feed}}" }, "options": { "personalization": true }, "feed_references": { "feeds": [ { "name": "featured_product" } ], "defaults": { "featured_product": { "category": "featured" } } } } ``` ```http HTTP/1.1 202 Accepted Content-Type: application/vnd.urbanairship+json; version=3 Content-Length: 123 Data-Attribute: push_ids { "ok": true, "operation_id": "5e7852b0-6909-4e60-a73f-4d6b92d94c80", "push_ids": [ "bf28d158-fefe-475a-9c2a-ed4f69cc891e" ] } ``` *Example feed references object* ```json { "feed_references": { "feeds": [ { "name": "featured_product", "params": { "sub_category": "shoes" }, "on_error": "continue" } ], "defaults": { "featured_product": { "category": "featured" } } } } ``` --- # Named User > A Named User is a proprietary identifier that maps customer-chosen IDs, e.g., CRM data, to Channels. Schemas for managing Named Users, their associations, and updates. ## Named User object {#nameduserresponsebody} The response body for a Named User listing, including tags, channels and attributes associated with the Named User. [Jump to examples ↓](#nameduserresponsebody-examples) - **`attributes`** `object` <[Custom and predefined Attributes]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#attributes)> **REQUIRED** Attributes associated with a channel or Named User. This object contains predefined attributes that you enable and assign to the channel, or custom attributes that you create and assign. This object enumerates predefined attributes, but you can [create your own in the Airship dashboard](/docs/guides/audience/attributes/adding/). - **`channels`** `array` <[Channel listing object]({{< ref "/developer/rest-api/ua/schemas/channels/" >}}#channellistingobject)> **REQUIRED** Listing of channels associated with the Named User. - **`created`** `string` **REQUIRED** The creation [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format). Format: `date-time` - **`last_modified`** `string` **REQUIRED** The last modified [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format). Format: `date-time` - **`named_user_id`** `string` **REQUIRED** A customer-chosen ID that represents a user, e.g., CRM ID. This ID cannot have leading or trailing whitespace. Example: `john_doe` - **`subscription_lists`** `array` <[Subscription List item object]({{< ref "/developer/rest-api/ua/schemas/subscription-lists/" >}}#namedusersubscriptionlistitem)> **REQUIRED** A list of subscription list items associated with the Named User. - **`tags`** `object` <[Tag Group object]({{< ref "/developer/rest-api/ua/schemas/tags/" >}}#taggroupobject)> **REQUIRED** One or more tag group objects associated with the Named User. See [Named User Tags](/docs/developer/rest-api/ua/operations/tags/#modifynamedusertags). Tags belong to Tag Groups. Tag Groups appear within the `tags` object for a Named User or the `tag_groups` object for a channel. See also [Device Properties](/docs/reference/data-collection/device-properties/) ``ua_`` is a reserved prefix for Airship-specific tag groups. A Tag Group has two parts: a "name" string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters. - **`user_attributes`** `object` **REQUIRED** User attributes consist of three values that are copied from the last channel associated with the Named User. **OBJECT PROPERTIES** - **`ua_country`** `string` An ISO 3166 two-character country code. Example: "US". - **`ua_language`** `string` An ISO 639-1 two-character language code. Example: "en". - **`ua_local_tz`** `string` Time zone as a string. Example: "America/Los_Angeles" **Used in:** - [Named User listing or lookup]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#getnameduser) **Examples** *Example Named User* ```json { "named_user": { "named_user_id": "user-id-1234", "created" : "2020-04-08T20:41:06", "last_modified" : "2020-05-01T18:00:27", "tags": { "loyalty program": [ "silver-member", "ten-plus-years", "valued-customer" ], "crm id": [ "abc-123-def-456" ] }, "subscription_lists": [ { "list_ids": ["example_listId-1", "example_listId-5"], "scope": "web" }, { "list_ids": ["example_listId-2", "example_listId-3"], "scope": "app" }, { "list_ids": ["example_listId-2"], "scope": "web" }, { "list_ids": ["example_listId-3"], "scope": "email" }, { "list_ids": ["example_listId-4"], "scope": "sms" } ], "attributes": { "item_purchased": "Fur removal tool", "cats_name": "Sammy", "pets_age": 12 }, "user_attributes": { "ua_country": "US", "ua_language": "en", "ua_tz": "America/Los_Angeles" }, "channels": [ { "channel_id": "dceafd02-b852-4305-83df-98b65fa40dd4", "device_type": "ios", "installed": true, "opt_in": true, "push_address": "FFFF", "created": "2020-04-08T20:41:06", "last_registration": "2020-05-01T18:00:27", "tags": [ "meow" ] } ] } } ``` --- ## Named User update payload {#nameduserupdate} At least one of `associate`, `disassociate`, `tags`, or `attributes` must be provided. If a channel is provided in both `associate` and `disassociate` sections, a 400 will be returned. - **`associate`** `array` Associate a list of channels or email addresses with the Named User. If the `channel_id` or `email_address` is already associated with the Named User, this operation will do nothing. **Any of:** - **`channel_id`** `string` **REQUIRED** Format: `uuid` Example: `9c36e8c7-5a73-47c0-9716-99fd3d4197d5` - **`device_type`** `string` The device type of the channel. If the channel is not yet registered in Airship and `device_type` is not provided a 400 will be returned. Possible values: `ios`, `android`, `amazon`, `web`, `email`, `sms`, `open` - **`email_address`** `string` **REQUIRED** This email channel must already be registered in Airship or a 400 will be returned Format: `email` Example: `user@example.com` - **`attributes`** `array` <[Attribute assignment]({{< ref "/developer/rest-api/ua/schemas/attributes/" >}}#attributesobject)> Set or remove attributes on a Named User. A single request body may contain `set` or `remove` operations, or both. If both `set` and `remove` fields are present and the intersection of the attributes in these fields is not empty, then a 400 will be returned. If at least one of the attributes included in the request is valid, i.e., at least one attribute exists, Airship returns a 200 with a warning containing a list of attributes that failed to update. - **`disassociate`** `array` Disassociate a channel or an email address from the Named User. **Any of:** - **`channel_id`** `string` **REQUIRED** Format: `uuid` Example: `9c36e8c7-5a73-47c0-9716-99fd3d4197d5` - **`device_type`** `string` The device type of the channel. If the channel is not yet registered in Airship and `device_type` is not provided a 400 will be returned. Possible values: `ios`, `android`, `amazon`, `web`, `email`, `sms`, `open` - **`email_address`** `string` **REQUIRED** This email channel must already be registered in Airship or a 400 will be returned Format: `email` Example: `user@example.com` - **`tags`** `object` Add, remove, or set tags on a Named User. A single request body may contain add and/or remove objects or a single set field. At least one of the add, remove, or set objects must be present in a request. A tag must be < 128 characters. A request with one or more tags longer than 128 characters will return a 400 response. If at least one of the tags included in the request is valid, i.e., at least one tags exists, Airship returns a 200 with a warning containing a list of tags that failed to update. **OBJECT PROPERTIES** - **`add`** `object` <[Tag Group object]({{< ref "/developer/rest-api/ua/schemas/tags/" >}}#taggroupobject)> Add the list of tags to the Named User, but do not remove any. If the tags are already present, they are not modified. Tags belong to Tag Groups. Tag Groups appear within the `tags` object for a Named User or the `tag_groups` object for a channel. See also [Device Properties](/docs/reference/data-collection/device-properties/) ``ua_`` is a reserved prefix for Airship-specific tag groups. A Tag Group has two parts: a "name" string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters. - **`remove`** `object` <[Tag Group object]({{< ref "/developer/rest-api/ua/schemas/tags/" >}}#taggroupobject)> Remove the list of tags from the Named User, but do not remove any others. If the tags are not currently present, nothing happens. Tags belong to Tag Groups. Tag Groups appear within the `tags` object for a Named User or the `tag_groups` object for a channel. See also [Device Properties](/docs/reference/data-collection/device-properties/) ``ua_`` is a reserved prefix for Airship-specific tag groups. A Tag Group has two parts: a "name" string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters. - **`set`** `object` <[Tag Group object]({{< ref "/developer/rest-api/ua/schemas/tags/" >}}#taggroupobject)> Set these tags for the Named User; any tags previously associated that are not in this current list are removed. Tags belong to Tag Groups. Tag Groups appear within the `tags` object for a Named User or the `tag_groups` object for a channel. See also [Device Properties](/docs/reference/data-collection/device-properties/) ``ua_`` is a reserved prefix for Airship-specific tag groups. A Tag Group has two parts: a "name" string of 1-128 characters, and an array of tags, containing 0-100 tags. Each tag in the array is also a string consisting of 1-128 characters. **Used in:** - [Named User update]({{< ref "/developer/rest-api/ua/operations/named-users/" >}}#updatenameduser) --- # OAuth > Schemas for OAuth token requests, including scopes, assertion JWTs, and subject identifiers. ## Assertion JWT {#assertionjwt} A JSON Web Token (JWT) used for authorization in [OAuth token requests](/docs/developer/rest-api/ua/operations/oauth/#requestoauthtoken). The JWT must be signed with the private key corresponding to the `client_id` in the `kid` header using the ES384 algorithm. **All of:** - **Headers** `object` Assertion JWT headers - **`alg`** `string` **REQUIRED** The signing algorithm. Possible values: `ES384` - **`kid`** `string` **REQUIRED** The key used to sign the JWT, the `client_id`. - **Claims** `object` Assertion JWT claims - **`aud`** `string` **REQUIRED** The valid request endpoint. Example: `https://oauth2.asnapius.com/token` - **`exp`** `integer` **REQUIRED** The `assertion`'s expiration timestamp in seconds since epoch, after which it is not valid. The expiry must not be more than 10 minutes in the future. This is for the `assertion`, not for the token that will be returned. Example: `1681862754` - **`iat`** `integer` **REQUIRED** The issue timestamp in seconds since epoch. Example: `168186250` - **`ipaddr`** `string` A space-delimited list of CIDR representations of valid IP addresses to which the issued token is restricted. - **`iss`** `string` **REQUIRED** The issuer, the `client_id`. - **`nonce`** `string` **REQUIRED** A unique string that must not have been used recently with this `client_id`. We will store this for a minimum of 2 hours. If you are relying on the nonce to defend against replay attacks, it is recommended to also enforce a narrow *ipaddr* range in order to prevent requests that utilize the returned access token from being replayed by an outside client. Min length: 1, Max length: 50 - **`scope`** `string` <[OAuth Scope]({{< ref "/developer/rest-api/ua/schemas/oauth/" >}}#oauthscope)> A space-delimited list of scopes to which the returned claim should be restricted. If not provided, the full list of scopes the `client_id` is granted will be in the returned claim. The value of the scope parameter is a list of space-delimited, case-sensitive strings. If multiple scopes are specified, their order does not matter. Each string adds an additional access range to the requested scope. For more information about scope values, see [OAuth token scopes](/docs/developer/rest-api/ua/api-auth-reference/#oauth-token-scopes) in the *Airship API Authorization Reference* documentation. * `att`: Attachments * `chn`: Channels * `tpl`: Content * `evt`: Events * `lst`: Lists * `nu`: Named Users * `pln`: Pipelines * `psh`: Push * `rpt`: Reports * `sch`: Schedules Possible values: `att`, `chn`, `tpl`, `evt`, `lst`, `nu`, `pln`, `psh`, `rpt`, `sch` - **`sub`** `object` <[Subject]({{< ref "/developer/rest-api/ua/schemas/oauth/" >}}#subject)> **REQUIRED** A space-delimited set of identifiers for which subjects a token is allowed. An `app` subject is required. Example: `app:`. A space-delimited set of identifiers for which subjects a token is allowed. Example: `app:` * `app`: May operate on the given app **Used in:** - [Request token]({{< ref "/developer/rest-api/ua/operations/oauth/" >}}#requestoauthtoken) --- ## OAuth Scope {#oauthscope} The value of the scope parameter is a list of space-delimited, case-sensitive strings. If multiple scopes are specified, their order does not matter. Each string adds an additional access range to the requested scope. For more information about scope values, see [OAuth token scopes](/docs/developer/rest-api/ua/api-auth-reference/#oauth-token-scopes) in the *Airship API Authorization Reference* documentation. * `att`: Attachments * `chn`: Channels * `tpl`: Content * `evt`: Events * `lst`: Lists * `nu`: Named Users * `pln`: Pipelines * `psh`: Push * `rpt`: Reports * `sch`: Schedules `string` Allowed values: `att`, `chn`, `tpl`, `evt`, `lst`, `nu`, `pln`, `psh`, `rpt`, `sch` **Used in:** - [Request token]({{< ref "/developer/rest-api/ua/operations/oauth/" >}}#requestoauthtoken) --- ## Subject {#subject} A space-delimited set of identifiers for which subjects a token is allowed. Example: `app:` * `app`: May operate on the given app **Used in:** - [Request token]({{< ref "/developer/rest-api/ua/operations/oauth/" >}}#requestoauthtoken) --- # Personalization template objects > Personalization template objects, including pushes to templates and template listing. ## Push template payload {#pushtemplatepayload} A push template payload defines a push by overriding the variables defined in a specific template object. Specifically, a push template object specifies push audience and device types, along with substitutions for the variables defined in a template. [Jump to examples ↓](#pushtemplatepayload-examples) - **`audience`** `object` <[Audience selector (max 1000)]({{< ref "/developer/rest-api/ua/schemas/audience-selection/" >}}#audienceselector1000)> **REQUIRED** The audience for the template. An audience selector forms the expression that determines the set of channels to target. - **`campaigns`** `object` <[Campaigns object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#campaignsobject)> An object specifying custom campaign categories related to the notification. - **`device_types`** `array[string]` **REQUIRED** An array containing one or more strings identifying targeted platforms. Min items: 1 Possible values: `android`, `amazon`, `ios`, `web`, `sms`, `mms`, `email`, `open::open_platform_name` - **`merge_data`** `object` **REQUIRED** A template selector describing the template ID and variable substitutions to use with it. **OBJECT PROPERTIES** - **`substitutions`** `object` An object containing overrides for your template's variables. The key-value pairs in this object are the value of the `key` items defined in your template, and the values you want to substitute for the `default_value` of those keys. - **`template_id`** `string` **REQUIRED** Specifies the template to override; corresponds to the `id` in `/templates` responses. Format: `uuid` Example: `ef34a8d9-0ad7-491c-86b0-aea74da15161` **Used in:** - [Push to template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#pushtotemplate) - [Validate a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#validatetemplate) **Examples** *Push template payload example* ```json { "audience": { "tag": [ "yanny", "laurel" ] }, "device_types": [ "email", "ios", "android", "web" ], "merge_data": { "template_id": "8cce6cc8-7d78-43c7-80b5-81ac24c07672", "substitutions": { "FIRST_NAME": "Bob", "LAST_NAME": "Takahashi", "TITLE": null } }, "campaigns": { "categories": [ "winter sale", "west coast" ] } } ``` --- ## Template object {#templateobject} A template object is a skeleton for a push. This is the object used for template creation, and returned by the template listing and lookup endpoints. [Jump to examples ↓](#templateobject-examples) - **`created_at`** `string` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when this template was created. Format: `date-time` Read only: true - **`description`** `string` The description for the template. - **`id`** `string` The unique ID assigned to this template. Used to retrieve or use the template in other endpoints. Format: `uuid` Read only: true - **`last_used`** `string` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when this template's definition was last used. This attribute cannot template-based specified when the template is created and will only be present when template objects are provided by the template retrieval and template listing endpoints. Format: `date-time` Read only: true - **`modified_at`** `string` The [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format) when this template was last modified. Format: `date-time` Read only: true - **`name`** `string` **REQUIRED** The name of the template. - **`push`** `object` <[Template push object]({{< ref "/developer/rest-api/ua/schemas/personalization-template-objects/" >}}#templatepushobject)> A partial push object describing everything about a push notification, except for the `audience` and `device_types` keys (which are defined in the [Push template payload](/docs/developer/rest-api/ua/schemas/personalization-template-objects/#pushtemplatepayload)) and the `message` key (which is incompatible with templates). - **`variables`** `array` <[Template variables]({{< ref "/developer/rest-api/ua/schemas/personalization-template-objects/" >}}#templatevariableobject)> **REQUIRED** An array of variable specifications. Variables can be customized when pushing based on the template. **Used in:** - [Create template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#createtemplate) - [List templates]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#gettemplates) - [Look up a template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#gettemplate) **Examples** *Basic template object* ```json { "name": "