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.
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.
/v1/identity/documents/options/v1/identity/documents/v1/identity/documents/v1/identity/documents/ocr/v1/identity/documents/search/ocr/v1/identity/documents/:id/extracted/v1/identity/documents/:id/extracted/v1/identity/documents/:id/media/v1/identity/liveness/check| Operation | Contract |
|---|---|
| Options | Country/document options supported by the current personal-identity module; availability elsewhere is not implied. |
| OCR and liveness | At most six requests per minute. Unsupported or uncertain extraction is never presented as a successful verified identity. |
| OCR search | GET /identity/documents/search/ocr?q=… searches only the authenticated applicant’s own extracted text. Explicitly authorized reviewers use the separate Admin OCR search permission. |
| Upload | Up 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. |
| Correction | Only the named saved record owned by the applicant can be corrected. Corrections are audited. |
| Media | Owner-authorized, no-store response. Do not treat the route as a public permanent document link or place it in emails/logs. |
Consent and revocation
/v1/identity/documents/:id/applicant-consents/v1/identity/documents/applicant-consents/:verificationIdThe 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.
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 }'/v1/identity/documents/:idDeleting 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.
/v1/applicants/v1/applicants/:id/v1/applicants/:id/status/v1/applicants/:id| Request | Purpose |
|---|---|
| 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/status | Body: { "status": "ACTIVE" } or { "status": "BLOCKED" }. |
| DELETE /applicants/:id | Erase 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.