Skip to content

Object tags API (beta)

Object tags store structured data about a user in one tag. A tag of the Object type holds one object with named fields, such as the last order with its amount and status. A tag of the ObjectList type holds an array of such objects, such as all orders. A field can itself be an object or a list of objects, such as the address of a profile. You define the fields once, write and read values through the tag API, build segments by field values, and insert the values into messages with Liquid.

How object tags work

Anchor link to

An object tag has a schema and a value. The schema is the tag name and a list of fields, each with its own type. The value is stored in the fields, separately for each user.

  • Field. Each field is a tag named <object>.<field>, for example order.amount. You segment by fields, and you can write a field of an Object tag by this name.
  • Object value. One object per user, for example "order": {"amount": 120, "status": "paid"}.
  • ObjectList value. An array of objects with the same fields, for example "orders": [{"amount": 120, "status": "paid"}, {"amount": 50}].
  • Nested object. A field of the OBJECT type with fields of its own, for example profile.address with the field profile.address.city.
  • Nested list. A field of the OBJECT_LIST type, an array of objects inside an object tag, for example profile.visits. See Nested objects and lists.

In the API, the tag and field types are OBJECT and OBJECT_LIST. In the Control Panel, they are Object and List of objects. On this page, a list of objects means an ObjectList tag or a nested list.

Object tags are always User-specific, which means the value belongs to the user, not to a single device, and is copied to all of the user’s devices. See Tags API for regular tags.

Nested objects and lists

Anchor link to

A field of an object tag can hold its own fields instead of a single value. A nested object, a field of the OBJECT type, holds one object. A nested list, a field of the OBJECT_LIST type, holds a list of objects. An element of a list can contain nested objects and lists too. Each field keeps its full dotted name, such as profile.address.city, and you segment by these names.

For example, a profile tag of the OBJECT type and an orders tag of the OBJECT_LIST type can have this structure:

profile OBJECT
├── address OBJECT
│ ├── city STRING
│ └── geo OBJECT
│ └── lat STRING
└── visits OBJECT_LIST
└── code STRING
orders OBJECT_LIST
├── sku STRING
├── meta OBJECT
│ └── color STRING
└── lines OBJECT_LIST
└── qty INTEGER

Searchable and stored-only fields

Anchor link to

What you can do with a field depends on how many lists of objects are above it:

  • No list above the field. You can segment by a field such as profile.address.city, write it on its own by its full name, and use it in messages.
  • One list above the field. You can segment by a field such as profile.visits.code or orders.meta.color and use it in messages. Write it only as part of the whole list.
  • Two lists above the field. A field such as orders.lines.qty is stored only. Use it in messages, but not in segments.

Pushwoosh applies these limits to object tags, nested objects and lists included:

LimitValueWhen it’s exceeded
Nesting depth3 levels of objects and lists. The tag itself is the first level, so profile.address.geo is the deepest allowed objectThe schema method returns HTTP 400, see Errors
Fields in one objectFrom 1 to 20, for the tag and for each nested object or nested listThe schema method returns HTTP 400, see Errors
Fields with values in one object tag50, nested fields included. Fields of the OBJECT and OBJECT_LIST types don’t countThe schema method returns HTTP 400, see Errors
Full field name64 characters, such as profile.address.cityThe schema method returns HTTP 400, see Errors
Elements in one list of objects100, for the tag and for each nested listThe whole written value is rejected
Size of one written value64 KB of JSONThe whole written value is rejected

A rejected value is handled the same way as a value with a wrong field type, see Writing replaces the whole value.

Schema rules

Anchor link to

Pushwoosh checks these rules when you create an object tag or add a field:

  • Object and field names contain only Latin letters, digits, and _.
  • The tag and each nested object or nested list have from 1 to 20 fields. The other limits apply too. Field names are case-insensitive, so Amount and amount are the same field.
  • A field has one of these types: INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT, OBJECT_LIST. A field of the OBJECT or OBJECT_LIST type needs its own fields. Timezone fields aren’t supported.
  • A field can’t take a name that another tag already has. If a tag order.note exists, adding the field note to order fails with tag order.note already exists.
  • An object can’t lose its last field. Delete the object instead.
  • A field or an object tag that is in use can’t be deleted. A nested object or nested list counts as in use when anything inside it is used. The error lists where it is used, for example field is in use: segment Big buyers, in-app Spring sale. Segments, in-apps, running Customer Journey campaigns, presets, email templates, and other items that reference the tag count as usages.

Manage object tags in the Control Panel

Anchor link to

