# 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": "<template name>",
   "description": "<template description>",
   "variables": ["<variable specifications>"],
   "push": "<push-object>",
   "id": "<template-id>",
   "created_at" : "timestamp",
   "modified_at" : "timestamp",
   "last_used" : "timestamp"
}

```

---

## Template push object {#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).

[Jump to examples ↓](#templatepushobject-examples)

- **`campaigns`** `object` <[Campaigns object]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#campaignsobject)>

  An object specifying custom campaign categories related to the notification.

- **`in_app`** `object` <[In-app message]({{< ref "/developer/rest-api/ua/schemas/push/" >}}#inappobject)>

  A JSON object describing an in-app message payload.

- **`no_throttle`** `boolean`

  If true, the push will ignore global throttling rates that have been configured for the application, resulting in delivery as quickly as possible.

  Default: `false`

- **`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`

  A JSON dictionary for specifying non-payload options related to the delivery of the push.

  **OBJECT PROPERTIES**

  - **`expiry`** `object`

    Delivery expiration, as either absolute ISO UTC timestamp, or number of seconds from now.

    **One of:**

    - `integer`

      Number of seconds from now. When the delivery platform supports it, a value of zero (0) indicates that the message should be delivered immediately and never stored for later attempts.

    - `string`

      A [date-time](/docs/developer/rest-api/ua/introduction/#date-time-format).



**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)
- [Update template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#updatetemplate)

**Examples**

*Example*

```json
{
    "audience" : {
        "OR" : [
            { "tag" : ["sports", "entertainment"]},
            { "device_token" : "871922F4F7C6DF9D51AC7ABAE9AA5FCD7188D7BFA19A2FA99E1D2EC5F2D76506" },
            { "apid" : "5673fb25-0e18-f665-6ed3-f32de4f9ddc6" }
        ]
    },
    "device_types" : [ "ios" ],
    "merge_data": {
        "template_id": "ef34a8d9-0ad7-491c-86b0-aea74da15161",
        "substitutions": {
            "FIRST_NAME": "Bob"
        }
    }
}

```

---

## Template variables {#templatevariableobject}

A template variable object describes the pieces of your template to override when creating template-based pushes. These are the fields you want to customize when you send a push based on the template.

[Jump to examples ↓](#templatevariableobject-examples)

- **`default_value`** `string`

  A default value for the variable. If the key for this variable is not specified in a Template Selector (`substitutions`) when issuing push notifications based on this template, the push will use this value.

- **`description`** `string`

  A description of the variable.

- **`key`** `string` **REQUIRED**

  The key used to reference the variable inside the template push. (32 chars, starting and ending with alphanumeric characters, and consisting of alphanumeric characters and underscores).

  Min length: 1, Max length: 32

- **`name`** `string`

  A friendly name for the variable.


**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)
- [Update template]({{< ref "/developer/rest-api/ua/operations/personalization/" >}}#updatetemplate)

**Examples**

*Template variable example*

```json
{
   "key" : "<key>",
   "name" : "<variable name>",
   "description" : "<variable description>",
   "default_value" : "<fallback value>"
}

```

---