CustomerRegistration

Endpoint

POST /customer/registration

Description

Creates a new customer profile as a lead, with an empty milestone mask.

The server accepts public registration fields and resets manager/KYC/AML/internal fields to safe defaults. The optional address_of_residence is a free-text residence address of up to 255 characters; it is stored as supplied and returned in the customer profile.

When country_of_residence is absent, the server resolves it as an upper-case ISO 3166-1 alpha-2 code:

1. from the international dialling code of phone, if the number starts with + (spaces, -, (, ) and . are ignored). For a code shared by several countries, such as +1 (US, CA), the country of the source IP is used when it is one of them, otherwise the code's primary country;
2. otherwise from the source IP through GeoIP.

If neither source gives a country, the field stays empty. A supplied country_of_residence is stored as is.

The request must provide a customer name either as full_name or through at least one structured component: first_name, middle_name, or last_name. Both forms are normalized into the same customer structure.

The server assigns a random identicon avatar derived from the customer's email and a generated UUID. Any avatar value supplied in the public request is ignored. The returned customer includes the avatar reference. Existing customer records are not bulk-updated by this behavior.

registered: true confirms that the record was created. It does not mean that the customer has reached the Registered milestone. Every public registration starts with customer_kind = 0 and lifecycle_flags = 0. A manager or workflow must raise the Registered flag explicitly.

The brand is resolved from the HTTP request host. A body brand value is used only as a fallback when the request context permits it. Under negotiated license brand policy v1, the host used for brand lookup is canonicalized as a domain or IP address without a port; DNS names are lowercased, trailing DNS dots are removed, and IPv6 is normalized. Existing trusted forwarded-host precedence is unchanged.

Registration also resolves marketing attribution. A normal brand landing page is matched automatically; an external landing can provide an attribution object; a mobile application can provide an installation_id. See Marketing Attribution API.

Whether a touch remembered from an earlier visit is used depends on the global fingerprint_mode (UpdateConfig): 0 — None, only attribution / installation_id in this request; 1 — Once (default), a remembered touch attributes one registration and is then expired; 2 — Always, a remembered touch attributes every registration until it expires. The ScaleTrade terminal sends the marketing parameters of the link it was opened with as attribution.

The acquisition channel source_type is set by the server: 3 (affiliate) when the resolved attribution contains an affiliate, otherwise 1 (web). An explicitly passed source_type is kept; allowed values are 0, 1, 3, 5, 6, 7, see Source Type.

Affiliate integrations should create leads through CustomerRegistrationByAffiliate. Automatic account creation is configured separately as a customer.created workflow; public registration does not select a trading group.

If the resolved brand has authorize_after_registration = 1, successful registration also creates a customer session and returns __token and __datalake_token. The Data Lake token is null if the active v2 signer or current authorization context is unavailable; the registration and primary session still succeed. The flag defaults to 0; in that mode neither token is returned and the customer must use the normal sign-in endpoint after registration.

Request

{
  "email": "[email protected]",
  "password": "strong-password",
  "full_name": "John Smith",
  "phone": "+35700000000",
  "brand": "default",
  "preferred_language": "en",
  "timezone": "Asia/Nicosia",
  "address_of_residence": "12 Example Street, Limassol",
  "marketing_allowed": 1
}

External landing attribution

{
  "email": "[email protected]",
  "password": "strong-password",
  "first_name": "John",
  "last_name": "Smith",
  "attribution": {
    "affiliate": "AFF1024",
    "campaign": "FB_CY_01",
    "utm_source": "partner-landing",
    "utm_medium": "affiliate",
    "sub_id": "creative-7"
  }
}

Mobile registration

{
  "email": "[email protected]",
  "password": "strong-password",
  "full_name": "John Smith",
  "installation_id": "4c0b68c8-3c90-46dc-a0dc-e092f879dd80"
}

Customer name formats

The API accepts either representation:

{
  "full_name": "John Smith"
}

or:

{
  "first_name": "John",
  "last_name": "Smith"
}

Name fields are trimmed and repeated whitespace is collapsed. The following normalization rules apply:

• when structured components are supplied without full_name, the server joins the non-empty first_name, middle_name, and last_name values in that order;
• when only full_name is supplied, the first word becomes first_name and the remaining text becomes last_name; a single-word name becomes first_name;
• when both forms are supplied, all explicit values are preserved and full_name is treated as the display name;
• middle_name is never inferred from full_name;
• the normalized or assembled full_name must not exceed 255 characters;
• an empty or whitespace-only name is rejected.

Automatic parsing is intentionally a fallback. Integrations that know the customer's structured name should send first_name and last_name explicitly.

Response

{
  "registered": true,
  "customer": {
    "customer_id": 1,
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Smith",
    "full_name": "John Smith",
    "status": 0,
    "lifecycle_flags": 0,
    "customer_kind": 0,
    "conversion_flags": 0,
    "enable": 1,
    "deposit_allowed": 1,
    "withdrawal_allowed": 1,
    "brand": "default",
    "avatar": "8e68414e-0e3f-48dd-b7b8-f5be9e26d4f7.svg",
    "source_type": 1,
    "last_online_time": 0,
    "created_time": 1777600000,
    "updated_time": 1777600000
  },
  "__token": "<HS256 session JWT>",
  "__datalake_token": "<EdDSA Data Lake JWT or null>"
}

__token and __datalake_token are conditional and are present only when the resolved brand enables authorize_after_registration. __token matches the normal customer session token; __datalake_token follows the Data Lake token profile. Issuing the session also updates the customer's last_login_time.

Response Parameters

Field	Type	Description
registered	bool	true after the customer has been created
customer	object	Created customer profile
customer.avatar	string	Server-generated public identicon reference
customer.last_online_time	int64	Read-only time when any trading account of the customer last went offline in the trading terminal; initially 0
__token	string	Optional primary customer session JWT when brand auto-authorization is enabled
__datalake_token	string or null	Optional Data Lake JWT when brand auto-authorization is enabled; may be null when the v2 signer or current authorization context is unavailable

Errors

HTTP	Error	Description
400	INVALID_DATA	Invalid request body or no usable customer name
404	BRAND_NOT_FOUND	Request host/fallback brand does not resolve to an active API-admitted brand, or is denied by negotiated license policy
409	DUPLICATE_RECORD	Email is already registered

Lifecycle

Public registration always creates a lead with an empty milestone mask. Raising the Registered flag is explicit:

• a CRM manager writes lifecycle_flags with MngUpdateCustomer; or
• a workflow executes customer.set_lifecycle_flags.

Conversion from lead to client is a separate operation, performed by MngConvertLeadToClient.

The response field registered describes the registration operation and must not be used as a milestone value.