API product catalogSub-Accounts & White-Label Retail KYC

Update sub-account

Sub-Accounts & White-Label Retail KYC

PATCH

/users/{userId}

Update sub-account

Sandbox availableupdateUsers

Updates mutable fields on a sub-account. All fields are optional — only provided fields are changed. Set status to frozen to immediately suspend all trading, deposits, and withdrawals for a user. Set back to active to restore access.

Parameters

userIdstringpathRequired

Example: usr_abc123

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

displayNamestring

New display name for the sub-account.

Example: "Alice Kamau"

emailstring

New email address.

statusactive | frozen

frozen suspends all trading, deposits and withdrawals. Set back to active to restore access.

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

200Updated sub-account.

Request reference

Sandbox available

userId Required · path

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

https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D

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 PATCH 'https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "Jane Doe Updated"
}'

GET /users/{userId}

GET /users/{userId}/buying-power