Skip to content
MyStocks Developers
API v1

API v1

Current stable contract

Versioning policyRelease changelog
Sandbox console
API product catalogSub-Accounts & White-Label Retail KYC

KYC assertion

Sub-Accounts & White-Label Retail KYC

POST

/users/{userId}/kyc

KYC assertion

Sandbox availablecreateKyc

Asserts the KYC status of a sub-account. MyStocks defers identity verification to your platform — you send us the result of your own KYC process. VERIFIED + BASIC is sufficient to unlock trading and asset subscriptions. FULL is required for higher transaction limits and private credit deals. REJECTED keeps the account gated and requires reasonCode plus customer-safe remediation text in reason; the response and kyc.updated webhook include reviewedAt. The reference field stores your internal KYC session ID for audit correlation. You may also attach an optional structured compliance profile (ID document type, date of birth, nationality, tax residency, PEP/sanctions screening result, risk rating, consent timestamp, evidence reference). Sensitive identifiers — idNumber and taxId — are stored as a sha256 fingerprint plus last-4 only and are never returned in full. All profile fields are optional and additive.

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

statusNONE | PENDING | VERIFIED | REJECTEDRequired

Overall KYC status of the user.

Example: "VERIFIED"

levelNONE | BASIC | FULLRequired

BASIC = government ID verified (sufficient for trading). FULL = address + enhanced due diligence.

Example: "BASIC"

providerstring

Name of the KYC provider that performed the verification (e.g. sumsub, smile_identity).

Example: "sumsub"

referencestring

Your internal KYC session reference for audit correlation.

Example: "kyc_session_88721"

reasonCodestring

Required when status is REJECTED. Stable machine-readable rejection code.

Example: "DOCUMENT_EXPIRED"

reasonstring

Required when status is REJECTED. Human-readable remediation guidance safe to show to the customer.

Example: "Submit a current government-issued identity document."

idDocumentTypePASSPORT | NATIONAL_ID | DRIVERS_LICENSE | VOTERS_CARD | RESIDENCE_PERMIT | OTHER

Type of identity document verified during your KYC process.

Example: "NATIONAL_ID"

idNumberstring

Identity document number. Stored as a sha256 fingerprint plus the last 4 characters only — never persisted or returned in full. The response and webhook echo back idNumberLast4.

Example: "24681012"

dateOfBirthstring

Date of birth in ISO YYYY-MM-DD format.

Example: "1990-04-17"

nationalitystring

Nationality as an ISO 3166-1 alpha-2 country code.

Example: "KE"

countryOfResidencestring

Country of residence as an ISO 3166-1 alpha-2 country code.

Example: "KE"

addressstring

Residential address (free-form, up to 500 characters).

Example: "12 Kenyatta Ave, Nairobi"

taxResidencystring

Country of tax residency as an ISO 3166-1 alpha-2 country code.

Example: "KE"

taxIdstring

Taxpayer identification number (TIN). Stored as a sha256 fingerprint plus the last 4 characters only — never persisted or returned in full. The response and webhook echo back taxIdLast4.

Example: "A012345678Z"

pepboolean

Whether the user is a politically exposed person.

Example: false

sanctionsResultCLEAR | FLAGGED | PENDING

Result of your sanctions/PEP screening.

Example: "CLEAR"

screeningProviderstring

Name of the sanctions/PEP screening provider.

Example: "comply_advantage"

riskRatingLOW | MEDIUM | HIGH

Risk rating assigned to the user by your onboarding process.

Example: "LOW"

consentAtstring

ISO 8601 timestamp when the user granted consent for processing.

Example: "2026-07-11T09:30:00Z"

evidenceReferencestring

Your reference/URL to the stored KYC evidence bundle for audit.

Example: "kyc_docs_88721"

employmentStatusEMPLOYED | SELF_EMPLOYED | UNEMPLOYED | STUDENT | RETIRED | OTHER

Employment status captured during onboarding.

Example: "EMPLOYED"

occupationstring

User occupation or role.

Example: "Software engineer"

employerNamestring

Employer or business name when available.

Example: "Acme Ltd"

sourceOfFundsunion

Source of funds used for investing.

Example: "SALARY"

sourceOfWealthunion

Source of accumulated wealth.

Example: "EMPLOYMENT_INCOME"

annualIncomeBandUNDER_10000 | 10000_50000 | 50000_100000 | 100000_250000 | 250000_1000000 | OVER_1000000

Annual income band in USD-equivalent.

Example: "50000_100000"

netWorthBandUNDER_25000 | 25000_100000 | 100000_500000 | 500000_1000000 | 1000000_5000000 | OVER_5000000

Net-worth band in USD-equivalent.

Example: "100000_500000"

investmentExperienceNONE | LIMITED | MODERATE | EXPERIENCED | PROFESSIONAL

User's investing experience level.

Example: "LIMITED"

investmentObjectivesstring[]

Investment objectives captured during suitability/appropriateness checks.

Example: ["GROWTH","RETIREMENT"]

riskToleranceLOW | MEDIUM | HIGH

User-declared or assessed risk tolerance.

Example: "MEDIUM"

suitabilityStatusNOT_ASSESSED | SUITABLE | UNSUITABLE | REVIEW_REQUIRED

Suitability outcome assigned by your onboarding process.

Example: "SUITABLE"

appropriatenessStatusNOT_ASSESSED | SUITABLE | UNSUITABLE | REVIEW_REQUIRED

Appropriateness outcome for execution-only brokerage products.

Example: "SUITABLE"

assessmentReferencestring

Your suitability/appropriateness assessment reference.

Example: "suitability_88721"

usPersonboolean

FATCA US-person declaration.

Example: false

fatcaStatusNOT_US_PERSON | US_PERSON | EXEMPT | UNKNOWN

FATCA classification asserted by your onboarding flow.

Example: "NOT_US_PERSON"

crsTaxResidenciesobject[]

CRS tax residencies. Tax IDs are stored as sha256 fingerprint plus last4 only.

crsTaxResidencies[].countrystringRequired

Example: "KE"

crsTaxResidencies[].taxIdstring

Stored as fingerprint + last4 only.

Example: "A012345678Z"

crsTaxResidencies[].reasonNoTinstring

Reason no TIN was supplied, if applicable.

marketAccountReferencesobject[]

Market-specific brokerage/CSD account references. Account numbers are stored as fingerprint plus last4 only.

marketAccountReferences[].marketstringRequired

Example: "NSE"

marketAccountReferences[].brokerstring

Example: "MyStocks Securities"

marketAccountReferences[].brokerAccountNumberstring

Stored as fingerprint + last4 only.

marketAccountReferences[].csdNumberstring

Stored as fingerprint + last4 only.

Response fields

messagestring
kycStatusNONE | PENDING | VERIFIED | REJECTED
kycLevelNONE | BASIC | FULL
reasonCodestring | null
reasonstring | null
reviewedAtstring | null
profileobject

Echo of the compliance fields asserted on this call (present only when a profile was supplied). Sensitive identifiers appear as idNumberLast4 / taxIdLast4 — never in full.

Response codes

200KYC status updated.

Previous

GET /users/{userId}/gains

Next

GET /users/{userId}/orders