API product catalogSub-Accounts & White-Label Retail KYC

Add symbol to watchlist

Sub-Accounts & White-Label Retail KYC

POST

/users/{userId}/watchlist

Sandbox availableaddToWatchlist

Adds a stock to a sub-account's watchlist. The symbol is resolved to its canonical exchange-qualified form (e.g. "SCOM" → "SCOM.KE"). Returns 409 if already present.

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

symbolstringRequired

Ticker symbol (exchange-qualified preferred, e.g. SCOM.KE).

Example: "SCOM.KE"

Response fields

assetIdstring

symbolstring

namestring

exchangestring

addedAtstring

metaobject

Standard response metadata included on every market-data envelope.

meta.request_idstring

Unique identifier for this request. Include in support tickets for tracing.

Example: "4f6e1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b"

meta.timestampstring

ISO 8601 UTC timestamp of when the response was generated.

Example: "2026-06-04T10:23:45.123Z"

meta.exchangestring | null

Exchange code the request was scoped to, when applicable.

Example: "NSE"

meta.symbolstring | null

Ticker symbol the request was scoped to, when applicable.

Example: "SCOM.KE"

Response codes

201Symbol added to watchlist.

409Symbol already on watchlist.

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

Open in API Tester API Reference

Response schema

{
  "type": "object",
  "properties": {
    "assetId": {
      "type": "string"
    },
    "symbol": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "exchange": {
      "type": "string"
    },
    "addedAt": {
      "type": "string",
      "format": "date-time"
    },
    "meta": {
      "type": "object",
      "description": "Standard response metadata included on every market-data envelope.",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid",
          "description": "Unique identifier for this request. Include in support tickets for tracing.",
          "example": "4f6e1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b"
        },
        "timestamp": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 UTC timestamp of when the response was generated.",
          "example": "2026-06-04T10:23:45.123Z"
        },
        "exchange": {
          "type": [
            "string",
            "null"
          ],
          "description": "Exchange code the request was scoped to, when applicable.",
          "example": "NSE"
        },
        "symbol": {
          "type": [
            "string",
            "null"
          ],
          "description": "Ticker symbol the request was scoped to, when applicable.",
          "example": "SCOM.KE"
        }
      }
    }
  }
}

curl -X POST 'https://mystocks.africa/api/sandbox/v1/partner/users/%7BuserId%7D/watchlist' \
  -H "Authorization: Bearer $MYSTOCKS_SANDBOX_API_KEY" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "symbol": "SCOM.KE"
}'

GET /users/{userId}/watchlist

DELETE /users/{userId}/watchlist/{symbol}