openapi: 3.0.1
info:
  title: IdRamp Identity Verification API - Overview
  description: >-
    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.
  contact:
    name: IdRamp
    url: https://www.idramp.com
    email: info@idramp.com
  license:
    name: Contact IdRamp
    url: https://www.idramp.com
  version: '1.0'
servers:
  - url: https://idvtest.idramp.com
    description: Test server
paths:
  /api/v1/verification:
    post:
      tags:
        - Identity Verification
      summary: Start verification
      description: >-
        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`.
      requestBody:
        description: Required details to create a verification session
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartVerificationRequestDto'
            example:
              identityVerifierId: b655c3c4-cff2-4521-8835-54c696aaa24d
              returnUrl: https://idramp.com
              customFields: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartVerificationResponseDto'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKey:
            - ApiKeyPolicy
  /api/v1/verification/{identityVerifierId}/status/{verificationId}:
    get:
      tags:
        - Identity Verification
      summary: Get Status
      description: >-
        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`.
      parameters:
        - name: identityVerifierId
          in: path
          description: IdRamp Identity Verifier instance id
          required: true
          schema:
            type: string
            format: uuid
        - name: verificationId
          in: path
          description: The Id of the verification session obtained at start of session
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
                description: 'Verification session status: `started`, `completed`'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      security:
        - ApiKey:
            - ApiKeyPolicy
  /api/v1/verification/{identityVerifierId}/{verificationId}:
    get:
      tags:
        - Identity Verification
      summary: Get Result
      description: >-
        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`.
      parameters:
        - name: identityVerifierId
          in: path
          description: IdRamp Identity Verifier instance id
          required: true
          schema:
            type: string
            format: uuid
        - name: verificationId
          in: path
          description: The Id of the verification session obtained at start of session
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerificationResultDto'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKey:
            - ApiKeyPolicy
  /api/v1/verification/match:
    post:
      tags:
        - Utility API
      summary: Match Result
      description: >-
        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`.
      requestBody:
        description: JSON data in body as per Rule API specification. See example/guide.
        content:
          application/json:
            example:
              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:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvaluateResultModel'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKey:
            - ApiKeyPolicy
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: ''
          format: int32
        message:
          type: string
          description: ''
          nullable: true
        errorCode:
          type: string
          description: ''
          nullable: true
        details:
          type: string
          description: ''
          nullable: true
        timestamp:
          type: string
          description: ''
          format: date-time
        diagnosticsId:
          type: string
          description: ''
          nullable: true
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    StartVerificationRequestDto:
      required:
        - identityVerifierId
        - returnUrl
      type: object
      properties:
        identityVerifierId:
          type: string
          description: The IdRamp IdentityVerifier instance id to use for this session.
          format: uuid
        returnUrl:
          type: string
          description: >-
            If present, users will be redirected to this url upon successful
            verification.
          nullable: true
        customFields:
          type: object
          additionalProperties:
            type: string
          description: Custom fields to address client specific requirements
          nullable: true
      additionalProperties: false
      description: Request body to start a new Identity Verification session.
    StartVerificationResponseDto:
      type: object
      properties:
        id:
          type: string
          description: The Id of the verification session
          nullable: true
        status:
          type: string
          description: Current status of the verficiation session
          nullable: true
        startUrl:
          type: string
          description: Url to start a new Identity Verification session with IdV provider.
          nullable: true
      additionalProperties: false
      description: ''
    Address:
      type: object
      properties:
        line1:
          type: string
          nullable: true
        line2:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        postal_code:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
      additionalProperties: false
    Document:
      type: object
      properties:
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
      additionalProperties: false
    Traits:
      type: object
      properties:
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        document:
          $ref: '#/components/schemas/Document'
      additionalProperties: false
    VerificationResultDto:
      type: object
      properties:
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        user_id:
          type: string
          description: Unique identifier of the user from associated IdV provider
          nullable: true
        status:
          type: string
          description: >-
            The statuses the verification can be in. `success`,
            `fail`,`canceled`
          nullable: true
        traits:
          $ref: '#/components/schemas/Traits'
      additionalProperties: false
    EvaluateResultModel:
      type: object
      properties:
        isMatch:
          type: boolean
          description: Overall result of the Rule evaluation.
        fullResult:
          $ref: '#/components/schemas/RuleResult'
        namedResults:
          type: array
          description: Result of individual rule evaluation - flattened.
          items:
            $ref: '#/components/schemas/RuleResult'
          nullable: true
      additionalProperties: false
    RuleResult:
      type: object
      properties:
        name:
          type: string
          description: Name identifier of the evaluated rule
          nullable: true
        rule:
          type: string
          description: The type of rule evaluated. e.g. equal, contain, etc.
          nullable: true
        isMatch:
          type: boolean
          description: Status of the rule evaluation - true or false
        results:
          type: array
          description: Details of rule evaluation.
          items:
            $ref: '#/components/schemas/RuleResult'
          nullable: true
        cause:
          type: string
          description: Failure cause, if status is false.
          nullable: true
      additionalProperties: {}
  securitySchemes:
    ApiKey:
      type: apiKey
      name: x-api-key
      in: header
