Verification Requests

Create verification request

Create a multi-asset verification request.

post/api/v1/verification-requests

Request

  • Base URL: https://api.proof.holdings
  • URL: https://api.proof.holdings/api/v1/verification-requests
  • Auth: HTTP bearer

Request body

reference_idstring

Your reference ID for this request

public_profile_idstring

Public profile ID for branding

action_type'verification' | '2fa' | 'login' | 'custom' | 'confirmation' | 'authorization'

Type of action for verification request or authorization

validity_requirementstring

Required proof freshness (e.g., "7d", "24h")

partial_okboolean

Complete even if only some assets verified

redirect_urlstring uri

HTTPS URL to redirect after completion. Must be a public HTTPS URL (no localhost, internal IPs, or private networks).

callback_urlstring uri

HTTPS URL for webhook notifications. Must be a public HTTPS URL (no localhost, internal IPs, or private networks).

expires_ininteger

Time until expiry in seconds (max 30 days)

proof_expiry_daysinteger

Per-request proof expiry override in days (1-365). Overrides account default.

Example request

{
  "reference_id": "order_12345",
  "public_profile_id": "507f1f77bcf86cd799439011",
  "assets": [
    {
      "type": "phone",
      "identifier": "+37069199199",
      "channel": "whatsapp",
      "allowed_channels": [
        "whatsapp",
        "telegram"
      ]
    }
  ],
  "action_type": "verification",
  "action_context": {
    "title": "Approve wire transfer",
    "amount": 15000,
    "currency": "USD",
    "entity": "production-cluster"
  },
  "validity_requirement": "7d",
  "redirect_url": "https://yourapp.com/callback",
  "callback_url": "https://yourapp.com/webhook",
  "expires_in": 604800,
  "proof_expiry_days": 90
}

Response

Verification request created

idstring required

MongoDB ObjectId

reference_idstring
status'pending' | 'partial' | 'completed' | 'expired' | 'cancelled' required

Status of a verification request

action_type'verification' | '2fa' | 'login' | 'custom' | 'confirmation' | 'authorization' required

Type of action for verification request or authorization

partial_okboolean required
validity_requirementstring nullable

Required proof freshness as set on the request (e.g. "7d"); null when none was set

verification_urlstring

URL for the verification flow

redirect_urlstring nullable
callback_urlstring nullable

The webhook URL set on the request, if any

expires_atstring date-time required
completed_atstring date-time
created_atstring date-time required
updated_atstring date-time

Example response

{
  "id": "507f1f77bcf86cd799439011",
  "status": "pending",
  "computed_state": {
    "status": "pending"
  },
  "assets": [
    {
      "type": "phone",
      "allowed_channels": [
        "telegram",
        "whatsapp"
      ],
      "status": "pending",
      "verified_identifier": "+37069199199",
      "verified_channel": "telegram"
    }
  ],
  "action_type": "verification",
  "action_context": {
    "title": "Approve wire transfer",
    "amount": 15000,
    "currency": "USD",
    "entity": "production-cluster"
  },
  "validity_requirement": "7d",
  "verification_url": "https://proof.holdings/verify/abc123"
}

Changes

No recorded changes to this operation across all 1 revision of this API.