Skip to content

Audience ​

These tools find the tags, segments and custom fields in an account, for example to choose who a campaign goes to or which tag starts an automation.

They are read-only. Tags, segments and custom fields are created and edited in Rule. The tools never read or change individual subscribers.

Every tool also takes the optional account_id (see Accounts). It is left out of the tables below.

Paging ​

All four tools return up to 100 items at a time:

ParameterTypeRequiredDescription
pagenumberNoPage number, starting at 1.
per_pagenumberNoItems per page, up to 100. Defaults to 100.

Each answer says whether there are more pages (hasMore). To find something specific, the assistant searches by name (query) instead of paging, and only then says whether it exists.

list-tags ​

Lists the account's tags with their id and a link to each tag in Rule, or finds tags by name.

ParameterTypeRequiredDescription
querystringNoFind every tag whose name contains this text (not case-sensitive). The whole list is searched, so paging does not apply.
page, per_pagenumberNoSee Paging.
  • A search says whether the whole list was searched (searchedAll). In an account with a very large number of tags, a tag that is not found may still exist.
  • Rule does not report how many tags there are in total, so the assistant cannot tell you the number of pages.

Try asking: "List my tags."

list-segments ​

Lists the account's segments with their id and a link to each segment in Rule, or finds segments by name.

ParameterTypeRequiredDescription
querystringNoFind every segment whose name contains this text (not case-sensitive). The whole list is searched, so paging does not apply.
page, per_pagenumberNoSee Paging.
  • Segments that Rule creates for its own use (behind automation delays) are not listed. A page can therefore hold fewer segments than per_page.
  • The rules that define a segment cannot be read here; open the segment in Rule.

Try asking: "Which segments do I have?"

list-custom-field-groups ​

Lists the account's custom field groups, each with the custom fields inside it.

ParameterTypeRequiredDescription
querystringNoOnly groups whose name contains this text (not case-sensitive).
include_fieldsbooleanNoInclude each group's fields. Defaults to true. With false, each group shows only how many fields it has.
page, per_pagenumberNoSee Paging.
  • Each field has a type, such as text, number, boolean, date, single or multiple.
  • A group marked historical keeps every value a subscriber has had (for example one entry per order), not just the latest.
  • The selectable values of single and multiple fields are not listed; they come from subscriber data.
  • In an account with very many fields, a page can be too large to return. The tool then says so, and the assistant lists the groups without their fields (include_fields: false), or searches with query.
  • To check whether a group exists, the assistant searches for it by name rather than paging.

Try asking: "What custom fields do I have?"

list-custom-fields ​

Lists the custom fields in one group.

ParameterTypeRequiredDescription
group_idnumberYesThe group's id, from list-custom-field-groups.
querystringNoOnly fields whose name contains this text (not case-sensitive).
page, per_pagenumberNoSee Paging.
  • A group that does not belong to the account is reported as not found.

Try asking: "Which fields are in my Orders group?"