Skip to main content
Version: Latest (3.102.4)

Initiate Account Verification

POST 
/verification-actions-srv/account/initiation

This API initiates the account verification process for communication mediums (email or mobile number). It sends a verification code or link to the user's email or mobile number.

Use Case:

  • Initiate verification when user is prompted during the communication_medium_verification precheck
  • Send verification code or link to user's email or mobile number
  • Required before validating the verification code

Processing Types:

  • CODE: Sends a verification code that the user must enter manually
  • LINK: Sends a verification link that the user clicks to verify

Verification Mediums:

  • email: Verify user's email address
  • sms: Verify user's mobile number
  • ivr: Verify via Interactive Voice Response (phone call)

Request Body:

  • Required: requestId, processingType
  • Either provide a user identifier (exactly one: masked sub q, email, mobile, or username), or provide trackId (no identifier needed—the user is resolved from the track context of the flow that requires verification before a token is issued).
  • When trackId is present, the API validates that the incoming identifier and the authenticated sub match.
  • Optional: verificationMedium (defaults to email if omitted)

Authentication:

  • Public endpoint; requestId is provided in the request body

Request​

Responses​

Redirect to the verification_complete hosted page. This redirect occurs for both CODE and LINK processing types.

Success Redirect URL: /identity/verification_complete

Success Query Parameters:

  • accvid (string, CODE only): Account verification ID to be used in the validate endpoint
  • email (string): Masked email address (not masked if email was provided in request)
  • mobile (string): Masked mobile number (not masked if mobile was provided in request)
  • processingType (string): The processing type used (CODE or LINK)
  • requestId (string): The request ID from the authorization request
  • track_id (string): Track ID of the flow
  • type (string): The verification type (email, sms, or ivr)

Error Redirect URL: /identity/error

Error Query Parameters:

  • error (string): Error type (e.g., "Expectation Failed", "Internal Server Error")
  • error_code (string): Error code (e.g., "VER_0005", "VER_0105")
  • error_description (string): Error description (e.g., "requestId or token is missing", "missing required field: Email or Mobile or Phone or Username or q", "error while processing request")
Response Headers
    Location

    Redirect URL. Either success (verification_complete hosted page) or error (error hosted page). Use the oneOf examples below to switch between success and error cases for a clear overview.