Validate email - StarkFi Documentation

After Prepare, the user must prove they own the email before StarkFi allows a KYC session. This phase uses two calls: send OTP and verify OTP.

Always call POST /kyc/prepare for that email first. If the address is not registered for KYC, send OTP returns 404 user_not_found.

1. Send verification code

POST /security/email/send-otp

Request

Field	Type	Required	Description
`email`	string	Yes	Same address used in prepare. The service normalizes to lowercase for lookup.

Example

curl --request POST \
  --url https://api.starkfi.io/security/email/send-otp \
  --header 'Content-Type: application/json' \
  --data '{"email":"user@example.com"}'

Responses (send OTP)

201 — code sent

{
  "statusCode": 201,
  "success": true,
  "status": "otp_sent",
  "message": "Verification code sent to your email"
}

400 — missing email status: missing_params — "email is required" 400 — already verified status: email_already_verified — "Email is already verified" 404 — not registered for KYC status: user_not_found — "User not found in whitelist" 500 — server error status: server_error — "Server failed, try again later"

2. Confirm the code

POST /security/email/verify-otp

Request

POST /security/email/verify-otp
Content-Type: application/json

Field	Type	Required	Description
`email`	string	Yes	Same email as send OTP.
`code`	string	Yes	One-time code from the user’s inbox.

Example

curl --request POST \
  --url https://api.starkfi.io/security/email/verify-otp \
  --header 'Content-Type: application/json' \
  --data '{"email":"user@example.com","code":"123456"}'

Responses (verify OTP)

200 — verified

{
  "statusCode": 200,
  "success": true,
  "status": "email_verified",
  "message": "Email verified successfully"
}

After this response, you can start the Didit session with POST /kyc/create/verify_public_kyc. 400 — missing fields status: missing_params — "email and code are required" 400 — invalid or unusable code status is one of: otp_invalid, otp_expired, otp_max_attempts
Human-readable message, for example:

Invalid code
Code expired, please request a new one
Max attempts reached, please request a new code

400 — already verified status: email_already_verified 404 — not registered status: user_not_found 500 — server error status: server_error

Flow in your product

User requests a code

Call send-otp after prepare. Show a “check your inbox” state; do not log the OTP in client analytics.

User enters the code

Call verify-otp with email + code. On success, move to the KYC session step.

Retries

If you receive otp_expired or otp_max_attempts, call send-otp again to issue a fresh code (subject to your product rules and abuse limits).

Email subject and template are controlled by StarkFi. If deliverability is an issue, work with StarkFi support for domain and inbox guidance.

Previous: Prepare
Overview: Getting started
Next: start KYC session — POST /kyc/create/verify_public_kyc (dedicated guide can follow)

​1. Send verification code

​Request

​Example

​Responses (send OTP)

​2. Confirm the code

​Request

​Example

​Responses (verify OTP)

​Flow in your product

​Related

1. Send verification code

Request

Example

Responses (send OTP)

2. Confirm the code

Request

Example

Responses (verify OTP)

Flow in your product

Related