Usage

Generate a verification link

1. Configure the application

Create or expand an application, then set the fields below. Save after changing callback, redirect, or bundle settings.

• Application ID: Public Ethereum address for the application. /api/link recovers this from the signature, so you do not pass it directly.
• Application secret: Private key used to sign requests. Keep it on your server. It is shown only once, right after the application is created, and cannot be retrieved later.
• Verification type: Verification category for generated links: education, employment, alumni, or identity.
• Callback URL: Your server endpoint for proof results. It receives requestId, applicationId, bundleType, country, institution, data, proof, and context; failures may include error.
• Redirect URL: Where the user returns after the flow. We append success=true|false, requestId, and applicationId.
• Session start callback URL (optional): We POST requestId, applicationId, reclaimSessionId, and status: started when the verification session begins, so you can track in-progress sessions.
• Credits: One credit equals one completed verification. Buy credits before sending production traffic.

2. Sign the request

Sign the request before creating a link. This proves the request came from your application and prevents anyone else from spending your application credits.

• requestId: Your unique id for this verification request. Use a stable id from your system so retries map to the same business event.
• userEmail: Email address of the person being verified. Completed proofs are saved to this user's wallet.
• applicationSecret: Private key from the expanded accordion. Keep it server-side and never expose it to browsers or mobile apps.

const baseUrl = "https://verify.reclaimprotocol.org";
const privateKey = "<YOUR APPLICATION SECRET HERE>";
const requestId = "request_123";
const userEmail = "user@example.com";
 
const signResponse = await fetch(`${baseUrl}/api/sign`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ privateKey, requestId, userEmail }),
});
 
const { signature } = await signResponse.json();
console.log(signature);

For additional security, you can also sign the request yourself using a crypto library.

import { Wallet } from "ethers";
 
const wallet = new Wallet("<YOUR APPLICATION SECRET HERE>");
const message = "requestId=request_123&userEmail=user@example.com";
const signature = await wallet.signMessage(message);

3. Generate verification link

Create the verification session and link with /api/link. The request must match the values you signed in step 2.

• requestId: Same id signed in step 2. Use it to reconcile the verification with your own system.
• userEmail: Same user email signed in step 2. This is the wallet owner for the saved proof.
• signature: Signature returned by /api/sign, or generated by your own crypto library.
• context (optional): Any JSON value of your own. It is not signed; we store it and echo it back verbatim in the callback as context.
• verificationUrl: Returned as request.verificationUrl. Send this URL to the user.
• Link lifetime: Each link is single-use and expires 24 hours after creation. Once a verification completes it is closed; expired or completed links cannot be reused. Generate a new one per request.

const baseUrl = "https://verify.reclaimprotocol.org";
const requestId = "request_123";
const userEmail = "user@example.com";
const signature = "<SIGNATURE FROM /api/sign>";
const context = { tier: "premium" }; // optional, echoed back verbatim
 
const linkResponse = await fetch(`${baseUrl}/api/link`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ requestId, userEmail, signature, context }),
});
 
const { request } = await linkResponse.json();
console.log(request.verificationUrl);

4. Redirect user to verification link

Send or redirect the user to request.verificationUrl. The platform handles the proof flow and returns the outcome to your app.

• User destination: Open request.verificationUrl in the user's browser or send it by email/SMS.
• Callback: Your callback URL receives requestId, applicationId, bundleType, country, institution, data, proof, and context. Use requestId to reconcile the result with your own system. It is sent once on completion. There is no retry, so respond 2xx quickly, persist the payload immediately, and dedupe on requestId in case of duplicate delivery.
• data: The fields the agent extracted. The exact keys depend on the provider/portal and what could be read. Employment usually includes employeeName and companyName, plus best-effort extras. Run one verification and inspect a sample callback to see the shape for your provider.
• Final redirect: The user lands on your redirect URL with success=true|false, requestId, and applicationId. These query params are visible and editable in the user's browser. Use the redirect only as a UX signal, never to mark a verification complete or grant access. The callback is the source of truth.