Retently's API gives you the possibility to create, update, and remove customer properties for a more flexible segmentation of your audience and survey data.
There are two API endpoints that support customer properties management:
When using any of the aforementioned endpoints, you will have to send a Request that will include an array with one or more customers. To start managing properties, you will need to add a new parameter called "properties" in each customer's object.
NOTE: The Requests displayed next in this tutorial should serve as examples. Make sure to check our API documentation for accurate Request examples.
The "properties" parameter
The "properties" parameter is an array of objects. Each object is related to a specific property that will be created and assigned to the customer, updated, or removed.
The structure of a property object is:
{
"label": "",
"type": "",
"value": ""
}
"label" field
The "label" field will store a string value with the name of the property that will be created in Retently, and updated if it already exists in your account.
A property name that consists of two or more words will be converted into lowercase snake_case labels in Retently. For example, the label "New Property" will be converted to "new_property".
"type" field
In this field, you have to specify the type of property that you want to create. Retently supports five data types:
string
date
integer
boolean
collection
"value" field
In the value field, you will have to include the information that you want to store in the property. The value will be converted based on the specified "type" of the property:
"string" (ex: "New product")
"date" (ex: "12/31/2019")
"integer" (ex: 100)
"collection" (ex: "item1, item2, item3")
Creating new properties
To create a new property you have to simply add it to your Request's body, within a customer's object in the "properties" array.
If the property doesn't exist, then it will be created in your account, and it will be assigned to the customer or customers that have this property listed in their object.
Request body example:
{
"subscribers": [
{
"email": "johnsmith@example.com",
"first_name": "John",
"last_name": "Smith",
"company": "ACME",
"tags": [
"foo",
"bar"
],
"properties": [
{
"label": "Subscription name",
"type": "string",
"value": "Free trial"
}
]
}
]
}Based on our example, the "Subscription name" (subscription_name) property will be created in your Retently account, and assigned to the customer johnsmith@example.com, along with the "Free trial" value.
You can include as many property objects as needed in your request.
NOTE: If you do not include the "type" field in a property's object, then the property will be created automatically with the type of "string", and the value will be stored according to this type.
Updating values in an existing property
To update the value in a specific property of a particular customer, you will have to pass that property in a new request, with the "value" field updated.
For example, if we follow the example in the previous chapter, let's say that the customer johnsmith@example.com has upgraded their subscription from "Free trial" to "Professional plan". In order to update the customer's property, you will have to make the following request:
{
"subscribers": [
{
"email": "johnsmith@example.com",
"first_name": "John",
"last_name": "Smith",
"company": "ACME",
"tags": [
"foo",
"bar"
],
"properties": [
{
"label": "Subscription name",
"type": "string",
"value": "Professional plan"
}
]
}
]
}
Removing properties
There are two ways to remove a property from a customer:
1. Pass the property object with an empty array for the "value" parameter:
{
"subscribers": [
{
"email": "johnsmith@example.com",
"first_name": "John",
"last_name": "Smith",
"company": "ACME",
"tags": [
"foo",
"bar"
],
"properties": [
{
"label": "Subscription name",
"type": "string",
"value": ""
}
]
}
]
}2. Pass the property object and make sure it includes only the property "label" parameter:
{
"subscribers": [
{
"email": "johnsmith@example.com",
"first_name": "John",
"last_name": "Smith",
"company": "ACME",
"tags": [
"foo",
"bar"
],
"properties": [
{
"label": "Subscription name"
}
]
}
]
}Both ways will result in the property being removed from the customer.
NOTE: If you remove a property from a customer (or from all customers at the same time), this will simply un-assign the property from the customer, but it will not be deleted from your account. You can manage the actual properties on the "Props & Tags" page in your account.