Verifications

Create verification

Start a new verification challenge for an asset.

The challenge object withholds the completion material for the pairs whose code we deliver out-of-band — type: email, and type: domain with channel: email. For those the code and the magic link are absent by design: the delivery to the address IS what the proof rests on, so a caller holding the code would prove nothing by submitting it back. Every other pair keeps its code, because the caller has to relay it (phone) or publish it (the TXT record or well-known file for a domain).

post/api/v1/verifications

Request

  • Base URL: https://api.proof.holdings
  • URL: https://api.proof.holdings/api/v1/verifications
  • Auth: HTTP bearer

Request body

profile_idstring

The sub-account (project) this is for; its branding and templates are used for every message. An account-wide key may name any project of its account; a project-bound key acts for its own project only (naming another answers 403 profile_mismatch). Omitted: the key's project, else the primary project.

type'phone' | 'email' | 'domain' | 'social' | 'wallet' | 'account' | 'telegram_bot' required

Type of asset being verified

channel'whatsapp' | 'telegram' | 'sms' | 'email' | 'dns' | 'http' | 'auto' | 'github' | 'google' | 'facebook' | 'x' | 'linkedin' | 'instagram' | 'youtube' | 'tiktok' | 'ethereum' | 'solana' | 'bitcoin' | 'coinbase' | 'kraken' | 'telegram_bot_token' required

Channel used for verification

identifierstring required

The asset identifier to verify

external_user_idstring

Your user ID for grouping verifications

client_metadataobject

Custom metadata to attach to verification

email_prefix'admin' | 'administrator' | 'webmaster' | 'hostmaster' | 'postmaster'

Email prefix for domain email verification

bot_tokenstring

Telegram bot token (required for channel=telegram_bot_token)

proof_expiry_daysinteger

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

Example request

{
  "profile_id": "507f1f77bcf86cd799439011",
  "type": "phone",
  "channel": "whatsapp",
  "identifier": "+37069199199",
  "external_user_id": "user_12345",
  "client_metadata": {
    "source": "onboarding"
  },
  "dns_provider": {
    "provider": "cloudflare",
    "region": "us-east-1"
  },
  "email_prefix": "admin",
  "proof_expiry_days": 90
}

Response

Verification created

idstring required

MongoDB ObjectId

type'phone' | 'email' | 'domain' | 'social' | 'wallet' | 'account' | 'telegram_bot' required

Type of asset being verified

channel'whatsapp' | 'telegram' | 'sms' | 'email' | 'dns' | 'http' | 'auto' | 'github' | 'google' | 'facebook' | 'x' | 'linkedin' | 'instagram' | 'youtube' | 'tiktok' | 'ethereum' | 'solana' | 'bitcoin' | 'coinbase' | 'kraken' | 'telegram_bot_token' required

Channel used for verification

identifierstring

The identifier being verified; absent for an identifier-free phone verification, whose number is learned only when the person completes it

status'pending' | 'verified' | 'failed' | 'expired' | 'revoked' | 'cancelled' required

Current status of the verification

external_user_idstring
attemptsinteger
max_attemptsinteger
created_atstring date-time required
updated_atstring date-time
verified_atstring date-time

Example response

{
  "id": "507f1f77bcf86cd799439011",
  "type": "phone",
  "channel": "whatsapp",
  "identifier": "+3706***9199",
  "status": "pending",
  "challenge": {
    "code": "X7K2M9",
    "instruction": "Send X7K2M9 to +370 691 99199 on WhatsApp",
    "expires_at": "2026-02-13T12:00:00Z"
  },
  "proof": {
    "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_at": "2025-01-15T12:00:00Z",
    "confidence": "high"
  },
  "max_attempts": 5
}

Changes

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