Create an object tag without nested objects and lists in the Control Panel:

  1. On the Tags page of your Control Panel, click Create tag.
  2. Enter the Tag name.
  3. In Value type, choose Object or List of objects.
  4. Under Fields, enter the name of the first field.
  5. Choose the type of the field.
  6. To add another field, click Add field.
  7. Click Create.

On the tag page, add a field or click Remove next to a field to delete it. The Control Panel can’t create a nested object or nested list or change its fields. It shows a nested object or nested list created through the API as one field of the Object or List of objects type. Deleting that field deletes it with everything inside it.

Manage the schema

Anchor link to

Create and change object tags with the REST methods below. Use /json/1.3/addTag only for regular tags, because it can’t define fields.

https://rpc-api.svc-nue.pushwoosh.com

Authentication

Anchor link to

Every request must include an Authorization header with your Server API token. A Device API token gets HTTP 403 a device API token cannot call this method, use an account API token.

Authorization: Api YOUR_API_TOKEN

These methods manage the schema of object tags and read the values of their fields:

MethodPathDescription
POST/api/tagsCreate an object tag with its fields
GET/api/tags/{name}Get an object tag with its fields
GET/api/tagsList tags. An object tag comes with all its fields, nested ones included, and the fields aren’t listed as separate tags
POST/api/tags/{name}/fieldsAdd a field to an object tag, a nested object, or a nested list
DELETE/api/tags/{name}/fields/{field}Delete a field, a nested object, or a nested list
DELETE/api/tags/{name}Delete an object tag with all its fields
GET/api/tags:valuesList the stored values of a field, see Stored values of a field

POST /api/tags returns the object tag, and both field methods return the object named in {name} after the change, wrapped in {"tag": {...}}. DELETE /api/tags/{name} returns {}.

If object tags aren’t enabled for your account, POST /api/tags with an object type and both field methods fail with HTTP 403 object tags are not enabled for the account. GET /api/tags/{name} and DELETE /api/tags/{name} return HTTP 404 tag not found, and GET /api/tags doesn’t list object tags. Without object tags enabled you can’t create one, so there is nothing to write values to.

Create an object tag

Anchor link to

POST /api/tags

Request body
Anchor link to
NameTypeDescription
name*stringName of the object tag.
type*stringOBJECT for one object or OBJECT_LIST for a list of objects.
fields*arrayFields of the object, from 1 to 20.
fields[].name*stringField name. The field becomes the tag <name>.<fields[].name>.
fields[].type*stringField type: INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT, or OBJECT_LIST.
fields[].fieldsarrayFields of a nested object or nested list, from 1 to 20, in the same format. Required for the OBJECT and OBJECT_LIST types and ignored for other types.
Example
{
"name": "orders",
"type": "OBJECT_LIST",
"fields": [
{ "name": "amount", "type": "INTEGER" },
{ "name": "status", "type": "STRING" }
]
}
Response
{
"tag": {
"name": "orders",
"type": "OBJECT_LIST",
"system": false,
"user_specific": true,
"has_right_ace_modify": true,
"fields": [
{ "name": "amount", "type": "INTEGER", "fields": [] },
{ "name": "status", "type": "STRING", "fields": [] }
]
}
}

The tag is created as User-specific regardless of the user_specific value. GET /api/tags/{name} returns the same object without the tag wrapper. Fields are sorted by name, and a field without nested fields comes with an empty fields array.

To create nested objects and lists, give a field the OBJECT or OBJECT_LIST type and its own fields. One request creates the whole structure:

Example: the profile tag from Nested objects and lists
{
"name": "profile",
"type": "OBJECT",
"fields": [
{
"name": "address",
"type": "OBJECT",
"fields": [
{ "name": "city", "type": "STRING" },
{ "name": "geo", "type": "OBJECT", "fields": [{ "name": "lat", "type": "STRING" }] }
]
},
{
"name": "visits",
"type": "OBJECT_LIST",
"fields": [{ "name": "code", "type": "STRING" }]
}
]
}

Nested fields come back with names relative to their object, such as city inside address. GET /api/tags/{name} takes only the name of the tag itself. A nested name such as profile.address returns HTTP 404 tag not found.

Add a field

Anchor link to

POST /api/tags/{name}/fields

Example: POST /api/tags/orders/fields
{
"field": { "name": "note", "type": "STRING" }
}

To add a field to a nested object or nested list, put its full name in {name}, for example POST /api/tags/profile.address/fields or POST /api/tags/profile.visits/fields. The new field can be a nested object or nested list with its own fields:

Example: POST /api/tags/profile/fields
{
"field": {
"name": "company",
"type": "OBJECT",
"fields": [{ "name": "title", "type": "STRING" }]
}
}

