General Information

Client attributes in Sailplay are additional data that can be stored to describe and personalize clients. They extend the standard user profile and allow:

• Using values for filtering and segmenting clients (e.g., highlighting all users from a specific city or with a certain interest).
• Setting up personalized communications and trigger scenarios.
• Inserting data into message templates. Attributes can be used as variables in email, SMS, and push notifications.
• Storing an additional client identifier (e.g., an external CRM ID or a mobile app device ID).
• Running promotions based on specific values (e.g., a unique offer for a product chosen by the client).

Each attribute has three key characteristics: type, cardinality, and uniqueness.

---

Attribute Types

The type determines the format and allowed values of the attribute.

Type	Subtype	Value	Example Values
string	value	Text string	"London"
date	value	Date in YYYY‑MM‑DD format	"1995‑04‑23"
integer	value	Integer	42
sku	reference	Link to product (SKU)	{ "ref_type": "sku", "ref_id": "171850" }
product	reference	Link to product (product ID in Sailplay system)	{"ref_type":"product", "ref_id":"875435"}
department	reference	Link to department (department ID in Sailplay system)	{"ref_type":"department", "ref_id":"4552"}
user	reference	Link to client (user_id in Sailplay system)	{"ref_type":"user", "ref_id":"114765948"}

Attributes of the reference subtype are used to link a client with external entities. For example, the sku type allows creating a link between a client and a product. This functionality enables setting a personalized discount on a specific product for a client.

---

Attribute Cardinality

Cardinality determines whether a client can have multiple values for a single attribute.

• Single Value (is_array = false)
  The attribute stores only one value for a client.
  Examples:

  • Place of birth — "Denpasar"
  • Favorite fruit — "Apple"

• Multiple Values (is_array = true)
  The attribute stores a list of values for a client.
  Examples:

  • Children's names — ["Annet", "John"]
  • Favorite product categories — ["electronics", "toys", "books"]

---

Attribute Uniqueness

Uniqueness (is_unique = true) determines whether an attribute value can be used as a client identifier. If uniqueness is enabled, the value must be unique among all clients. Such an attribute can be used for searching, identifying, and integrating clients (examples: card_number, crm_id, session_id).

Attributes without uniqueness (is_unique = false) can be repeated across different clients (e.g., "city of residence" or "interests").

How to Create an Attribute

Contact technical support: support@sailplay.net and provide:

1. partner_id — account identifier.
2. name — technical name (Latin characters, no spaces or special symbols).
   Minimum length: 4 characters. Maximum length: 32 characters. Example: city_name.
3. title — user-friendly name for display in the dashboard. Example: City of Residence.
4. description — a brief description of the attribute's purpose.
   Example: Client's city of residence to exclude Moscow residents from communications regarding St. Petersburg.
5. attribute_type — attribute type.
6. is_array — attribute cardinality (specify if a single client can have a list of values for one attribute).
7. is_unique — attribute uniqueness (specify if the attribute will be used as a client identifier).

Pre-set attribute properties cannot be changed during their usage.

---

API Method Map

Below is a list of methods used for working with client attributes. When moving documentation to your portal, replace the links with the corresponding pages in your API section.

Group	Purpose	Method URL
Client Attributes	Get attributes	/api/v2/users/attributes/get-partner-attributes-list/
	Get attribute values	/api/v2/users/attributes/get-values-by-attribute/
	Get client attribute values	/api/v2/users/attributes/get-values-by-user/
	Add attribute value	/api/v2/users/attributes/set-values-for-user/
	Add value to attribute array	/api/v2/users/attributes/push-values-to-array/
	Remove value from attribute array	/api/v2/users/attributes/pop-values-from-array/

---

Get List of All Attributes

To retrieve attributes previously added to the dashboard, use the method /api/v2/users/attributes/get-partner-attributes-list/. The method supports pagination by page number with an indication of the number of elements per page.

Request

curl --request GET \
  --url https://api.sailplay.net/api/v2/users/attributes/get-partner-attributes-list/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data page=1 \
  --data per_page=50

Response

{
  "status": "ok",
  "result": {
    "Region": [
      {
        "description": "client's region, manually selected by the client in the dashboard",
        "title": "Client Region",
        "is_array": false,
        "is_unique": false,
        "type": {
          "name": "string",
          "parameters": {}
        }
      }
    ],
    "City": [
      {
        "description": "Automatically detected client cities",
        "title": "Client City",
        "is_array": true,
        "is_unique": false,
        "type": {
          "name": "string",
          "parameters": {}
        }
      }
    ]
  }
}

---

Get Attribute Values

