Passwave API

curl https://api.passwave.com/api/verification/init \
  -H "Authorization: Bearer sk_test_..." \
  -H "X-App-Auth: passwave-app" \
  -H "Accept: application/json"

{
  "status": {
    "success": true,
    "code": 200,
    "message": "Verification session created"
  },
  "data": {
    "verification_url": "https://passwave.com/open",
    "verification_link": "https://passwave.com/open/AB3X-7K9M-2PQ5-4WZ8",
    "access_code": "AB3X-7K9M-2PQ5-4WZ8",
    "expires_at": "2026-04-29T12:10:00Z",
    "expires_in": 600
  }
}

curl https://api.passwave.com/api/verification/retrieve \
  -H "Authorization: Bearer sk_test_..." \
  -H "Access-Key: AB3X-7K9M-2PQ5-4WZ8" \
  -H "X-App-Auth: passwave-app" \
  -H "Accept: application/json"

{
  "status": {
    "success": true,
    "code": 200,
    "message": "Waiting for user to complete request via Passwave app."
  },
  "data": {
    "scanned": false,
    "pending": true
  }
}

{
  "status": {
    "success": true,
    "code": 200,
    "message": "Verification data found"
  },
  "data": {
    "status": "completed",
    "created_at": "2026-04-29T12:00:00Z",
    "expires_at": "2026-04-29T12:10:00Z",
    "completed_at": "2026-04-29T12:05:00Z",
    "access_code": "AB3X-7K9M-2PQ5-4WZ8",
    "verifications": {
      "site_token": "a3f82c917d4e5b60c8f1d92e7a45b3c6091e8d74f2ab5c30e6d19f84b7c25a01",
      "verified": true,
      "verification": {
        "status": "verified",
        "country": [
          { "name": "United Kingdom", "iso_code": "GB", "emoji_flag": "🇬🇧" }
        ],
        "date_expires": "2029-01-01T00:00:00.000000Z",
        "legal_gender": "male",
        "over_18": true,
        "over_21": true,
        "over_25": true,
        "age_band": "25-35"
      },
      "capability_code": "7Q3KX9M2P4R8T6V1W5Y0Z2A3B4C5D6E7",
      "capabilities_version": 1,
      "capabilities": [
        { "capability": "name_match", "window_hours": 24, "window_ends_at": "2026-04-30T12:05:00Z", "lifetime_cap": 5 }
      ]
    },
    "preferences": null
  }
}

age_band  covers ages
────────  ───────────
16-17     16 to 17
18-20     18 to 20
21-24     21 to 24
25-35     25 to 35
36-45     36 to 45
46-60     46 to 60
61-75     61 to 75
76+       76 and over
null      no band on record

legal_gender  means
────────────  ─────
male          a verified document states male
female        a verified document states female
other         a verified document states a third value
undefined     no verified document states a legal gender
(absent)      not entitled, or include_legal_gender was not set

curl -X POST https://api.passwave.com/api/capability/name-match \
  -H "Authorization: Bearer sk_test_..." \
  -H "X-App-Auth: passwave-app" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "code": "7Q3KX9M2P4R8T6V1W5Y0Z2A3B4C5D6E7", "name": "SMITH/JOHN MR" }'

{
  "status": {
    "success": true,
    "code": 200,
    "message": "Name match evaluated"
  },
  "data": {
    "result": "match"
  }
}

{
  "status": {
    "success": true,
    "code": 200,
    "message": "Name match refused"
  },
  "data": {
    "refused": true,
    "reason": "window_closed"
  }
}

Capability table · version 1 · a code lives 90 days from the share
capability   window after share   answer                       cap per code
name_match   24 hours             match · partial · no_match   5, lifetime

unknown_code          Never issued, or already deleted at 90 days. Ask the user for a new share.
wrong_service         Issued to a different project. A code is inert outside the project it was issued to; check the API key you present.
revoked               The user cut your service off. Final for this share.
expired               Past its 90-day life. Ask for a new share.
window_closed         The 24-hour name-match window after the share has closed. Ask for a new share.
cap_exhausted         All five name-match queries on this code are used. Stop asking.
service_rate_limited  Your project is over its rolling 24-hour query ceiling. Back off and retry later.
no_document           The user holds no verified document to compare against. Unanswerable, not a no_match.
name_unusable         The name could not be evaluated: fewer than two parts, no Latin letters, or more than ten parts. Fix the input; not a no_match.