You can write the new field right away as part of the whole tag value. Adding a field fails if the object already has 20 fields, if the field breaks another limit, or if a tag with the full field name exists, see Errors.

Delete a field

Anchor link to

DELETE /api/tags/{name}/fields/{field}

For example, DELETE /api/tags/orders/fields/note deletes the field orders.note. To delete a field of a nested object or nested list, put its full name in {name}: DELETE /api/tags/profile.address/fields/city.

Deleting a nested object or nested list deletes everything inside it: DELETE /api/tags/profile/fields/address deletes profile.address.city and profile.address.geo too. You can’t delete the last field of an object, or a field, a nested object, or a nested list that is in use, see Errors.

Errors come in the format {"code": <n>, "message": "...", "details": [...]}. When you create an object tag, a 400 message has the form validate: rpc error: code = InvalidArgument desc = <message>, where <message> is the text in the table. In these messages, <object> is the full name of the object, such as profile.address.

HTTP statusMessageCause
400object tag and field names must contain only letters, digits and underscoresA name has another character.
400<object>: an object needs 1 to 20 fieldsOn create, the tag, a nested object, or a nested list has no fields or more than 20 fields.
400an object has at most 20 fieldsThe object you add a field to already has 20 fields.
400<object>.<field>: objects nest at most 3 levels deepAn OBJECT or OBJECT_LIST field would be the fourth level.
400an object tag holds at most 50 fields with values, nested ones includedThe object tag would have more than 50 fields with values.
400field <name> is given twiceTwo fields have the same name, ignoring case.
400<object>.<field>: object and field names together cannot be longer than 64 charactersThe full field name is too long.
400<object>.<field>: field type must be INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT or OBJECT_LISTUnsupported field type.
400an object needs at least one field; delete the object insteadYou tried to delete the last field of an object.
400field is in use: ..., tag is in use: ...The field, something inside the nested object or nested list, or the object tag is used in segments, in-apps, Customer Journey campaigns, or other items.
403object tags are not enabled for the accountObject tags aren’t enabled for the account.
403a device API token cannot call this method, use an account API tokenThe request uses a Device API token.
404tag not foundGET or DELETE /api/tags/{name}: no such tag, the name is a field, or object tags aren’t enabled.
404object tag not found, field not foundField methods: no such object tag, nested object, nested list, or field. {name} that is a field with a value also returns object tag not found.
409tag already existsA tag with the object tag name exists.
409tag <object>.<field> already existsA tag with the field’s full name exists.

Write values

Anchor link to

Write object tag values with /setTags and /bulkSetTags. These methods keep their own authentication: /setTags takes a Device API token in the Authorization: Token header, and /bulkSetTags takes the API access token in auth. Send an Object value as a JSON object and an ObjectList value as an array of objects:

Example: /json/1.3/setTags
{
"request": {
"application": "XXXXX-XXXXX",
"userId": "user_42",
"tags": {
"order": { "amount": 120, "status": "paid" },
"orders": [
{ "amount": 120, "status": "paid" },
{ "amount": 50 }
]
}
}
}

If you set the value by HWID, it is stored on the user of that device. POST /api/devices:set_tags on the base URL of the schema methods writes object tags by the same rules. Its response lists the fields of objects as flat names such as "profile.address.city".

A nested object takes a JSON object, and a nested list takes an array of objects:

Example: nested values in /json/1.3/setTags
"tags": {
"profile": {
"address": { "city": "Berlin", "geo": { "lat": "52.5" } },
"visits": [{ "code": "v1" }]
},
"orders": [
{ "sku": "A-1", "meta": { "color": "red" }, "lines": [{ "qty": 2 }, { "qty": 3 }] }
]
}

Each field takes a value in the format of its type:

Field typeExample value
INTEGER120
STRING"paid"
LIST["gift", "express"]
DATE"2026-10-02 22:11" (UTC), "2026-10-02", or a Unix timestamp in seconds
BOOLEANtrue or false
PRICE19.95
VERSION"1.0.0"

Writing replaces the whole value

Anchor link to

Each write replaces the stored value of the object tag:

  • A field missing from the new value is deleted. A field sent as null is deleted too.
  • null, [], or "" deletes the whole value.
  • {} deletes all fields of an Object tag.
  • A key that isn’t a field of the object is skipped.
  • If a field value at any depth doesn’t match the field type, the whole value of the tag is rejected and the stored value stays as it was. The same happens if the value breaks a limit: a list with more than 100 elements or more than 64 KB of JSON.

