Skip to main content
Identity privacy

Reusable applicant identity

Reuse eligible evidence only with the applicant's consent and a fresh merchant-scoped verification—never through a global document-number lookup.

Saved Personal Identity records belong to the applicant. Merchant applicants and verification cases belong to one authorized Business or Reseller tenant. These are separate security boundaries.

Fresh evidence and no cross-merchant discovery
Every new merchant case requires its own consent, decision record and applicable fresh selfie/liveness. A merchant cannot discover whether an unrelated business has already verified a person.

Applicant-owned Personal Identity

These routes require the applicant's authenticated JWT and Identity audience. They do not accept a merchant API key. List responses present only permitted saved-record data; full document numbers are not exposed as a reusable lookup key.

GET/v1/identity/documents/options
GET/v1/identity/documents
POST/v1/identity/documents
POST/v1/identity/documents/ocr
GET/v1/identity/documents/search/ocr
GET/v1/identity/documents/:id/extracted
PATCH/v1/identity/documents/:id/extracted
GET/v1/identity/documents/:id/media
POST/v1/identity/liveness/check
Operation, Contract
OperationContract
OptionsCountry/document options supported by the current personal-identity module; availability elsewhere is not implied.
OCR and livenessAt most six requests per minute. Unsupported or uncertain extraction is never presented as a successful verified identity.
OCR searchGET /identity/documents/search/ocr?q=… searches only the authenticated applicant’s own extracted text. Explicitly authorized reviewers use the separate Admin OCR search permission.
UploadUp to twelve requests per minute and 25 MB per original image. The server validates file bytes and sides, preserves the original and links any optimized derivative separately; caller-supplied OCR status alone is not verification.
CorrectionOnly the named saved record owned by the applicant can be corrected. Corrections are audited.
MediaOwner-authorized, no-store response. Do not treat the route as a public permanent document link or place it in emails/logs.
POST/v1/identity/documents/:id/applicant-consents
DELETE/v1/identity/documents/applicant-consents/:verificationId

The consent body names the new verification_id and explicit consent boolean. The verification and saved record must be eligible for this exact sharing operation. Revoking consent affects future permitted use; it does not rewrite the merchant's historic audit decision.

grant-consent.sh
curl -X POST https://api.okias.io/v1/identity/documents/$DOCUMENT_ID/applicant-consents \
  -H "Authorization: Bearer $APPLICANT_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "verification_id": "ver_merchant_scoped_case", "consent": true }'
DELETE/v1/identity/documents/:id

Deleting a saved identity is a sensitive operation subject to retention/blocking rules. Do not retry it against another account or use it to bypass an unresolved compliance obligation.

Business and Reseller applicant records

These routes require a Business or Reseller console JWT. Every list, read, block and erase operation is scoped to the caller's tenant and, where supplied, its own project_id.

GET/v1/applicants
GET/v1/applicants/:id
PATCH/v1/applicants/:id/status
DELETE/v1/applicants/:id
Request, Purpose
RequestPurpose
GET /applicants?page=1&page_size=25&status=ACTIVE&project_id=…&q=…List only this tenant's applicants with bounded pagination and optional project/status/search filters.
PATCH /applicants/:id/statusBody: { "status": "ACTIVE" } or { "status": "BLOCKED" }.
DELETE /applicants/:idErase permitted applicant identity data under the existing retention and financial/compliance blockers.

Duplicate submissions and idempotency

  • Reuse matching is tenant/project scoped and uses protected fingerprints—not a public global document-number query.
  • An eligible repeat can return existing evidence or an updated-verification choice instead of forcing unnecessary uploads.
  • A replayed idempotent request returns its original result and cannot create a second charge.
  • A fresh merchant case may still be required even when previous document evidence is reusable.
  • Another tenant receives the same not-found behavior for an applicant, saved record or consent reference that it does not own.

API-created verification behavior and the Idempotency-Key contract are documented in Verifications. Merchant OCR retrieval is owner-only and is not a public saved-document feed.

Next steps