General Information

A client record in Sailplay is a unified customer card that aggregates their basic information, identifiers, contact details, loyalty program statuses, tags, and any other arbitrary attributes.
This entity lies at the heart of personalized communications, segmentation, bonus and discount calculations, as well as marketing automation scenarios.

---

Client Identifiers

The following key identifiers are used to reference a client in the API and automation processes.

Primary Client Identifier (user_id)

A unique internal identifier automatically assigned by Sailplay when a record is created.
It is the primary identifier in the system. It can only be changed during the merging of client profiles.

---

External Identifier (origin_user_id)

An additional client identifier, typically used for linking with external data sources
(for example, a loyalty card number or an identifier from a CRM system).

• can contain arbitrary string values;
• allows for modification and updates when necessary.

---

Phone (user_phone)

A unique client phone number. Used primarily for SMS communications, but can also be applied as an identifier in external integrations.

Format Requirements:

• international format without the + symbol, for example 79998887766;
• a single client can have only one phone number;
• creating a record with a landline number is not allowed.

---

Email (email)

A unique client email address.

• one email per client is allowed;
• email format validation is performed.

---

Additional Identifier (Attribute)

An arbitrary attribute with a unique value (for example, an identifier from a third-party system).

For such an integration, a special approach to working with entities is required (see corresponding documentation).

info

Any operations with a client in Sailplay (creating orders, awarding bonuses, assigning tags, etc.) can be performed using any of the identifiers:

user_id, origin_user_id, phone, email
or by the value of an additional attribute.

---

Basic API Parameters for Creating and Updating Clients

These parameters are used in Sailplay business logic for segmentation, personalization, and promotion setup.

• first_name — first name (e.g., Ivan)
• middle_name — middle name (e.g., Ivanovich)
• last_name — last name (e.g., Ivanov)
• birth_date — birth date in YYYY-MM-DD format
• sex — gender:
  • 1 — male
  • 2 — female
  • 3 — other
• register_date — registration date;
  minimum allowed date is 1971-01-01

note

Parameters in this section are not mandatory.

---

API Method Map for Clients

Purpose	Method
Get client information	/api/v2/users/info/
Create client	/api/v2/users/add/
Update client	/api/v2/users/update/
Merge clients	/api/v2/users/merge/

---

Creating a Client

To create a client, you must specify at least one identifier:

• origin_user_id
• phone
• email

Request Example

curl --request POST \
  --url https://api.sailplay.net/api/v2/users/add/ \
  --header 'accept: application/json' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data token=TOKEN \
  --data store_department_id=14864 \
  --data user_phone=79653215476 \
  --data email=ivanovivan@mail.net \
  --data origin_user_id=12345 \
  --data first_name=Ivan \
  --data middle_name=Ivanovich \
  --data last_name=Abramov \
  --data birth_date=1983-11-07 \
  --data sex=1 \
  --data register_date=2012-04-24

If the client already exists:

{
  "status": "error",
  "status_code": -5100,
  "message": "User already exist"
}

---

Updating a Client

Method: /api/v2/users/update/

Supports changing identifiers:

• new_phone
• new_email
• new_origin_user_id

To remove an identifier value, pass null.

Request Example

curl --request POST \
  --url https://api.sailplay.net/api/v2/users/update/ \
  --header 'accept: application/json' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data token=TOKEN \
  --data store_department_id=2444 \
  --data user_phone=79538889977 \
  --data new_phone=79994443322 \
  --data new_origin_user_id=null \
  --data new_email=myname@gmail.com

Errors

{ "status_code": -5102, "message": "Phone is used" }

{ "status_code": -5103, "message": "Email is used" }

{ "status_code": -5122, "message": "User ID belongs to another user" }

{ "status_code": -4000, "message": "User not found" }

---

Retrieving Client Information

The method for retrieving client information returns:

• Basic Information about the client
  (Full name, registration date, birth date).

• Subscription Statuses for communication channels (email, SMS, push).
  To retrieve statuses, you must pass the parameter subscriptions=1.
  The response will include a subscriptions array. The presence of a value in the array means an active subscription to the corresponding channel.

Response Examples with Subscription Statuses

{
  "subscriptions": [
    "email_all",
    "sms_all",
    "push_all"
  ]
}

{
  "subscriptions": [
    "email_all"
  ]
}

{
  "subscriptions": [
    "push_all"
  ]
}

{
  "subscriptions": [
    "sms_all"
  ]
}

---

Client Bonus Balance

The method returns the client's current bonus balance:

• confirmed — confirmed points, available for use;
• unconfirmed — points awaiting purchase confirmation;
• total — total points (confirmed + unconfirmed);
• spent — points spent on gifts;
• spent_extra — other deductions.

{
  "points": {
    "spent_extra": 1000,
    "confirmed": 255,
    "total": 355,
    "spent": 10,
    "unconfirmed": 100
  }
}

---

Purchase History and Bonus Operations

The method allows for retrieving the history of:

• purchases,
• bonus accruals,
• deductions,
• bonus expiration.

To include history, you must pass the parameter history=1.
Additionally, you can limit the period with from_date and to_date parameters (format: YYYY-MM-DD HH:MM:SS).

Example fragment of response with history:

{
  "history": [
    {
      "action": "expiration",
      "action_date": "2025-07-31T05:05:29.239",
      "is_completed": true,
      "points_delta": -250,
      "name": "Deduction of unused bonuses"
    },
    {
      "action": "extra",
      "action_date": "2025-07-23T04:58:44.423",
      "is_completed": true,
      "points_delta": 250,
      "name": "Bonus accrual"
    },
    {
      "action": "purchase",
      "action_date": "2025-06-11T12:06:45.301",
      "is_completed": true,
      "order_num": "20250611_120611_89_1_258_37",
      "points_delta": 0,
      "price": 799
    }
  ]
}

---

Checking Multiple Identifiers (Multi)

To check multiple identifiers, pass multi=1.

If multiple identifiers of the same type are specified, only one will be used.

---

Merging Client Records

Method /api/v2/users/merge/

In the request, you can specify a pair of identifiers of either the same or different types (for example, from_email → to_oid).

Parameter Set for Merging

Parameter	Value
from_uid	user_id of the from client
to_uid	user_id of the to client
from_phone	phone of the from client
to_phone	phone of the to client
from_email	email of the from client
to_email	email of the to client
from_oid	origin_user_id of the from client
to_oid	origin_user_id of the to client

Important

Only one pair of identifiers is allowed in a single request.

Merging Rules

Field	Result
user_id, phone, email	from to
origin_user_id, Full name, birth date, gender	from from

If a field is filled in only one profile, it is preserved.