Tags API

Attach keyword classifier tags to customer profiles, retrieve them, and ingest them in bulk from a CSV file.

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.

API Contingencies and Combinations:

Since tags are specified for customers, you must create the customers before you can implement their tags. Use the Standard Profile API to create customers and specify the attributes for their standard profiles.

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 for Create or Increment a Customer Tag

This method offers the following endpoints:

Here

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 for Create or Increment a Customer Tag

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 for Create or Increment a Customer Tag

When this method runs, it passes in a request object that contains the tags object, as shown below:

JSON Request

{
   "tags":[
    "tag1",
    "tag2"
   ],
   "ttl":2592000
}

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 for Create or Increment a Customer Tag

In addition to a status key-value pair, the response object returned by the method contains the tags object, as shown below:

Here

{
   "status":"ok",
   "tags":{
    "tag1":2,
    "tag2":5,
    "tag3":0
   }
}

This object is detailed in the following table:

Response Attributes for Tags

Attribute	Type	Description
tags	dictionary string: integer	All of customer's tags and their counts.

Statuses and Errors for Create or Increment a Customer Tag

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 for Retrieve Customer Tags

This method offers the following endpoints:

REST 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 for Retrieve Customer Tags

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 for Retrieve Customer Tags

Not applicable.

Response Object for Retrieve Customer Tags

In addition to a status key-value pair, the response object returned by the method contains the tags object, as shown below:

JSON Response

{
   "status":"ok",
   "tags":{
    "tag1":2,
    "tag2":5,
    "tag3":0
   }
}

Statuses and Errors for Retrieve Customer Tags

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 for Create a Batch Job to Ingest Tags from a CSV File

This method offers the following endpoints:

REST Endpoints

POST    /priv/v1/apps/:api_key/batch/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 for Create a Batch Job to Ingest Tags from a CSV File

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 for Create a Batch Job to Ingest Tags from a CSV File

When this method runs, it passes in a tags request object that utilizes information in a CSV file. Consider the following samples:

JSON Request

{
  "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"
  }
}

CSV File Corresponding with Request

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 for Create a Batch Job to Ingest Tags from a CSV File

In addition to a status key-value pair, the response object contains a tags object, as shown below:

JSON Response

{
  "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 for Create a Batch Job to Ingest Tags from a CSV File

Was this page helpful?