Verifications

Submit challenge code

Submit a challenge code to complete verification.

Accepted ONLY where the code was delivered out-of-band to the party being verified: type: email, and type: domain with channel: email (the code goes to <prefix>@<domain>). For those pairs the create response deliberately withholds the challenge code and the magic link — the delivery is what the proof rests on.

Every other pair answers 400 unsupported_for_type and must produce its own evidence instead: POST /api/v1/verifications/{id}/verify for domain over dns, http or auto; the inbound message from the number itself for phone; the OAuth callback for social; the signed challenge message for wallet. A telegram_bot verification is already completed at creation, when its token is validated.

post/api/v1/verifications/{id}/submit

Request

  • Base URL: https://api.proof.holdings
  • URL: https://api.proof.holdings/api/v1/verifications/{id}/submit
  • Auth: HTTP bearer

Path parameters

idstring required

MongoDB ObjectId

Example:507f1f77bcf86cd799439011

Request body

challenge_codestring required

The 6-character challenge code

source_identifierstring

Phone/email that sent the code (for validation)

Example request

{
  "challenge_code": "X7K2M9"
}

Response

Verification completed

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.