/setTags doesn’t report a rejected value in its response and returns HTTP 200. Check the result with /getTags or use /bulkSetTags, which reports a result for each tag.

Hidden fields

Anchor link to

A hidden field is a field that Pushwoosh marks as hidden for its own use. You can’t create or hide a field with the schema methods on this page. /getTags doesn’t return hidden fields, so a value you read and write back never contains them. What happens to them on a write depends on the type:

  • Object. A hidden field missing from the new value is kept, at any depth. A visible nested object missing from the new value is deleted with everything inside it, hidden fields included. Deleting the whole value deletes hidden fields too.
  • ObjectList. Writing the list replaces all its elements, and hidden fields of the old elements are lost. An element has no identifier, so a new element can’t be matched to an old one. The same applies to a nested list.

Write part of an Object

Anchor link to

Write a single field, a nested object, or a nested list of an Object tag by its full name instead of the whole tag value. increment and the other operations of /setTags work on fields:

"tags": {
"order.status": "shipped",
"order.amount": { "operation": "increment", "value": 5 }
}

The same works for a field of a nested object that has only objects above it, such as "profile.address.city": "Paris".

A nested object or nested list with only objects above it can be written on its own by its full name, such as profile.address or profile.visits. The value replaces only it, and the rest of profile stays as it was. The 100-element and 64 KB limits count from this value:

"tags": {
"profile.address": { "city": "Paris" },
"profile.visits": [{ "code": "v2" }]
}

Nothing inside a list of objects can be written on its own, because it isn’t clear which element to change. This covers a field of an ObjectList tag, such as orders.sku, and everything inside an element, such as orders.meta or profile.visits.code. /setTags skips such a value. Send the whole list instead.

Object tags aren’t created automatically

Anchor link to

A value with an object or an array of objects for a tag that doesn’t exist is skipped. Tag auto-creation doesn’t create object tags, so create the schema first with POST /api/tags.

bulkSetTags results

Anchor link to

With detailed=true, /bulkSetTags status returns one of these results for an object tag, in addition to ok, tag not found, and wrong value. expect :<type>:

ResultCause
object tags are stored on the user onlyThe object tag isn’t User-specific.
cannot load the fields of the objectPushwoosh couldn’t read the fields of the object tag.
wrong value. expect an object (a map) or, for a list of objects, an array of mapsThe value doesn’t fit the object tag, a field value at any depth doesn’t match its type, or the value breaks a limit.
a field of a list of objects cannot be set on its own, set the whole listThe value is set on something inside a list of objects, such as orders.sku or orders.meta.

Read values

Anchor link to

/getTags returns an Object value as a JSON object and an ObjectList value as an array of objects:

Response
{
"status_code": 200,
"status_message": "OK",
"response": {
"result": {
"order": { "amount": 120, "status": "paid" },
"orders": [
{ "amount": 120, "status": "paid" },
{ "amount": 50 }
]
}
}
}

Nested objects and lists come back at any depth in the same shape as you write them, for example "profile": {"address": {"city": "Berlin"}, "visits": [{"code": "v1"}]}.

Field values are returned the same way as regular tag values in /getTags: a Date as a Unix timestamp in seconds, a Price as a string such as "120.00", and a Boolean as 1 or 0.

Stored values of a field

Anchor link to

GET /api/tags:values on the base URL lists the distinct values a field holds, with the number of subscribers for each value. Pass the field’s full name in name, such as profile.address.city or orders.sku.

Query parameters
Anchor link to
NameTypeDescription
application*stringApplication code, XXXXX-XXXXX.
name*stringFull name of the field.
likestringReturn only values that contain this text, in the position set by like_op.
like_opstringSTARTS_WITH (default), ENDS_WITH, or CONTAINS.
order_bystringVALUE (default) or COUNT.
order_directionstringASC (default) or DESC.
limitintegerNumber of values to return. Defaults to 100.
offsetintegerNumber of values to skip.
pageintegerPage number, starting from 0. Used with per_page instead of limit and offset.
per_pageintegerNumber of values on a page.
Example
GET /api/tags:values?application=XXXXX-XXXXX&name=orders.sku&order_by=COUNT&order_direction=DESC
Response
{
"values": [
{ "value": "A-1", "count": 120 },
{ "value": "B-2", "count": 45 }
],
"total": 2,
"page": 0,
"per_page": 100
}

Integer and Price fields return no values, the same as regular tags of these types. An object tag, a nested object, or a nested list itself has no values of its own, so its name returns HTTP 404 tag not found.

Segment by fields

Anchor link to

