Skip to content
/Utility API

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

Utility API

Operations

Match Result

Request

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

JSON data in body as per Rule API specification. See example/guide.

curl -i -X POST \
  https://idvtest.idramp.com/api/v1/verification/match \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "data": {
      "sourceRecord": {
        "firstName": "John",
        "lastName": "Doe",
        "fullName": "Johnathan Doe"
      },
      "targetRecord": {
        "given_name": "Johnathan",
        "surname": "Doe",
        "displayName": "Jon Doe"
      }
    },
    "rule": {
      "rule": "and",
      "name": "Rule",
      "rules": [
        {
          "rule": "or",
          "name": "firstOrLast",
          "rules": [
            {
              "rule": "equal",
              "name": "first",
              "left": {
                "expr": "prop",
                "name": "sourceRecord.firstName"
              },
              "right": {
                "expr": "prop",
                "name": "targetRecord.given_name"
              }
            },
            {
              "rule": "equal",
              "name": "last",
              "left": {
                "expr": "prop",
                "name": "sourceRecord.lastName"
              },
              "right": {
                "expr": "prop",
                "name": "targetRecord.surname"
              }
            }
          ]
        },
        {
          "rule": "lev-ratio",
          "name": "full",
          "left": {
            "expr": "join",
            "values": [
              {
                "expr": "prop",
                "name": "sourceRecord.firstName"
              },
              {
                "expr": "prop",
                "name": "sourceRecord.lastName"
              }
            ],
            "separator": " "
          },
          "right": {
            "expr": "join",
            "values": [
              {
                "expr": "prop",
                "name": "targetRecord.given_name"
              },
              {
                "expr": "prop",
                "name": "targetRecord.surname"
              }
            ],
            "separator": " "
          },
          "threshold": 80
        }
      ]
    }
  }'

Responses

OK

Bodyapplication/json
isMatchboolean

Overall result of the Rule evaluation.

fullResultobject(RuleResult)
namedResultsArray of objects or null(RuleResult)

Result of individual rule evaluation - flattened.

Response
application/json
{
  "isMatch": true,
  "fullResult": {
    "name": "string",
    "rule": "string",
    "isMatch": true,
    "results": [ … ],
    "cause": "string",
    "property1": null,
    "property2": null
  },
  "namedResults": [
    { … }
  ]
}