MngAddCustomer

Creates a customer record in CRM. A customer is the business/KYC entity above trading accounts. Trading accounts can later be linked to the customer through customer_id.

Use this method when a manager, CRM admin, integration, or import flow needs to create a customer profile before or after opening trading accounts.

SEO

Page summary: Create a CRM customer through the ScaleTrade manager TCP API.

Keywords: ScaleTrade customer API, MngAddCustomer, create CRM customer, manager TCP API, customer onboarding API, KYC customer record, AML customer record, trading CRM customer.

Access Control

Allowed sessions:

• SESSION_MANAGER
• SESSION_ADMIN
• SESSION_DEALER
• SESSION_CRM_MANAGER
• SESSION_CRM_ADMIN

Behavior

• customer_id is optional. If it is omitted or 0, backend assigns a new id.
• email is optional, but non-empty email values must be unique.
• password is optional. If provided, it must be 6-128 characters and is stored as a hash. Password hash is never returned.
• desk is normalized to uppercase.
• If desk is provided, it must exist, be enabled, not archived, and belong to the same brand.
• Sensitive fields such as password hash and OTP secret are not returned in the response.

Request

{
  "command": "MngAddCustomer",
  "extID": "1",
  "data": {
    "brand": "default",
    "desk": "DESK_RETENTION",
    "email": "[email protected]",
    "password": "strong-password",
    "first_name": "John",
    "last_name": "Smith",
    "full_name": "John Smith",
    "phone": "+442000000000",
    "type": 0,
    "status": 0,
    "assigned_manager_id": 10,
    "lead_source": "web",
    "campaign": "spring-landing",
    "kyc_status": 0,
    "sales_status": 0,
    "risk_level": 0,
    "aml_status": 0
  }
}

Request Data

Core fields:

Field	Type	Required	Description
customer_id	int	No	Optional explicit customer id. Use 0 or omit for auto id
external_id	string	No	External CRM, PSP, affiliate, or import reference
brand	string	No	Brand namespace
desk	string	No	CRM desk code, for example DESK_RETENTION
manager_id	int	No	Legacy/responsible manager id
assigned_manager_id	int	No	CRM owner/assigned manager id
type	int	No	0 individual, 1 business
status	int	No	0 active, 1 blocked, 2 archived, 3 prospect
enable	int	No	1 enabled, 0 disabled
password	string	No	Customer auth password, 6-128 characters

Identity and contact fields:

Field	Type	Required	Description
first_name	string	No	First name
last_name	string	No	Last name
middle_name	string	No	Middle name
full_name	string	No	Full display/legal name
birth_date	time_t	No	Unix timestamp
citizenship	string	No	Citizenship country/code
country_of_residence	string	No	Residence country/code
email	string	No	Customer email, unique when not empty
phone	string	No	Customer phone
preferred_language	string	No	Language preference
timezone	string	No	Timezone label

CRM and acquisition fields:

Field	Type	Required	Description
lead_source	string	No	Acquisition source
campaign	string	No	Campaign identifier
affiliate_id	string	No	Affiliate reference
introducer_id	string	No	Introducer/IB reference
crm_stage	string	No	CRM pipeline stage
segment	string	No	Customer segment
tags_json	string	No	JSON string with tags or labels
marketing_allowed	int	No	1 marketing allowed, 0 not allowed

Compliance and status fields:

Field	Type	Required	Description
email_verified	int	No	1 verified, 0 not verified
phone_verified	int	No	1 verified, 0 not verified
tax_id	string	No	Tax identifier
national_id	string	No	National identity number
pep_status	int	No	0 unknown, 1 clear, 2 positive
sanctions_status	int	No	0 unknown, 1 clear, 2 positive, 3 review
risk_level	int	No	0 low, 1 medium, 2 high
aml_status	int	No	0 pending, 1 review, 2 approved, 3 rejected
kyc_status	int	No	Customer status dictionary id, 0 means not assigned
sales_status	int	No	Customer status dictionary id, 0 means not assigned
risk_status	int	No	Customer status dictionary id, 0 means not assigned
finance_status	int	No	Customer status dictionary id, 0 means not assigned
kyc_updated_time	time_t	No	KYC status update timestamp
aml_updated_time	time_t	No	AML status update timestamp

Lifecycle and extension fields:

Field	Type	Required	Description
last_contact_time	time_t	No	Last CRM contact timestamp
next_contact_time	time_t	No	Next planned contact timestamp
conversion_time	time_t	No	Conversion timestamp
last_login_time	time_t	No	Last customer login timestamp
created_by	int	No	Creator manager id
updated_by	int	No	Updater manager id
meta_json	string	No	Optional JSON extension payload

Response Data

Returns the created customer object. Sensitive authentication fields are not returned.

{
  "customer": {
    "customer_id": 1,
    "external_id": "",
    "type": 0,
    "status": 0,
    "enable": 1,
    "enable_otp": 0,
    "first_name": "John",
    "last_name": "Smith",
    "middle_name": "",
    "full_name": "John Smith",
    "birth_date": 0,
    "citizenship": "",
    "country_of_residence": "",
    "email": "[email protected]",
    "phone": "+442000000000",
    "preferred_language": "",
    "timezone": "",
    "brand": "default",
    "desk": "DESK_RETENTION",
    "manager_id": 0,
    "lead_source": "web",
    "campaign": "spring-landing",
    "affiliate_id": "",
    "introducer_id": "",
    "assigned_manager_id": 10,
    "crm_stage": "",
    "segment": "",
    "tags_json": "",
    "email_verified": 0,
    "phone_verified": 0,
    "marketing_allowed": 0,
    "tax_id": "",
    "national_id": "",
    "pep_status": 0,
    "sanctions_status": 0,
    "risk_level": 0,
    "aml_status": 0,
    "kyc_status": 0,
    "sales_status": 0,
    "risk_status": 0,
    "finance_status": 0,
    "created_time": 1710000000,
    "updated_time": 1710000000
  }
}

Errors

Common errors:

Error	Description
INVALID_DATA	Request validation failed
INVALID_DESK	desk does not exist, is disabled, archived, or belongs to another brand
RET_DUPLICATE_RECORD	Customer id or unique email already exists
RET_ERROR	Storage or internal error