Onboarding (KYC)

Opening an account is a KYC flow that ends with the broker approving the application and the platform minting an investor_id. Until then, no money can move.

Flow

1. Create an application with the applicant's details.
2. Upload both national-ID photos (front and back).
3. Submit — this routes the application to the broker's review queue.
4. The brokerage reviews the ID images (audited) and clears or declines.
5. On approval, the application carries an investor_id. Record suitability answers and the risk acknowledgment before trading.

# 1. Create
curl -X POST https://sandbox.boursa.sh/v1/kyc/applications \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"full_name":"…","national_id":"29001011234567","date_of_birth":"1990-01-01",
       "email":"…","phone":"01…","address":"…"}'
# → {"application_id":"kyc_…","state":"screened"}

# 2. Upload each side (raw JPEG/PNG body, ≤512 KiB, sealed under the tenant key)
curl -X PUT https://sandbox.boursa.sh/v1/kyc/applications/kyc_…/documents/national_id_front \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @front.jpg

# 3. Submit → routes to broker review when both sides are on file
curl -X POST https://sandbox.boursa.sh/v1/kyc/applications/kyc_…/submit \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)"
# → {"state":"screening_referred"}  (the broker now reviews)

# 4. Poll status; after the broker clears, the app resubmits automatically
curl https://sandbox.boursa.sh/v1/kyc/applications/kyc_… -H "Authorization: Bearer $KEY"
# → {"state":"approved","investor_id":"inv_…",…}

States

received → screened → screening_referred → approved | rejected. A submission with both ID sides routes to broker review (screening_referred). A dossier-only submission (no documents) keeps the direct path — for integrators with their own verified capture.

Suitability

After approval, record suitability and risk acknowledgment (a regulatory gate):

curl -X PUT https://sandbox.boursa.sh/v1/investors/inv_…/suitability \
  -H "Authorization: Bearer $KEY" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"questionnaire":{…},"risk_acknowledged":true}'

Sandbox magic values

• national_id ending 0000 → the broker rejects the application.
• national_id ending 9999 → screening referral (clear it from the dealer console).