✨Works out of the box guarantee. If you face any issue at all, hit us up on Telegram and we will write the integration for you.
logoReclaim Protocol Docs

Anatomy of messages

Datastructures of messages transmitted during the verification process

Proof Request

{
    // This can be your application id
    "applicationId": "0xsampleapplicationid",
    // The ID of Provider you are using for verifications
    "providerId": "example",
    // A unique short sessionId created by Reclaim Protocol to identify this session
    "sessionId": "123",
    // Any JSON serializable data you want to be part of the proof generation process
    "context": {
      "user": "john@example.com",
      "contextAddress":"Address you set",
      "contextMessage":"message you set"
    },
    // URL where proof(s) are submitted after all proofs are successfully generated
    "appCallbackUrl": "https://api.example.com/success?session=def",
    // The type of claim creation
    "claimCreationType": "createClaim",
    // The parameters used by the provider script and the requests involved in proof generation process
    // This is a map of strings to strings.
    "parameters": {
        "user": "john@example.com"
    },
    // Signature of the proof request using your application secret
    // This signature is generated using your application secret to know it came from your application
    "signature": "0xbbf1aad7bd65c6d0c37a5b6012c4dff217e190372d5e364bf8f2bf4ea9df3a080ec8b325b84b29e130d9b15401087b36bc4852367c8f93427c39ffb7b44b498d1c",
    // URL to redirect to after successful proof generation
    "redirectUrl": "https://example.com/success?session=def",
    // Optional. Only applicable when `redirectUrl` is provided.
    "redirectUrlOptions": {
        // `POST` method only supported on In-Browser SDK.
        // Allowed values: GET, POST. Optional. Default is GET.
        "method": "POST",
        // An array of objects with `name` (string) and `value` (string) fields for form submission.
        // `body` is only supported on In-Browser SDK.
        // Optional. Only applicable when `method` is `POST`.
        "body": [
            {
                "name": "username",
                "value": "john"
            },
            {
                "name": "student",
                "value": "true"
            }
        ]
    },
    // URL which is called when verification is cancelled by the user or after errors (only auto submit enabled; auto submit is enabled by default).
    "cancelCallbackUrl": "https://api.example.com/cancel?session=def",
    // URL to redirect to after cancelled proof generation
    "cancelRedirectUrl": "https://example.com/cancelled?session=def",
    // Optional. Only applicable when `cancelCallbackUrl` is provided.
    "cancelRedirectUrlOptions": {
        // `POST` method only supported on In-Browser SDK.
        // Allowed values: GET, POST. Optional. Default is GET.
        "method": "POST",
        // An array of objects with `name` (string) and `value` (string) fields for form submission.
        // `body` is only supported on In-Browser SDK.
        // Optional. Only applicable when `method` is `POST`.
        "body": [
            {
                "name": "username",
                "value": "john"
            },
            {
                "name": "student",
                "value": "true"
            }
        ]
    },
    // Timestamp of the proof request
    "timestamp": "1769867597546",
    // legacy: same as above
    "timeStamp": "1769867597546",
    "options": {
        // enables diagnostic logging for debugging purposes
        "log": true,
        // enables use of AI in verification journey
        "acceptAiProviders": false,
        // users may use Reclaim Verifier app clip or instant app for verification
        "useAppClip": false,
        // URL of the custom share page (optional)
        "customSharePageUrl": "https://portal.reclaimprotocol.org",
        "launchOptions": {
            // enables deferred deep links flow
            "canUseDeferredDeepLinksFlow": true
        },
        // Enables auto submitting proofs on success or errors
        "canAutoSubmit": false,
        // Preferred locale for the UI in verification journey
        "preferredLocale": "zh-Hant-HK",
        // Metadata that can be used by the UI in verification journey
        "metadata": {
            // This is an example of metadata, actual values may depend on custom themes
            "theme": "dark"
        },
        // Enables use of browser extension for verification
        "useBrowserExtension": true
    },
    // The version of SDK that generated this JSON string request
    "sdkVersion": "js-4.11.0",
    // Whether to submit proof as JSON or URL encoded using HTTP POST to the success callback. Cancellation callback not affected.
    "jsonProofResponse": false,
    // The version of provider that should be used for verifications
    "resolvedProviderVersion": "1.0.0"
}

Proof

[ // note this is an array
  {
    "identifier": "0x7059eb0d834e4e0b544f683ef083081fa7dc7f51b847b5ccb67c5b63a7e8b605",
    "claimData": {
      "provider": "http",
      "parameters": "",
      "owner": "0x1234567890123456789012345678901234567890", //Legacy. Ignore.
      "timestampS": 1769800037,
      // THIS IS WHAT YOU CARE ABOUT
      // "extractedParameters" will contain the data. Can be extracted from this field using `JSON.parse(proof[index].claimData.context).extractedParameters`.
      "context": "{\"contextAddress\":\"Your set address\",\"contextMessage\":\"Your context message\",\"extractedParameters\":{\"KEY\":\"Value\"}}",
      "identifier": "0x7059eb0d834e4e0b544f683ef083081fa7dc7f51b847b5ccb67c5b63a7e8b605",
      "epoch": 1
    },
    "signatures": [
      "0xc014ac88a17b1fb95ca8cb51b1bbefc02efb79d741f1b83fe011eac8dadc703722d409674a76c5bc0d51d835cf2b52db8bef22e1df69a4feecb0da9d1ab160e71b"
    ],
    "witnesses": [
      {
        "id": "0x1be31a94361a391bbafb2a4ccd704f57dc04d4bb",
        "url": "reclaimprotocol"
      }
    ],
    // Optional: Extra data attached to any proof. This can be null, JSON string, array or map. In most cases, this is a JSON map or null.
    "publicData": {
      "KEY":"VALUE"
    }
  }
]

Structure of data POSTed to cancel callback

{
  "type": "string",
  "message": "string",
  [key: any]: any
}
Exception NameDescription
ReclaimVerificationCancelledExceptionVerification cancelled (likely another verification started or invalid request).
ReclaimVerificationDismissedExceptionVerification dismissed by user.
ReclaimAttestorExceptionException related to attestor.
ReclaimVerificationSkippedExceptionVerification skipped (proofs reused or manual review).
InvalidRequestReclaimExceptionRequest to start verification is invalid.
ReclaimVerificationPlatformNotSupportedExceptionPlatform not supported.
ReclaimVerificationOutdatedSDKExceptionInApp SDK version is outdated.
ReclaimVerificationManualReviewExceptionVerification submitted for manual review.
ReclaimVerificationProviderNotFoundExceptionProvider not found.
ReclaimVerificationAbortedExceptionVerification aborted by user (e.g. clicking cancel).
ReclaimVerificationProviderScriptExceptionProvider script reported an error.
ReclaimVerificationNoActivityDetectedExceptionNo activity detected.
ReclaimVerificationRequirementExceptionClaim creation requirements not met.
ReclaimVerificationProviderLoadExceptionProvider load failed.
ReclaimExpiredSessionExceptionSession expired.
ReclaimInitSessionExceptionError initializing session.

Description of RECLAIM_EXCEPTION in metadata

When the logType is RECLAIM_EXCEPTION, the metadata string parses to an object containing an exception field. The exception.type will be one of the following:

[!NOTE] In case of ReclaimVerificationProviderScriptException, the metadata may contain an additional providerError field with more detailed error information from the provider script. In case of ReclaimVerificationAbortedException, the metadata may contain an additional has_error boolean field which will be true if the user cancelled the verification after an error occurred during verification.

You can see some common reasons of failures here

On this page