# IdRamp Identity Verification API - Overview

The IdRamp Identity Verification API enables applications to initiate, monitor, and retrieve identity verification sessions using trusted verification providers integrated with IdRamp. It also includes a flexible rules-based matching utility for comparing and validating identity data.

### Key Capabilities

- **Start Verification** (`POST /api/v1/verification`): Create a new verification session for a user, specifying the IdRamp Identity Verifier configuration to use. Returns a session identifier and a provider URL where the verification flow begins.

- **Get Verification Status** (`GET /api/v1/verification/{identityVerifierId}/status/{verificationId}`): Retrieve the current state of a verification session (`started`, `completed`). Useful for polling the session progress without fetching detailed results.

- **Get Verification Result** (`GET /api/v1/verification/{identityVerifierId}/{verificationId}`): Fetch the full verification outcome once a session completes, including status (`success`, `fail`, `canceled`), provider user ID, and verified user traits such as name, email, phone, and document information.

- **Match Utility** (`POST /api/v1/verification/match`): Evaluate custom rules to compare and match data across two records (e.g., source vs. target). Supports logical and fuzzy matching (e.g., equality, Levenshtein ratio) with detailed per-rule results.

### Authentication

All endpoints require an API key sent in the request header:

```
x-api-key: YOUR_API_KEY
```

### Typical Flow

1. Client calls **Start Verification** to create a session and obtain the provider launch URL.
2. End-user completes verification via the provider interface.
3. Client waits for user to be redirected back to `returnUrl` specified at Start signalling completion. Alternatively, the Client polls **Get Status** until completion.
4. Once completed, client calls **Get Result** to retrieve verified attributes.
5. Optionally, client uses **Match Utility** to compare verified data with existing records.

Version: 1.0
License: Contact IdRamp

## Servers

Test server
```
https://idvtest.idramp.com
```

## Security

### ApiKey

Type: apiKey
In: header
Name: x-api-key

## Download OpenAPI description

[IdRamp Identity Verification API - Overview](https://apidocs.idramp.com/_bundle/apis/idramp-idv.yaml)

## 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.

## Utility API

### Match Result

 - [POST /api/v1/verification/match](https://apidocs.idramp.com/apis/idramp-idv/utility-api/paths/~1api~1v1~1verification~1match/post.md): Evaluates a ruleset against two records (e.g., “source” vs “target”) and returns a boolean match along with detailed rule outcomes.

Request
- Provide a JSON body with:
  - data: arbitrary objects such as sourceRecord and targetRecord holding fields to compare.
  - rule: a tree of evaluation rules (e.g., and, or, equal, lev-ratio) referencing fields via simple expressions.
- See the example for composing nested rules and thresholds (e.g., Levenshtein ratio with threshold).

Successful response (200)
- Returns EvaluateResultModel:
  - isMatch: overall boolean result of the ruleset.
  - fullResult: hierarchical RuleResult tree with match outcomes and causes.
  - namedResults: flattened list of RuleResult items for named rules.

Use cases
- Name normalization and fuzzy matching (e.g., lev-ratio across concatenated name parts).
- Combining exact comparisons (equal) with fallback logic (or) inside higher-level and conditions.

Errors
- 401/403: authentication/authorization failure.
- 422: invalid body or rule specification (see ErrorResponse).

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