API product catalogSub-Accounts & White-Label Retail KYC

Create sub-account

Sub-Accounts & White-Label Retail KYC

POST

/users

Create sub-account

Sandbox availablecreateUsers

Creates a new sub-account. Each sub-account has an isolated USD wallet, portfolio, and order book. The externalId is your own reference — it must be unique per partner and is used in all subsequent calls. Sub-accounts start with a walletBalance of $0 — fund them via POST /users/{userId}/deposit.

Parameters

This endpoint has no path or query parameters.

Headers

AuthorizationstringRequired

Bearer sk_sandbox_<your_key> for sandbox requests.

Idempotency-KeystringheaderRequired

Unique string that makes write calls safe to retry on network failure. Required for money movement, trading, KYC, subscriptions, and webhook creation. Deduplicated for 24 hours -- duplicate keys return the cached response. HTTP 409 if a concurrent request with the same key is still in progress.

Example: dep_user42_1743152580

Request body

externalIdstringRequired

Your internal user identifier. Must be unique per partner.

Example: "usr_8821"

displayNamestring

Full name shown in the MyStocks admin console.

Example: "Alice K."

emailstring

Email address for the sub-account user.

Example: "alice@yourapp.com"

phonestring

Customer phone number in international format when available.

Example: "+254712345678"

countrystring

ISO 3166-1 alpha-2 country code used for onboarding and compliance context.

Example: "KE"

Response fields

subAccountIdstring

MyStocks internal ID. Use in /users/{userId}/... paths.

Example: "usr_abc123"

userIdstring

Compatible alias of subAccountId. Use subAccountId as the canonical stored identifier.

externalIdstring

Your own user identifier as set at creation.

Example: "usr_8821"

displayNamestring | null

Example: "Alice K."

emailstring | null

Example: "alice@yourapp.com"

kycStatusNONE | PENDING | VERIFIED | REJECTED

VERIFIED required for trading and asset subscriptions. REJECTED remains gated until re-asserted.

kycLevelNONE | BASIC | FULL

BASIC = ID verified. FULL = enhanced due diligence.

kycRejectionCodestring | null

Stable rejection code when kycStatus is REJECTED.

kycRejectionReasonstring | null

Customer-safe remediation guidance when kycStatus is REJECTED.

kycReviewedAtstring | null

Timestamp of the rejection decision.

statusactive | frozen | closed

walletBalancenumber

Current USD wallet balance.

Example: 1250

Response codes

201Sub-account created.

409externalId already exists.

Request reference

Sandbox available

Use the API Tester for write requests, including request bodies and idempotency keys.

https://mystocks.africa/api/sandbox/v1/partner/users

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "subAccountId": {
      "type": "string",
      "example": "usr_abc123",
      "description": "MyStocks internal ID. Use in /users/{userId}/... paths."
    },
    "userId": {
      "type": "string",
      "description": "Compatible alias of subAccountId. Use subAccountId as the canonical stored identifier."
    },
    "externalId": {
      "type": "string",
      "example": "usr_8821",
      "description": "Your own user identifier as set at creation."
    },
    "displayName": {
      "type": [
        "string",
        "null"
      ],
      "example": "Alice K."
    },
    "email": {
      "type": [
        "string",
        "null"
      ],
      "example": "alice@yourapp.com"
    },
    "kycStatus": {
      "type": "string",
      "enum": [
        "NONE",
        "PENDING",
        "VERIFIED",
        "REJECTED"
      ],
      "description": "VERIFIED required for trading and asset subscriptions. REJECTED remains gated until re-asserted."
    },
    "kycLevel": {
      "type": "string",
      "enum": [
        "NONE",
        "BASIC",
        "FULL"
      ],
      "description": "BASIC = ID verified. FULL = enhanced due diligence."
    },
    "kycRejectionCode": {
      "type": [
        "string",
        "null"
      ],
      "description": "Stable rejection code when kycStatus is REJECTED."
    },
    "kycRejectionReason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Customer-safe remediation guidance when kycStatus is REJECTED."
    },
    "kycReviewedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Timestamp of the rejection decision."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "frozen",
        "closed"
      ]
    },
    "walletBalance": {
      "type": "number",
      "example": 1250,
      "description": "Current USD wallet balance."
    }
  }
}

curl -X POST 'https://mystocks.africa/api/sandbox/v1/partner/users' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "externalId": "user_42",
  "displayName": "Jane Doe",
  "email": "jane@example.com"
}'

GET /users

DELETE /users/{userId}