Verification Match Service - IdCanopy API Documentation

For a usage description of the Verification Match Service, please refer to the Verification Match page.
Endpoint

PATCH /verificationMatch/{referenceId}
Swagger

Copy Swagger
{
  "openapi": "3.1.0",
  "info": {
    "title": "Verification Match API",
    "description": "API documentation for Verification Match endpoint - validates OTP codes for verification completion",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://sandbox-umbrella-api.azurewebsites.net/api/services/",
      "description": "Sandbox Server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/verificationMatch/{referenceId}": {
      "post": {
        "summary": "Verification Match",
        "description": "The Verification Match service validates the one-time password (OTP) code that was sent to the user's phone number or email address. This endpoint is used to complete the verification process by matching the provided code against the expected value.",
        "parameters": [
          {
            "name": "referenceId",
            "in": "path",
            "required": true,
            "description": "The reference ID from the original verification request.",
            "schema": {
              "type": "string"
            },
            "example": "VER123456789ABCDEF"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VerificationMatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully validated verification code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationMatchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Malformed syntax in the request.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error400"}}}
          },
          "401": {
            "description": "Unauthorized - Authentication failed.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error401"}}}
          },
          "404": {
            "description": "Not Found - The server could not find the requested resource.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error404"}}}
          },
          "429": {
            "description": "Too Many Requests - Rate limit exceeded.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error429"}}}
          },
          "500": {
            "description": "Invalid Transaction - Transaction not attempted due to a system issue.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error500"}}}
          },
          "503": {
            "description": "Service Unavailable - System is temporarily unavailable.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error503"}}}
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "VerificationMatchRequest": {
        "type": "object",
        "required": ["code"],
        "properties": {
          "code": {
            "type": "string",
            "description": "The verification code (OTP) entered by the user.",
            "example": "123456"
          },
          "externalId": {
            "type": "string",
            "description": "A customer-generated ID for this transaction.",
            "example": "CustomExternalID5678"
          },
          "originatingIp": {
            "type": "string",
            "description": "End user's IP address (IPv4 or IPv6).",
            "example": "203.0.113.45"
          },
          "consent": {
            "type": "object",
            "description": "Consent information for the request.",
            "properties": {
              "method": {
                "type": "integer",
                "description": "Method of consent.",
                "example": 1
              },
              "timestamp": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp of consent.",
                "example": "2024-01-15T10:35:00Z"
              }
            }
          }
        }
      },
      "VerificationMatchResponse": {
        "type": "object",
        "properties": {
          "reference_id": {
            "type": "string",
            "description": "Unique reference ID for the verification transaction.",
            "example": "VER123456789ABCDEF"
          },
          "sub_resource": {
            "type": "string",
            "description": "Sub-resource type (e.g., 'match').",
            "example": "match"
          },
          "status": {
            "type": "object",
            "properties": {
              "code": {
                "type": "number",
                "description": "Status code (e.g., 300 for success).",
                "example": 300
              },
              "description": {
                "type": "string",
                "description": "Status description.",
                "example": "Verification code validated successfully"
              },
              "updatedOn": {
                "type": "string",
                "description": "Timestamp of the last update (ISO 8601 format).",
                "example": "2024/01/15T10:35:30.123456Z"
              }
            }
          },
          "errors": {
            "type": "array",
            "description": "List of errors, if any.",
            "items": {
              "type": "string"
            }
          },
          "verificationMatch": {
            "type": "object",
            "properties": {
              "matched": {
                "type": "boolean",
                "description": "Whether the verification code matched successfully.",
                "example": true
              },
              "method": {
                "type": "string",
                "description": "The verification method that was used.",
                "example": "sms"
              },
              "phoneNumber": {
                "type": "string",
                "description": "The phone number that was verified.",
                "example": "11234567890"
              },
              "email": {
                "type": "string",
                "description": "The email address that was verified (if applicable).",
                "example": "user@example.com"
              },
              "attempts": {
                "type": "integer",
                "description": "Number of verification attempts made.",
                "example": 1
              },
              "maxAttempts": {
                "type": "integer",
                "description": "Maximum number of verification attempts allowed.",
                "example": 3
              },
              "verifiedAt": {
                "type": "string",
                "format": "date-time",
                "description": "Timestamp when verification was completed.",
                "example": "2024-01-15T10:35:30Z"
              },
              "expired": {
                "type": "boolean",
                "description": "Whether the verification code had expired.",
                "example": false
              }
            }
          }
        }
      },
      "Error400": {
        "required": [
          "message"
        ],
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Invalid request payload"
          }
        }
      },
      "Error401": {
        "required": [
          "message"
        ],
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Unauthorized request"
          }
        }
      },
      "Error404": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Resource not found"
          }
        }
      },
      "Error429": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Rate limit exceeded"
          }
        }
      },
      "Error500": {
        "required": [
          "message"
        ],
        "type": "object",
        "properties": { 
          "message": {
            "type": "string",
            "example": "Internal Server Error"
          }
        }
      },
      "Error503": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Service temporarily unavailable"
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
Authorizations

Authorization
string
header
required
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters

referenceId
string
required
Unique identifier for the verification process.
Body

application/json
Response

200
application/json
Successfully validated verification code.
The response is of type object.
Endpoints
