Tags API
Tags objects manage arbitrary strings that can be attached to a customer profile. They act as keyword classifiers and are associated with a counter to indicate the number of times a tag has been assigned.
Tags allow you to define segments of customers, each of which can be associated with targeting rules. Typically, the rules are designed to test for the presence of tags or their values and then take conditional steps based on them. For example, they can track simple customer actions such as abandoning an online shopping cart. With knowledge of the customer's decision to abandon a cart, you can retarget the customer to a new campaign or outcome.
In addition, tags may also have a TTL (Time to Live) associated with them. These tags expire and disappear after the TTL expires. Note that a tag may have either a count (counter tag) or a TTL (expiring tag), but not both.
This API provides a means to attach tags to a customer and show the tags that are already attached. It provides the following methods:
- Create or increment a customer tag
- Retrieve customer tags
- Create a batch job to ingest tags from a CSV file
Create or Increment a Customer Tag
Specifies a counter tag if it does not exist and sets its count to 1. If the counter tag already exists, its count is incremented by one.
If a TTL is specified, an expiring tag is created instead and the tag is set to the value specified. This kind of tag does not have a count. Note that multiple tags may be specified in a single invocation.
Endpoints
This method offers the following endpoints:
POST /priv/v1/apps/:api_key/users/:user_id/tags
POST /priv/v1/apps/:api_key/external/users/:external_id/tags
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Identifier for an internal customer. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
When this method runs, it passes in a request object that contains the tags object, as shown below:
This object is detailed in the following table:
Request Attributes for Tags
Attribute | Type Required/Optional |
Description |
---|---|---|
tags | array string required |
Tags to create. |
ttl | integer optional |
Time to Live, in seconds. If provided, attribute specifies number of seconds that tag remains set after created or updated. After specified time, tag expires. |
Response Object
In addition to a status key-value pair, the response object returned by the method contains the tags object, as shown below:
This object is detailed in the following table:
Attribute | Type | Description |
---|---|---|
tags | dictionary string: integer | All of customer's tags and their counts. |
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.
Retrieve Customer Tags
Retrieves all the tags associated with a customer, along with their counts.
Endpoints
This method offers the following endpoints:
GET /priv/v1/apps/:api_key/users/:user_id/tags
GET /priv/v1/apps/:api_key/external/users/:external_id/tags
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
user_id | Identifier for an internal customer. |
external_id | Identifier for a customer in an external system integrating with the SessionM Platform. |
Request Object
Not applicable.
Response Object
In addition to a status key-value pair, the response object returned by the method contains the tags object, as shown below:
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.
Create a Batch Job to Ingest Tags from a CSV File
Generates a collection of tags by ingesting them from a CSV file. This approach allows the caller to avoid supporting real-time submissions that create tags. In this case, the API allows a client to submit tags via a batch.
Endpoints
This method offers the following endpoints:
For more information on how to specify an endpoint as part of an actual URL, see Before You Begin. The procedure in this section includes a sample URL for a customer transaction.
Endpoint Parameters
The following parameters are available when specifying the endpoint for this method:
Endpoint Parameter | Description |
---|---|
api_key | Supplied by the SessionM Platform, the API key is necessary to authenticate any HTTP request to a SessionM API. This key is associated to an API secret, which ties the authentication to a specific application or web site within the organization. The platform maintains each application or site as a digital property, something that can be configured using the SessionM UI. |
Request Object
When this method runs, it passes in a tags request object that utilizes information in a CSV file. Consider the following samples:
{
"tags":{
"request_id":"917",
"url":"https://mybucket.s3.aws.acme.com/tags_contexts-20140101.csv",
"md5":"acbd18db4cc2f85cedef654fccc4a4d8",
"notify":"https://test.com/sessionm/tags/job/notification?id=JOB_ID&status=JOB_STATUS&request_id=JOB_REQUEST_ID"
}
}
external_id,tag,expires
user1234,foo,
user1235,bar,
user1236,bar,1 day
user1237,foo,
While the value for the attributes will differ, the tags request object contains the same attributes as those offered for an events request object.
The tags object ingests events headers and data from an associated CSV file, which is detailed below:
CSV Headers
Attribute | Type Required/Optional |
Description |
---|---|---|
user_id | string required, unless external_id provided; when both are present, user_id takes precedence. |
CSV header for a customer ID. |
external_id | string required, unless user_id provided; when both are present, user_id takes precedence. |
CSV header for an external customer ID. |
tag | string required |
CSV header for the tag. |
expires | string optional |
CSV header for the the tag's TTL (Time to Live). |
Response Object
In addition to a status key-value pair, the response object contains a tags object, as shown below:
{
"status": "ok",
"tags":
{
"id": 7,
"request_id": "sample_id_1",
"status": "created"
}
}
The attributes for this object are identical to those offered for an events response object.
Statuses and Errors
When this method makes a successful call to the platform, it returns a 200-level status code. When the string returned with a 200-level status code is ok, the transaction did process. But, if the string returned is error, you need to discover what type of error occurred.
Returned errors can be either method-specific or generic. No error messages are defined for this method except for the generic statuses and errors returned for any object. For more information, see the associated section in Generic Statuses and Errors.