Set segment conditions on fields, not on the object tag itself. In the segmentation language, a field is a tag with a dotted name, and it takes the operators of its own type:

AT("XXXXX-XXXXX", "order.amount", gte, 100)

A field of a nested object or nested list takes its full name, such as profile.address.city, profile.visits.code, or orders.meta.color. A condition on the object tag itself, a nested object, or a nested list, such as profile.address, fails with object tag has no value of its own, use one of its fields.

A field with two lists of objects above it, such as orders.lines.qty, is stored only. The segment with such a condition is saved, but counting it or sending to it fails with a field inside a list nested in a list is stored only and cannot be searched.

Conditions on an ObjectList

Anchor link to

A condition on a field of an ObjectList tag matches a user when at least one element of the list fits the condition. Conditions on fields of the same list joined with AND must match the same element:

AT("XXXXX-XXXXX", "orders.amount", gte, 100) * AT("XXXXX-XXXXX", "orders.status", eq, "paid")

This segment holds users with at least one order that is both 100 or more and paid. A user with one large unpaid order and one small paid order doesn’t match. The same element is checked for the fields of an object inside it: orders.sku equal to A-1 AND orders.meta.color equal to red match a user with one order that has both. Conditions joined with OR don’t have to match the same element. Conditions on two different lists are checked on each list separately.

Some operators work differently on a field of an ObjectList tag:

  • notset. No element of the list has a value in this field. A user without the list matches too.
  • noteq. At least one element has a value in this field, and that value differs from the given one. Elements without the field don’t count. A user with orders in statuses paid and new matches noteq "paid".
  • notin on a List field. No element contains any of the given values.
  • notin on a field of another type. At least one element has a value in this field that isn’t among the given values.

notset and notin on a List field aren’t tied to the same element as the other conditions joined with AND. These rules apply to nested lists, such as profile.visits, too.

Use values in messages

Anchor link to

Insert fields of object tags into push notifications, emails, SMS, and messenger messages such as WhatsApp with Liquid templates. Liquid works only if content templates are enabled for your account. Write a field by its full name at any depth:

Your city is {{ profile.address.city }}.

Take an element of a list of objects by its index, starting from 0:

Your first order is {{ orders[0].sku }}, quantity {{ orders[0].lines[0].qty }}.

An index past the end of the list, or a list the user doesn’t have, renders as an empty string. Check the element first or set a fallback with default:

{% if orders[0] %}Your first order is {{ orders[0].sku }}.{% endif %}
Your first order is {{ orders[0].sku | default: "on its way" }}.

Loop over a list of objects, including a list inside an element:

{% for o in orders %}{{ o.meta.color }}{% for l in o.lines %}{{ l.qty }}{% endfor %}{% endfor %}

Stored-only fields, such as orders.lines.qty, work in templates the same way as other fields.

Export segments with object tags

Anchor link to

/exportSegment exports the fields of object tags:

  • CSV. Each field with a value is a separate column named by its full name, such as order.amount or profile.address.city. Object tags, nested objects, and nested lists themselves get no column. A field inside a list of objects, at any depth, holds the distinct values from all elements as a JSON array, the same way as a List tag: ["A-1","B-2"]. The array is sorted and doesn’t show which element a value came from, so it doesn’t keep the order of elements either. To get the elements whole, export in json or json_each_line.
  • json and json_each_line. Object tags come nested, in the same shape as /getTags returns them. An Object tag is one entry in tags with its fields under object.fields, and a nested object inside it carries its own fields under object.fields too, at every level. An ObjectList tag is one entry with its elements in object_list.items, and so is a nested list. Fields have short names, are sorted by name, and carry their value under a key named after the type: integer, string, list, date, boolean, price, or version:
{
"name": "profile",
"object": {
"fields": [
{ "name": "address", "object": { "fields": [{ "name": "city", "string": "Berlin" }] } },
{ "name": "visits", "object_list": { "items": [{ "fields": [{ "name": "code", "string": "v1" }] }] } }
]
}
}

An ObjectList tag looks like this. Integer values come as strings:

{
"name": "orders",
"object_list": {
"items": [
{ "fields": [{ "name": "amount", "integer": "120" }, { "name": "status", "string": "paid" }] },
{ "fields": [{ "name": "amount", "integer": "50" }] }
]
}
}

An element with a nested object and a nested list looks like this:

{
"fields": [
{ "name": "meta", "object": { "fields": [{ "name": "color", "string": "red" }] } },
{ "name": "lines", "object_list": { "items": [{ "fields": [{ "name": "qty", "integer": "2" }] }] } }
]
}

If tagsList names an object tag, all of its fields are exported, nested ones included.