Skip to content
API Reference/
/
Start verification

IdRamp Identity Verification API - Overview (1.0)

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.
Download OpenAPI description
idramp-idv.json
idramp-idv.yaml
Overview
URL

https://www.idramp.com

IdRamp

info@idramp.com

License

Contact IdRamp

Languages
Servers
Test server

https://idvtest.idramp.com/

Identity Verification

Operations

Start verification

Request

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.
Security
ApiKey
Bodyapplication/json

Required details to create a verification session

identityVerifierIdstring(uuid)required

The IdRamp IdentityVerifier instance id to use for this session.

returnUrlstring or nullrequired

If present, users will be redirected to this url upon successful verification.

customFieldsobject or null

Custom fields to address client specific requirements

curl -i -X POST \
  https://idvtest.idramp.com/api/v1/verification \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "identityVerifierId": "b655c3c4-cff2-4521-8835-54c696aaa24d",
    "returnUrl": "https://idramp.com",
    "customFields": {}
  }'

Responses

OK

Bodyapplication/json
idstring or null

The Id of the verification session

statusstring or null

Current status of the verficiation session

startUrlstring or null

Url to start a new Identity Verification session with IdV provider.

Response
application/json
{
  "id": "string",
  "status": "string",
  "startUrl": "string"
}

Get Status

Request

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.
Security
ApiKey
Path
identityVerifierIdstring(uuid)required

IdRamp Identity Verifier instance id

verificationIdstringrequired

The Id of the verification session obtained at start of session

curl -i -X GET \
  'https://idvtest.idramp.com/api/v1/verification/{identityVerifierId}/status/{verificationId}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
string

Verification session status: started, completed

Response
application/json
"string"

Get Result

Request

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.
Security
ApiKey
Path
identityVerifierIdstring(uuid)required

IdRamp Identity Verifier instance id

verificationIdstringrequired

The Id of the verification session obtained at start of session

curl -i -X GET \
  'https://idvtest.idramp.com/api/v1/verification/{identityVerifierId}/{verificationId}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
emailstring or null
phonestring or null
user_idstring or null

Unique identifier of the user from associated IdV provider

statusstring or null

The statuses the verification can be in. success, fail,canceled

traitsobject(Traits)
Response
application/json
{
  "email": "string",
  "phone": "string",
  "user_id": "string",
  "status": "string",
  "traits": {
    "first_name": "string",
    "last_name": "string",
    "email": "string",
    "phone": "string",
    "document": { … }
  }
}

Utility API

Operations