secuveriAPI docs
OpenAPIMarkdown

Read a proof of address

POST/v1/proof-of-address/read

The proof-of-address reader on a bill or statement: name match against the name you send, address, issue date and age, issuer, document type, QR-bill and PDF forensics. It assists and never approves. Asynchronous: answers 202, then proof_of_address.read.completed. CHF 0.25 when the reader read the file; refunded when it could not. Needs the poa:read scope. The file is not stored.

Send your API key in the x-api-key header.

Headers

  • Idempotency-Keystring8–200 chars

    Reuse on retries (printable non-space ASCII). For 24 hours the same key and the same request return the saved answer and check id without a second charge; a different request under the key returns 409.

Request bodyapplication/jsonrequired

  • given_namesstringrequired
  • surnamestringrequired
  • countrystring

    Expected country of the address, ISO 3166-1.

  • postcodestring

    Expected postcode; answered as postcode_match.

  • max_age_daysintegerdefault 90

    One of306090180

  • reference_idstring≤ 128 chars

    Your own id, echoed in the answer.

  • sandbox_outcomestring

    Sandbox keys only: which test answer to return. No model runs and nothing is charged.

    One ofpassreviewunreadable

  • filestringrequired

    PDF, JPEG, PNG, WebP, HEIC or AVIF, at most 10 MB.

Responses

  • 202Accepted. Poll the check or wait for its webhook.
    • check_idstringuuidrequired
    • productstring
    • environmentstring | null
    • statusstringrequired

      One ofPROCESSINGCOMPLETEDFAILED

    • sandboxboolean
    • created_atstringdate-time
    • completed_atstring | nulldate-time
    • reference_idstring
    • poll_urlstring
    • resultobject
      Show 20 child properties
      • check_idstringuuid
      • productstring
      • environmentstring | null
      • sandboxboolean
      • checked_atstringdate-time
      • reference_idstring
      • signed_resultstring

        The same answer as an ES256 JWS, verifiable with /.well-known/jwks.json.

      • statestring

        One ofPASSREVIEWERROR

      • readboolean

        Whether the reader read the file (what is charged).

      • consistentboolean
      • findingsarray of string
      • document_typestring | null
      • issuerstring | null
      • issued_onstring | null
      • age_daysinteger | null
      • name_scorenumber | null
      • addressobject | null
      • postcode_matchboolean | null
      • qr_billobject | null
      • pdfobject | null
    • errorobject
      Show 2 child properties
      • codestring
      • messagestring
  • 400Invalid input.
  • 401Missing, unknown or expired API key.
  • 402The balance does not cover the check.
  • 403The key lacks the product's scope, its IP allowlist refuses the caller, or (code production_not_allowed) the organization may not use production yet.
  • 409The Idempotency-Key is in progress (Retry-After: 1) or was used with a different request.
  • 413A file or the body is too large.
  • 415A file is not of an accepted type (checked by its bytes, not its name), or the body is neither multipart nor JSON.
  • 429More than 60 calls in a minute for this product.
  • 503The check could not run on our side. Nothing was charged; retry later with the same Idempotency-Key.
curl -X POST https://api-verify.secuveri.com/v1/proof-of-address/read \
  -H "x-api-key: $SECUVERI_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: signup-1042-retry-safe" \
  -d '{
  "given_names": "<given names>",
  "surname": "<surname>",
  "file": "<file>"
}'
Response · 202
{
  "check_id": "6f1c2e0a-8f43-4f7e-9a51-2b7c1d9e4a10",
  "environment": "<environment>",
  "status": "PROCESSING",
  "completed_at": "2026-10-23T09:12:44.120Z"
}