Retently's API gives you the ability to create and update customer properties for more flexible segmentation of your audience and survey data.

Two API endpoints support customer properties management:

Create or update customers (POST /api/v2/customers)
Send transactional surveys (POST /api/v2/survey)

With either endpoint, you send a request containing an array of one or more customers. To manage properties, add a properties array to each customer's object.

NOTE: The requests below are examples. Always check the API documentation for the authoritative request format.

The "properties" parameter

properties is an array of objects. Each object describes one property to create, assign, or update on the customer.

The structure of a property object is:

{
    "label": "",
    "type": "",
    "value": ""
}

"label" field

A string with the property name. The property is created in Retently if it doesn't exist, and updated if it does. A name with two or more words is converted to a lowercase snake_case label. For example, "New Property" becomes "new_property".

"type" field

The property's data type. Retently supports five types:

string
date
integer
boolean
collection

If you omit type and the property already exists in your account, the value is stored using that property's existing type. If the property is new, it defaults to string.

"value" field

The information stored in the property. The value is interpreted according to the property's type:

string: any text, e.g. "New product"
integer: a whole number, e.g. 100
boolean: true / false, 1 / 0, or Yes / No / Y / N (case-insensitive)
collection: a comma-separated list, e.g. "item1, item2, item3"
date: see the date guidance below

For date values, the unambiguous form is ISO 8601 with an explicit timezone, e.g. "2019-12-31T00:00:00Z". The date-only form "2019-12-31" is also safe and is treated as UTC midnight. Other accepted formats (US-style "MM/DD/YYYY", "YYYY/MM/DD", or ISO without a Z) are parsed in the server's local timezone and may shift the stored date, so prefer the explicit-Z form. The format "DD/MM/YYYY" (e.g. "31/12/2019") is not parsed and the value will not be stored on the contact.

Creating new properties

To create a property, add it to a customer's properties array. If it doesn't exist, it's created in your account and assigned to the listed customers with the given value.

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

Here, "Subscription name" (subscription_name) is created and assigned to johnsmith@example.com with the value "Free trial". You can include as many property objects as needed.

Updating values in an existing property

To update a value, send the customer again with the property's value changed. For example, if johnsmith@example.com upgrades from "Free trial" to "Professional plan":

{
    "subscribers": [
        {
            "email": "johnsmith@example.com",
            "properties": [
                {
                    "label": "Subscription name",
                    "type": "string",
                    "value": "Professional plan"
                }
            ]
        }
    ]
}

Properties the customer already has that are not included in your request are left untouched. They are not updated, removed, or overwritten.

Unassigning a property from a customer

These API endpoints can unassign a property from a customer. Send the property with an empty string ("") or null as its value. Whatever value the property currently holds for that customer is cleared, and the property is unassigned from them.

{
    "subscribers": [
        {
            "email": "johnsmith@example.com",
            "properties": [
                {
                    "label": "Subscription name",
                    "value": ""
                }
            ]
        }
    ]
}

Here, "Subscription name" is unassigned from johnsmith@example.com. Sending null as the value has the same effect.

This only affects the single customer in your request:

The property itself is not deleted from your account. It stays available on the "Contact attributes" page.
The property stays assigned to every other customer that has it. Their values are untouched.

An empty string or null clears the value for this one customer only. To delete a property from your account entirely, use the "Contact attributes" page.

To manage your account's properties, use the "Contact attributes" page in your account.

Manage customer properties via API