# Identity Verification

## Start verification

 - [POST /api/v1/verification](https://apidocs.idramp.com/apis/idramp-idv/identity-verification/paths/~1api~1v1~1verification/post.md): Starts a new identity verification session using the specified IdRamp Identity Verifier instance.

How it works
- Provide the identityVerifierId for the IdV configuration you want to use.
- Provide a returnUrl. If verification succeeds, the user is redirected to this URL.
- customFields can carry additional key–value metadata required by your client workflow.

Successful response (200)
- Returns StartVerificationResponseDto with:
  - id: the server-generated verification session identifier.
  - status: the current session status.
  - startUrl: a URL your client/app can open to begin the provider’s verification flow.

Errors
- 401/403: missing or invalid API key, or insufficient policy.
- 422: request body failed validation (see ErrorResponse).

Auth
- Requires x-api-key with the ApiKeyPolicy.

## Get Status

 - [GET /api/v1/verification/{identityVerifierId}/status/{verificationId}](https://apidocs.idramp.com/apis/idramp-idv/identity-verification/paths/~1api~1v1~1verification~1%7Bidentityverifierid%7D~1status~1%7Bverificationid%7D/get.md): Returns the lightweight status of a verification session, suitable for polling.

Path parameters
- identityVerifierId (UUID): IdRamp Identity Verifier instance ID used to start the session.
- verificationId (string): The session ID returned by the start call.

Successful response (200)
- Plain string status: started or completed.

When to use
- Use this endpoint to check whether the session has finished without fetching the full result payload.

Errors
- 400/422: invalid parameter format (see ProblemDetails).
- 401/403: authentication/authorization failure.
- 404: session not found for the given IDs.

Auth
- Requires x-api-key with the ApiKeyPolicy.

## Get Result

 - [GET /api/v1/verification/{identityVerifierId}/{verificationId}](https://apidocs.idramp.com/apis/idramp-idv/identity-verification/paths/~1api~1v1~1verification~1%7Bidentityverifierid%7D~1%7Bverificationid%7D/get.md): Retrieves the verification outcome and captured traits for a completed session.

Path parameters
- identityVerifierId (UUID): IdRamp Identity Verifier instance ID used to start the session.
- verificationId (string): The session ID returned by the start call.

Successful response (200)
- Returns VerificationResultDto, including:
  - status: one of success, fail, or canceled.
  - user_id: the provider’s unique user identifier (if available).
  - email, phone: top-level contact values, when present.
  - traits: structured attributes (e.g., first_name, last_name, nested document).

Notes
- Call after status indicates completion to obtain final details.
- Field presence varies by provider and configuration.

Errors
- 401/403: authentication/authorization failure.
- 422: parameter formatting or validation error (see ErrorResponse).

Auth
- Requires x-api-key with the ApiKeyPolicy.