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 toAn 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 exampleorder.amount. You segment by fields, and you can write a field of anObjecttag by this name. Objectvalue. One object per user, for example"order": {"amount": 120, "status": "paid"}.ObjectListvalue. An array of objects with the same fields, for example"orders": [{"amount": 120, "status": "paid"}, {"amount": 50}].- Nested object. A field of the
OBJECTtype with fields of its own, for exampleprofile.addresswith the fieldprofile.address.city. - Nested list. A field of the
OBJECT_LISTtype, an array of objects inside an object tag, for exampleprofile.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 toA 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 INTEGERSearchable and stored-only fields
Anchor link toWhat 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.codeororders.meta.colorand use it in messages. Write it only as part of the whole list. - Two lists above the field. A field such as
orders.lines.qtyis stored only. Use it in messages, but not in segments.
Limits
Anchor link toPushwoosh applies these limits to object tags, nested objects and lists included:
| Limit | Value | When it’s exceeded |
|---|---|---|
| Nesting depth | 3 levels of objects and lists. The tag itself is the first level, so profile.address.geo is the deepest allowed object | The schema method returns HTTP 400, see Errors |
| Fields in one object | From 1 to 20, for the tag and for each nested object or nested list | The schema method returns HTTP 400, see Errors |
| Fields with values in one object tag | 50, nested fields included. Fields of the OBJECT and OBJECT_LIST types don’t count | The schema method returns HTTP 400, see Errors |
| Full field name | 64 characters, such as profile.address.city | The schema method returns HTTP 400, see Errors |
| Elements in one list of objects | 100, for the tag and for each nested list | The whole written value is rejected |
| Size of one written value | 64 KB of JSON | The 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 toPushwoosh 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
Amountandamountare the same field. - A field has one of these types:
INTEGER,STRING,LIST,DATE,BOOLEAN,PRICE,VERSION,OBJECT,OBJECT_LIST. A field of theOBJECTorOBJECT_LISTtype needs its ownfields. Timezone fields aren’t supported. - A field can’t take a name that another tag already has. If a tag
order.noteexists, adding the fieldnotetoorderfails withtag 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 toCreate an object tag without nested objects and lists in the Control Panel:
- On the Tags page of your Control Panel, click Create tag.
- Enter the Tag name.
- In Value type, choose Object or List of objects.
- Under Fields, enter the name of the first field.
- Choose the type of the field.
- To add another field, click Add field.
- 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 toCreate and change object tags with the REST methods below. Use /json/1.3/addTag only for regular tags, because it can’t define fields.
Base URL
Anchor link tohttps://rpc-api.svc-nue.pushwoosh.comAuthentication
Anchor link toEvery 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_TOKENEndpoints
Anchor link toThese methods manage the schema of object tags and read the values of their fields:
| Method | Path | Description |
|---|---|---|
POST | /api/tags | Create an object tag with its fields |
GET | /api/tags/{name} | Get an object tag with its fields |
GET | /api/tags | List 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}/fields | Add 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:values | List 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 toPOST /api/tags
Request body
Anchor link to| Name | Type | Description |
|---|---|---|
| name* | string | Name of the object tag. |
| type* | string | OBJECT for one object or OBJECT_LIST for a list of objects. |
| fields* | array | Fields of the object, from 1 to 20. |
| fields[].name* | string | Field name. The field becomes the tag <name>.<fields[].name>. |
| fields[].type* | string | Field type: INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT, or OBJECT_LIST. |
| fields[].fields | array | Fields 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. |
{ "name": "orders", "type": "OBJECT_LIST", "fields": [ { "name": "amount", "type": "INTEGER" }, { "name": "status", "type": "STRING" } ]}{ "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:
{ "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 toPOST /api/tags/{name}/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:
{ "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 toDELETE /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
Anchor link toErrors 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 status | Message | Cause |
|---|---|---|
| 400 | object tag and field names must contain only letters, digits and underscores | A name has another character. |
| 400 | <object>: an object needs 1 to 20 fields | On create, the tag, a nested object, or a nested list has no fields or more than 20 fields. |
| 400 | an object has at most 20 fields | The object you add a field to already has 20 fields. |
| 400 | <object>.<field>: objects nest at most 3 levels deep | An OBJECT or OBJECT_LIST field would be the fourth level. |
| 400 | an object tag holds at most 50 fields with values, nested ones included | The object tag would have more than 50 fields with values. |
| 400 | field <name> is given twice | Two fields have the same name, ignoring case. |
| 400 | <object>.<field>: object and field names together cannot be longer than 64 characters | The full field name is too long. |
| 400 | <object>.<field>: field type must be INTEGER, STRING, LIST, DATE, BOOLEAN, PRICE, VERSION, OBJECT or OBJECT_LIST | Unsupported field type. |
| 400 | an object needs at least one field; delete the object instead | You tried to delete the last field of an object. |
| 400 | field 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. |
| 403 | object tags are not enabled for the account | Object tags aren’t enabled for the account. |
| 403 | a device API token cannot call this method, use an account API token | The request uses a Device API token. |
| 404 | tag not found | GET or DELETE /api/tags/{name}: no such tag, the name is a field, or object tags aren’t enabled. |
| 404 | object tag not found, field not found | Field 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. |
| 409 | tag already exists | A tag with the object tag name exists. |
| 409 | tag <object>.<field> already exists | A tag with the field’s full name exists. |
Write values
Anchor link toWrite 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:
{ "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:
"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 type | Example value |
|---|---|
INTEGER | 120 |
STRING | "paid" |
LIST | ["gift", "express"] |
DATE | "2026-10-02 22:11" (UTC), "2026-10-02", or a Unix timestamp in seconds |
BOOLEAN | true or false |
PRICE | 19.95 |
VERSION | "1.0.0" |
Writing replaces the whole value
Anchor link toEach write replaces the stored value of the object tag:
- A field missing from the new value is deleted. A field sent as
nullis deleted too. null,[], or""deletes the whole value.{}deletes all fields of anObjecttag.- 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 toA 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 toWrite 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 toA 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 toWith 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>:
| Result | Cause |
|---|---|
object tags are stored on the user only | The object tag isn’t User-specific. |
cannot load the fields of the object | Pushwoosh 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 maps | The 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 list | The 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:
{ "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 toGET /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| Name | Type | Description |
|---|---|---|
| application* | string | Application code, XXXXX-XXXXX. |
| name* | string | Full name of the field. |
| like | string | Return only values that contain this text, in the position set by like_op. |
| like_op | string | STARTS_WITH (default), ENDS_WITH, or CONTAINS. |
| order_by | string | VALUE (default) or COUNT. |
| order_direction | string | ASC (default) or DESC. |
| limit | integer | Number of values to return. Defaults to 100. |
| offset | integer | Number of values to skip. |
| page | integer | Page number, starting from 0. Used with per_page instead of limit and offset. |
| per_page | integer | Number of values on a page. |
GET /api/tags:values?application=XXXXX-XXXXX&name=orders.sku&order_by=COUNT&order_direction=DESC{ "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 toSet 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 toA 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 statusespaidandnewmatchesnoteq "paid".notinon a List field. No element contains any of the given values.notinon 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 toInsert 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.amountorprofile.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 injsonorjson_each_line. jsonandjson_each_line. Object tags come nested, in the same shape as/getTagsreturns them. AnObjecttag is one entry intagswith its fields underobject.fields, and a nested object inside it carries its own fields underobject.fieldstoo, at every level. AnObjectListtag is one entry with its elements inobject_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, orversion:
{ "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.