Skip to content

Customers TCP API

Customer is a CRM/KYC/AML entity above trading accounts. It does not replace account login or trading runtime identity.

customer_id is an int. A trading account is linked to a customer through AccountRecord.customer_id / Users.customer_id.

customer_id = 0 means the account is not linked to any customer. This is valid.

Access Control

All customer methods require one of:

  • SESSION_MANAGER
  • SESSION_ADMIN
  • SESSION_DEALER
  • SESSION_CRM_MANAGER
  • SESSION_CRM_ADMIN

Customer Fields

Field Type Notes
customer_id int Primary customer identifier
external_id string Optional external CRM/PSP/reference ID
type int CUSTOMER_TYPE_INDIVIDUAL = 0, CUSTOMER_TYPE_BUSINESS = 1
status int CUSTOMER_STATUS_ACTIVE = 0, CUSTOMER_STATUS_BLOCKED = 1, CUSTOMER_STATUS_ARCHIVED = 2, CUSTOMER_STATUS_PROSPECT = 3
enable int 1 enabled, 0 disabled
enable_otp int 1 requires OTP during customer auth
first_name, last_name, middle_name, full_name string Identity fields
birth_date time_t Unix timestamp
citizenship, country_of_residence string Profile/compliance fields
email string Unique for non-empty values; used for customer auth
phone string Customer phone
preferred_language, timezone string Communication preferences
brand string Optional brand scope
desk_id int CRM desk id
manager_id int Assigned manager id
lead_source, campaign, affiliate_id, introducer_id string Acquisition data
assigned_manager_id int CRM owner/manager id
crm_stage, segment, tags_json string CRM classification fields
email_verified, phone_verified, marketing_allowed int Boolean flags
tax_id, national_id string Compliance identifiers
pep_status int CUSTOMER_PEP_UNKNOWN = 0, CUSTOMER_PEP_CLEAR = 1, CUSTOMER_PEP_POSITIVE = 2
sanctions_status int CUSTOMER_SANCTIONS_UNKNOWN = 0, CUSTOMER_SANCTIONS_CLEAR = 1, CUSTOMER_SANCTIONS_POSITIVE = 2, CUSTOMER_SANCTIONS_REVIEW = 3
risk_level int CUSTOMER_RISK_LOW = 0, CUSTOMER_RISK_MEDIUM = 1, CUSTOMER_RISK_HIGH = 2
aml_status int CUSTOMER_AML_PENDING = 0, CUSTOMER_AML_REVIEW = 1, CUSTOMER_AML_APPROVED = 2, CUSTOMER_AML_REJECTED = 3
kyc_status int CRM status dictionary id, 0 means not assigned
sales_status int CRM status dictionary id, 0 means not assigned
risk_status int CRM status dictionary id, 0 means not assigned
finance_status int CRM status dictionary id, 0 means not assigned
kyc_updated_time, aml_updated_time time_t Status update timestamps
last_contact_time, next_contact_time, conversion_time, last_login_time time_t CRM/customer lifecycle timestamps
created_time, updated_time time_t Record lifecycle timestamps
created_by, updated_by int Manager ids
meta_json string Optional JSON extension payload

Sensitive fields such as password hash and OTP secret are not returned in customer responses.

Customer Status Dictionary

CRM workflow statuses are configurable records from customer_statuses. Customer fields kyc_status, sales_status, risk_status, and finance_status store status ids. Value 0 means that a status is not assigned.

Status types:

Value Name
0 CUSTOMER_STATUS_TYPE_SALES
1 CUSTOMER_STATUS_TYPE_FINANCE
2 CUSTOMER_STATUS_TYPE_TRADE
3 CUSTOMER_STATUS_TYPE_RISK
4 CUSTOMER_STATUS_TYPE_KYC

Status record fields:

Field Type Notes
id int Status id
brand string Optional brand scope
type int Status type enum
status_name string Display name
status_description string Optional description
status_color string Optional UI color
sort int Sort order
created_time, updated_time time_t Record timestamps
created_by, updated_by int Manager ids

Customer Commands

Customer Status Commands

Errors

Common errors:

  • INVALID_DATA
  • RET_NOT_FOUND
  • RET_DUPLICATE_RECORD
  • RET_INVALID_PASSWORD