To retrieve attribute values, execute a request to /api/v2/users/attributes/get-values-by-attribute/ specifying a list of attributes.

• attr_names — list — list of technical attribute names.

Below is an example request to retrieve values for two attributes: Region (is_array = false) and City (is_array = true). The response returns arrays for the two attributes:

• Within the Region attribute, an array consisting of dictionaries is returned.
• Within the City attribute, an array consisting of dictionaries with a nested array of values is returned.

Request

curl --request GET \
  --url https://api.sailplay.net/api/v2/users/attributes/get-values-by-attribute/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data page=1 \
  --data per_page=50 \
  --data 'attr_names=["Region","City"]'

Response

{
  "status": "ok",
  "result": {
    "City": [
      {
        "value": [
          "Moscow"
        ]
      },
      {
        "value": [
          "Kyiv",
          "Minsk",
          "Odessa"
        ]
      }
    ],
    "Region": [
      {
        "value": "Europe"
      },
      {
        "value": "North America"
      },
      {
        "value": "Russia"
      }
    ]
  }
}

---

Get Client Attribute Values

To retrieve a list of a client's attribute values, execute a request to /api/v2/users/attributes/get-values-by-user/ listing the attributes.

• attributes — string — list of technical attribute names separated by commas. Spaces around the separator are not allowed.

Request

curl --request GET \
  --url https://api.sailplay.net/api/v2/users/attributes/get-values-by-user/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data user_phone=79998880011 \
  --data 'attributes=Region,City'

Response

{
  "status": "ok",
  "result": {
    "City": [
      {
        "title": "Client City",
        "description": "Automatically detected client cities",
        "value": [
          "Almaty",
          "Minsk",
          "Boston"
        ],
        "value_id": [
          948618149,
          948618150,
          948618151
        ]
      }
    ],
    "Region": [
      {
        "title": "Client Region",
        "description": "client's region, manually selected by the client in the dashboard",
        "value": "Russia",
        "value_id": 262833408
      }
    ]
  }
}

If an attribute is not found or the name was passed incorrectly, the system will return an empty result:

Response

{
  "status": "ok",
  "result": {}
}

The attributes parameter is not mandatory. In the absence of the attributes parameter, the system will return all attributes assigned to the client.

---

Add Attribute Value

The method /api/v2/users/attributes/set-values-for-user/ is used to assign new values to attributes and overwrite existing ones.

Request

curl --request POST \
  --url https://api.sailplay.net/api/v2/users/attributes/set-values-for-user/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data user_phone=79998880011 \
  --data 'attributes=[{"name":"country","value":"USA"},{"name":"region","value":"Boston"}]'

Response

{
  "status": "ok"
}

Parameter:

• attributes — array — an array of dictionaries with attributes and their values.

Example attributes structure:

attributes

[
  {
    "name": "country",
    "value": "USA"
  }
]

• name — string — technical name of the attribute.
• value — element type must match the attribute type.

The method accepts both single and multiple dictionaries with attributes within a single request:

attributes

[
  {
    "name": "country",
    "value": "USA"
  },
  {
    "name": "region",
    "value": "Boston"
  }
]

If the attribute is_array = true, then value must be enclosed in square brackets, regardless of whether you are passing one or several values:

attributes

[
  {
    "name": "child_names",
    "value": [
      "Sam",
      "John"
    ]
  }
]

---

Add Array of Values

The method /api/v2/users/attributes/push-values-to-array/ is designed for adding new elements to a client's attribute with cardinality is_array = true.

Request

curl --request POST \
  --url https://api.sailplay.net/api/v2/users/attributes/push-values-to-array/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data user_phone=79998880011 \
  --data 'attributes={"name":"City","value":["Moscow","Astana"]}'

Response

{
  "status": "ok"
}

Parameter:

• attributes — object — dictionary of attributes and values. The method processes only one attribute per call.
  • value — array — list of added values (minimum one element). The type of array elements must match the attribute type.

Example attributes structure:

attributes

{
  "name": "City",
  "value": [
    "Moscow",
    "Astana"
  ]
}

---

Remove Value from Attribute Array

The method /api/v2/users/attributes/pop-values-from-array/ removes attribute values with cardinality is_array = true. The types of the attributes parameter match those in the method for adding an array of values.

Request

curl --request POST \
  --url https://api.sailplay.net/api/v2/users/attributes/pop-values-from-array/ \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data token=*** \
  --data store_department_id=*** \
  --data user_phone=79998880011 \
  --data 'attributes={"name":"City","value":["Moscow"]}'

Response

{
  "status": "ok"
}