API product catalogSub-Accounts & White-Label Retail KYC

Register notification device

Sub-Accounts & White-Label Retail KYC

POST

/users/{userId}/devices

Sandbox availableregisterUserDevice

Registers or updates a push-token record for your mobile/web app. MyStocks stores only a token hash and last4. This endpoint gives partners a durable device-token model for mobile notification fanout. Webhooks remain the server-side event source of truth; your backend should receive webhooks or SSE events and fan out user-visible notifications through APNs, FCM, Expo, or Web Push using the device records you maintain.

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

tokenstringRequired

Mobile/web push token from APNs, FCM, Expo, or Web Push. Stored as sha256 hash plus last4 only.

Example: "ExpoPushToken[xxxxxxxxxxxxxxxxxxxxxx]"

platformios | android | webRequired

Example: "ios"

providerfcm | apns | expo | webpushRequired

Example: "expo"

appIdstring

Partner app bundle/package ID.

Example: "com.afritrade.app"

deviceIdstring

Optional partner device identifier. Used to keep one stable MyStocks deviceId across token rotations.

Example: "afritrade-device-42"

localestring

Example: "en-KE"

timezonestring

Example: "Africa/Nairobi"

tagsstring[]

Example: ["retail","beta"]

enabledboolean

Response fields

See the response format and API Reference for this endpoint.

Response codes

200Existing device registration updated.

201Device registered.

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/devices

Open in API Tester API Reference

Response format

Existing device registration updated.

curl -X POST 'https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/devices' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "token": "ExpoPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "platform": "ios",
  "provider": "expo",
  "appId": "com.afritrade.app",
  "deviceId": "qa-device-001",
  "locale": "en-KE",
  "timezone": "Africa/Nairobi"
}'

GET /users/{userId}/devices

DELETE /users/{userId}/devices/{deviceId}