Operation details
List every tenant's identity verification cases (platform administrator)
- operationId
listPlatformIdentityVerificationCases- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：platform.admin
Description (from the contract)
Admin console identity review entry (fix-decide1027b item 3). Platform sessions only, and the administrator must hold platform.admin in the platform scope (tenantaccess rule); tenant sessions and other platform members get 403. Rows carry the tenant scope, tenant display name and applicant username; reviewing one case uses the reviewer routes with tenant_scope_id. The HMAC cursor is bound to the platform scope and exact kind/status filters; tenant_scope_id is rejected.
Parameters
listPlatformIdentityVerificationCases Parameters| Name | In | Type | Required | Description |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Tenant- and filter-bound HMAC cursor returned by the preceding page. |
|---|
kind | query | string: personal_initial / personal_reverification / enterprise | No | — |
|---|
status | query | string: draft / submitted / reviewing / approved / rejected / withdrawn / expired | No | — |
|---|
Responses
listPlatformIdentityVerificationCases Responses| Status | Description |
|---|
200 | Platform administrator cross-tenant case page. Fields：items: array<AdminCaseSummary> next_cursor?: string |
|---|
400 | Strict header, query, path, body, or trusted material validation failed. |
|---|
401 | Authentication failed or did not produce a tenant Actor. |
|---|
403 | Live tenant membership/RBAC, self-review, or assignment check denied the operation. |
|---|
405 | The path exists but the HTTP method is not supported; the response includes Allow. |
|---|
408 | Request context was canceled. |
|---|
503 | Resolver, core store, read store, audit append, or bounded response is unavailable. No raw cause is returned. |
|---|
504 | Bounded command or query timeout elapsed. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/identity-verification/cases
Create a draft from trusted server-resolved evidence
- operationId
createMyIdentityVerificationDraft- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity_verification.self.manage
Description (from the contract)
Requires identity_verification.self.manage. The evidence token must be bound by the resolver to the authenticated tenant and user. A missing resolver fails service construction; client-supplied fingerprint or material metadata is rejected as an unknown field. Live IAM is checked without business writes before reserving evidence, then checked again inside the create transaction before idempotency, locks, DML, or audit.
Parameters
createMyIdentityVerificationDraft Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createMyIdentityVerificationDraft Request body| Name | Type | Required | Description |
|---|
kind | string: personal_initial / personal_reverification / enterprise | Yes | — |
|---|
evidence_token | string | Yes | Opaque one-time trusted resolver handle; never a fingerprint or document value. |
|---|
Responses
createMyIdentityVerificationDraft Responses| Status | Description |
|---|
201 | Draft created. Fields：id: string(uuid) applicant_user_id: string(uuid) kind: string: personal_initial / personal_reverification / enterprise status: string: draft / submitted / reviewing / approved / rejected / withdrawn / expired decision_reason_code?: string: evidence_verified / identity_mismatch / evidence_incomplete / evidence_unreadable / organization_mismatch / authorization_invalid / suspected_fraud agent_relationship?: string: legal_person / employee / authorized_representative reviewer_user_id?: string(uuid) revision: integer(int64) created_at: string(date-time) state_changed_at: string(date-time) submitted_at?: string(date-time) expires_at?: string(date-time) terminal_at?: string(date-time) retention: RetentionView materials: array<MaterialView> replayed: boolean |
|---|
200 | Sanitized case projection. A replayed write returns replayed=true. Fields：id: string(uuid) applicant_user_id: string(uuid) kind: string: personal_initial / personal_reverification / enterprise status: string: draft / submitted / reviewing / approved / rejected / withdrawn / expired decision_reason_code?: string: evidence_verified / identity_mismatch / evidence_incomplete / evidence_unreadable / organization_mismatch / authorization_invalid / suspected_fraud agent_relationship?: string: legal_person / employee / authorized_representative reviewer_user_id?: string(uuid) revision: integer(int64) created_at: string(date-time) state_changed_at: string(date-time) submitted_at?: string(date-time) expires_at?: string(date-time) terminal_at?: string(date-time) retention: RetentionView materials: array<MaterialView> replayed: boolean |
|---|
400 | Strict header, query, path, body, or trusted material validation failed. |
|---|
401 | Authentication failed or did not produce a tenant Actor. |
|---|
403 | Live tenant membership/RBAC, self-review, or assignment check denied the operation. |
|---|
405 | The path exists but the HTTP method is not supported; the response includes Allow. |
|---|
409 | Revision, idempotency payload, active review, or state transition conflict. |
|---|
422 | Trusted evidence does not match the previously approved stable identity. |
|---|
408 | Request context was canceled. |
|---|
503 | Resolver, core store, read store, audit append, or bounded response is unavailable. No raw cause is returned. |
|---|
504 | Bounded command or query timeout elapsed. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/identity-verification/cases/{case_id}
Read a case owned by the authenticated user
- operationId
getMyIdentityVerificationCase- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity_verification.self.manage
Description (from the contract)
A different-user or different-tenant case returns the same 404 as an unknown case.
Parameters
getMyIdentityVerificationCase Parameters| Name | In | Type | Required | Description |
|---|
case_id | path | string(uuid) | Yes | Canonical lower-case UUID of the identity verification case. |
|---|
Responses
getMyIdentityVerificationCase Responses| Status | Description |
|---|
200 | Sanitized case projection. A replayed write returns replayed=true. Fields：id: string(uuid) applicant_user_id: string(uuid) kind: string: personal_initial / personal_reverification / enterprise status: string: draft / submitted / reviewing / approved / rejected / withdrawn / expired decision_reason_code?: string: evidence_verified / identity_mismatch / evidence_incomplete / evidence_unreadable / organization_mismatch / authorization_invalid / suspected_fraud agent_relationship?: string: legal_person / employee / authorized_representative reviewer_user_id?: string(uuid) revision: integer(int64) created_at: string(date-time) state_changed_at: string(date-time) submitted_at?: string(date-time) expires_at?: string(date-time) terminal_at?: string(date-time) retention: RetentionView materials: array<MaterialView> replayed: boolean |
|---|
400 | Strict header, query, path, body, or trusted material validation failed. |
|---|
401 | Authentication failed or did not produce a tenant Actor. |
|---|
403 | Live tenant membership/RBAC, self-review, or assignment check denied the operation. |
|---|
404 | Case is missing or outside the actor's user/tenant visibility boundary. |
|---|
405 | The path exists but the HTTP method is not supported; the response includes Allow. |
|---|
408 | Request context was canceled. |
|---|
503 | Resolver, core store, read store, audit append, or bounded response is unavailable. No raw cause is returned. |
|---|
504 | Bounded command or query timeout elapsed. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/identity-verification/cases/{case_id}/expire
Expire an owned submitted or reviewing case after its deadline
- operationId
expireMyIdentityVerificationCase- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity_verification.self.manage
Description (from the contract)
It is not a reviewer, administrator, or scheduler endpoint and cannot substitute another actor.
Parameters
expireMyIdentityVerificationCase Parameters| Name | In | Type | Required | Description |
|---|
case_id | path | string(uuid) | Yes | Canonical lower-case UUID of the identity verification case. |
|---|
If-Match | header | string | Yes | Quoted positive decimal current case revision, for example `"2"`. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
↑ Back to list
POST /v1/identity-verification/cases/{case_id}/submit
Submit an owned draft for review
- operationId
submitMyIdentityVerificationCase- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity_verification.self.manage
Parameters
submitMyIdentityVerificationCase Parameters| Name | In | Type | Required | Description |
|---|
case_id | path | string(uuid) | Yes | Canonical lower-case UUID of the identity verification case. |
|---|
If-Match | header | string | Yes | Quoted positive decimal current case revision, for example `"2"`. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Responses
submitMyIdentityVerificationCase Responses| Status | Description |
|---|
200 | Sanitized case projection. A replayed write returns replayed=true. Fields：id: string(uuid) applicant_user_id: string(uuid) kind: string: personal_initial / personal_reverification / enterprise status: string: draft / submitted / reviewing / approved / rejected / withdrawn / expired decision_reason_code?: string: evidence_verified / identity_mismatch / evidence_incomplete / evidence_unreadable / organization_mismatch / authorization_invalid / suspected_fraud agent_relationship?: string: legal_person / employee / authorized_representative reviewer_user_id?: string(uuid) revision: integer(int64) created_at: string(date-time) state_changed_at: string(date-time) submitted_at?: string(date-time) expires_at?: string(date-time) terminal_at?: string(date-time) retention: RetentionView materials: array<MaterialView> replayed: boolean |
|---|
400 | Strict header, query, path, body, or trusted material validation failed. |
|---|
401 | Authentication failed or did not produce a tenant Actor. |
|---|
403 | Live tenant membership/RBAC, self-review, or assignment check denied the operation. |
|---|
404 | Case is missing or outside the actor's user/tenant visibility boundary. |
|---|
405 | The path exists but the HTTP method is not supported; the response includes Allow. |
|---|
409 | Revision, idempotency payload, active review, or state transition conflict. |
|---|
422 | Trusted evidence does not match the previously approved stable identity. |
|---|
408 | Request context was canceled. |
|---|
503 | Resolver, core store, read store, audit append, or bounded response is unavailable. No raw cause is returned. |
|---|
504 | Bounded command or query timeout elapsed. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/identity-verification/cases/{case_id}/withdraw
Withdraw an owned draft or submitted case
- operationId
withdrawMyIdentityVerificationCase- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity_verification.self.manage
Parameters
withdrawMyIdentityVerificationCase Parameters| Name | In | Type | Required | Description |
|---|
case_id | path | string(uuid) | Yes | Canonical lower-case UUID of the identity verification case. |
|---|
If-Match | header | string | Yes | Quoted positive decimal current case revision, for example `"2"`. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
↑ Back to list
POST /v1/identity-verification/provider-callbacks/{provider}
Accept a signed replay-safe provider callback
- operationId
acceptIdentityVerificationProviderCallback- Auth
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Bearer and actor headers are rejected. The callback signature covers timestamp, nonce and the exact body. Timestamp freshness, unique nonce, unique event, local session ID and external provider session ID are all checked before monotonic state application. The stable replay conflict code is identity_verification_provider_callback_replay_conflict.
Parameters
acceptIdentityVerificationProviderCallback Parameters| Name | In | Type | Required | Description |
|---|
provider | path | string | Yes | — |
|---|
X-KYC-Timestamp | header | string | Yes | — |
|---|
X-KYC-Nonce | header | string | Yes | — |
|---|
X-KYC-Key-ID | header | string | Yes | — |
|---|
X-KYC-Signature | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
Responses
acceptIdentityVerificationProviderCallback Responses| Status | Description |
|---|
200 | Signed callback application result. Fields：session_id: string(uuid) state: string revision: integer(int64) applied: boolean replayed: boolean |
|---|
400 | Strict header, query, path, body, or trusted material validation failed. |
|---|
401 | Authentication failed or did not produce a tenant Actor. |
|---|
405 | The path exists but the HTTP method is not supported; the response includes Allow. |
|---|
409 | Revision, idempotency payload, active review, or state transition conflict. |
|---|
408 | Request context was canceled. |
|---|
503 | Resolver, core store, read store, audit append, or bounded response is unavailable. No raw cause is returned. |
|---|
504 | Bounded command or query timeout elapsed. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/identity-verification/provider-sessions
Start or retry a durable KYC provider session
- operationId
startIdentityVerificationProviderSession- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity_verification.self.manage
Description (from the contract)
Requires a live tenant session and identity_verification.self.manage. The durable local intent is committed before the HTTPS provider call; an unknown provider outcome is retried with the exact provider request identity.
Parameters
startIdentityVerificationProviderSession Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
startIdentityVerificationProviderSession Request body| Name | Type | Required | Description |
|---|
kind | string: personal_initial / personal_reverification / enterprise | Yes | — |
|---|
provider | string | Yes | — |
|---|
Responses
startIdentityVerificationProviderSession Responses| Status | Description |
|---|
201 | Durable provider session projection. Fields：id: string(uuid) kind: string: personal_initial / personal_reverification / enterprise provider: string state: string: creating / pending / processing / succeeded / failed / canceled / expired / unknown revision: integer(int64) evidence_token?: string expires_at: string(date-time) updated_at: string(date-time) replayed: boolean |
|---|
200 | Durable provider session projection. Fields：id: string(uuid) kind: string: personal_initial / personal_reverification / enterprise provider: string state: string: creating / pending / processing / succeeded / failed / canceled / expired / unknown revision: integer(int64) evidence_token?: string expires_at: string(date-time) updated_at: string(date-time) replayed: boolean |
|---|
400 | Strict header, query, path, body, or trusted material validation failed. |
|---|
401 | Authentication failed or did not produce a tenant Actor. |
|---|
403 | Live tenant membership/RBAC, self-review, or assignment check denied the operation. |
|---|
405 | The path exists but the HTTP method is not supported; the response includes Allow. |
|---|
409 | Revision, idempotency payload, active review, or state transition conflict. |
|---|
408 | Request context was canceled. |
|---|
503 | Resolver, core store, read store, audit append, or bounded response is unavailable. No raw cause is returned. |
|---|
504 | Bounded command or query timeout elapsed. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/identity-verification/provider-sessions/{session_id}/uploads
Create a bound private object store upload
- operationId
createIdentityVerificationPrivateUpload- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity_verification.self.manage
Description (from the contract)
Returns a short-lived presigned PUT whose signed headers bind the exact digest, size, content type, KMS encryption_key_id and private object key. Material bytes never pass through or enter the control database.
Parameters
createIdentityVerificationPrivateUpload Parameters| Name | In | Type | Required | Description |
|---|
session_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
createIdentityVerificationPrivateUpload Request body| Name | Type | Required | Description |
|---|
material_kind | string: identity_document / liveness_evidence / business_license / legal_person_identity / agent_identity / authorization_letter / supplementary | Yes | — |
|---|
content_type | string: image/jpeg / image/png / application/pdf / video/mp4 | Yes | — |
|---|
size_bytes | integer(int64) | Yes | — |
|---|
sha256 | string | Yes | — |
|---|
Responses
createIdentityVerificationPrivateUpload Responses| Status | Description |
|---|
201 | Private upload projection; object key and object_version remain server-side facts. Fields：id: string(uuid) session_id: string(uuid) material_kind: string state: string: issued / finalized / erase_pending / erased revision: integer(int64) upload_url?: string(uri) required_headers?: object expires_at: string(date-time) replayed: boolean |
|---|
200 | Private upload projection; object key and object_version remain server-side facts. Fields：id: string(uuid) session_id: string(uuid) material_kind: string state: string: issued / finalized / erase_pending / erased revision: integer(int64) upload_url?: string(uri) required_headers?: object expires_at: string(date-time) replayed: boolean |
|---|
400 | Strict header, query, path, body, or trusted material validation failed. |
|---|
401 | Authentication failed or did not produce a tenant Actor. |
|---|
403 | Live tenant membership/RBAC, self-review, or assignment check denied the operation. |
|---|
404 | Case is missing or outside the actor's user/tenant visibility boundary. |
|---|
405 | The path exists but the HTTP method is not supported; the response includes Allow. |
|---|
409 | Revision, idempotency payload, active review, or state transition conflict. |
|---|
408 | Request context was canceled. |
|---|
503 | Resolver, core store, read store, audit append, or bounded response is unavailable. No raw cause is returned. |
|---|
504 | Bounded command or query timeout elapsed. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/identity-verification/provider-sessions/{session_id}/uploads/{upload_id}/finalize
Finalize exact immutable private object facts
- operationId
finalizeIdentityVerificationPrivateUpload- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity_verification.self.manage
Description (from the contract)
HEAD verification must return the expected object_version, SHA-256, size, content type and encryption_key_id before the upload is finalized.
Parameters
finalizeIdentityVerificationPrivateUpload Parameters| Name | In | Type | Required | Description |
|---|
session_id | path | string(uuid) | Yes | — |
|---|
upload_id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | Quoted positive decimal current case revision, for example `"2"`. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
Responses
finalizeIdentityVerificationPrivateUpload Responses| Status | Description |
|---|
200 | Private upload projection; object key and object_version remain server-side facts. Fields：id: string(uuid) session_id: string(uuid) material_kind: string state: string: issued / finalized / erase_pending / erased revision: integer(int64) upload_url?: string(uri) required_headers?: object expires_at: string(date-time) replayed: boolean |
|---|
400 | Strict header, query, path, body, or trusted material validation failed. |
|---|
401 | Authentication failed or did not produce a tenant Actor. |
|---|
403 | Live tenant membership/RBAC, self-review, or assignment check denied the operation. |
|---|
404 | Case is missing or outside the actor's user/tenant visibility boundary. |
|---|
405 | The path exists but the HTTP method is not supported; the response includes Allow. |
|---|
409 | Revision, idempotency payload, active review, or state transition conflict. |
|---|
422 | Trusted evidence does not match the previously approved stable identity. |
|---|
408 | Request context was canceled. |
|---|
503 | Resolver, core store, read store, audit append, or bounded response is unavailable. No raw cause is returned. |
|---|
504 | Bounded command or query timeout elapsed. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/identity-verification/reviewer/cases
List the authenticated tenant's review cases
- operationId
listTenantIdentityVerificationCases- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity_verification.read identity_verification.review
Description (from the contract)
Requires live active membership, active user, identity_verification.read, and identity_verification.review. The HMAC cursor is bound to the authenticated tenant and exact kind/status filters. tenant_id, applicant_id, and reviewer_id query parameters are rejected.
Parameters
listTenantIdentityVerificationCases Parameters| Name | In | Type | Required | Description |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Tenant- and filter-bound HMAC cursor returned by the preceding page. |
|---|
kind | query | string: personal_initial / personal_reverification / enterprise | No | — |
|---|
status | query | string: draft / submitted / reviewing / approved / rejected / withdrawn / expired | No | — |
|---|
tenant_scope_id | query | string(uuid) | No | Platform administrator sessions only (user 10-27: 平台管理员也能代审): the tenant scope whose cases are reviewed. Required for a platform session, rejected with 400 for a tenant session. The administrator must hold platform.admin and the tenant must be active; the administrator acts and is audited as themself (payload actor_scope_kind=platform). |
|---|
Responses
listTenantIdentityVerificationCases Responses| Status | Description |
|---|
200 | Stable reviewer queue page. Fields：items: array<CaseSummary> next_cursor?: string |
|---|
400 | Strict header, query, path, body, or trusted material validation failed. |
|---|
401 | Authentication failed or did not produce a tenant Actor. |
|---|
403 | Live tenant membership/RBAC, self-review, or assignment check denied the operation. |
|---|
405 | The path exists but the HTTP method is not supported; the response includes Allow. |
|---|
408 | Request context was canceled. |
|---|
503 | Resolver, core store, read store, audit append, or bounded response is unavailable. No raw cause is returned. |
|---|
504 | Bounded command or query timeout elapsed. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
GET /v1/identity-verification/reviewer/cases/{case_id}
Read one case in the authenticated reviewer tenant
- operationId
getTenantIdentityVerificationCase- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity_verification.read identity_verification.review
Description (from the contract)
A different-tenant case returns the same 404 as an unknown case.
Parameters
getTenantIdentityVerificationCase Parameters| Name | In | Type | Required | Description |
|---|
case_id | path | string(uuid) | Yes | Canonical lower-case UUID of the identity verification case. |
|---|
tenant_scope_id | query | string(uuid) | No | Platform administrator sessions only (user 10-27: 平台管理员也能代审): the tenant scope whose cases are reviewed. Required for a platform session, rejected with 400 for a tenant session. The administrator must hold platform.admin and the tenant must be active; the administrator acts and is audited as themself (payload actor_scope_kind=platform). |
|---|
Responses
getTenantIdentityVerificationCase Responses| Status | Description |
|---|
200 | Sanitized case projection. A replayed write returns replayed=true. Fields：id: string(uuid) applicant_user_id: string(uuid) kind: string: personal_initial / personal_reverification / enterprise status: string: draft / submitted / reviewing / approved / rejected / withdrawn / expired decision_reason_code?: string: evidence_verified / identity_mismatch / evidence_incomplete / evidence_unreadable / organization_mismatch / authorization_invalid / suspected_fraud agent_relationship?: string: legal_person / employee / authorized_representative reviewer_user_id?: string(uuid) revision: integer(int64) created_at: string(date-time) state_changed_at: string(date-time) submitted_at?: string(date-time) expires_at?: string(date-time) terminal_at?: string(date-time) retention: RetentionView materials: array<MaterialView> replayed: boolean |
|---|
400 | Strict header, query, path, body, or trusted material validation failed. |
|---|
401 | Authentication failed or did not produce a tenant Actor. |
|---|
403 | Live tenant membership/RBAC, self-review, or assignment check denied the operation. |
|---|
404 | Case is missing or outside the actor's user/tenant visibility boundary. |
|---|
405 | The path exists but the HTTP method is not supported; the response includes Allow. |
|---|
408 | Request context was canceled. |
|---|
503 | Resolver, core store, read store, audit append, or bounded response is unavailable. No raw cause is returned. |
|---|
504 | Bounded command or query timeout elapsed. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/identity-verification/reviewer/cases/{case_id}/claim
Atomically claim a submitted case as the authenticated reviewer
- operationId
claimTenantIdentityVerificationCase- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity_verification.read identity_verification.review
Parameters
claimTenantIdentityVerificationCase Parameters| Name | In | Type | Required | Description |
|---|
case_id | path | string(uuid) | Yes | Canonical lower-case UUID of the identity verification case. |
|---|
If-Match | header | string | Yes | Quoted positive decimal current case revision, for example `"2"`. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
tenant_scope_id | query | string(uuid) | No | Platform administrator sessions only (user 10-27: 平台管理员也能代审): the tenant scope whose cases are reviewed. Required for a platform session, rejected with 400 for a tenant session. The administrator must hold platform.admin and the tenant must be active; the administrator acts and is audited as themself (payload actor_scope_kind=platform). |
|---|
↑ Back to list
POST /v1/identity-verification/reviewer/cases/{case_id}/decision
Approve or reject a case assigned to the authenticated reviewer
- operationId
decideTenantIdentityVerificationCase- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity_verification.read identity_verification.review
Description (from the contract)
Free-text review notes are not accepted. Only stable decision and reason codes are persisted.
Parameters
decideTenantIdentityVerificationCase Parameters| Name | In | Type | Required | Description |
|---|
case_id | path | string(uuid) | Yes | Canonical lower-case UUID of the identity verification case. |
|---|
If-Match | header | string | Yes | Quoted positive decimal current case revision, for example `"2"`. |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
tenant_scope_id | query | string(uuid) | No | Platform administrator sessions only (user 10-27: 平台管理员也能代审): the tenant scope whose cases are reviewed. Required for a platform session, rejected with 400 for a tenant session. The administrator must hold platform.admin and the tenant must be active; the administrator acts and is audited as themself (payload actor_scope_kind=platform). |
|---|
Request body
application/json · Required：Yes
decideTenantIdentityVerificationCase Request body| Name | Type | Required | Description |
|---|
decision | string: approved / rejected | Yes | — |
|---|
reason_code | string: evidence_verified / identity_mismatch / evidence_incomplete / evidence_unreadable / organization_mismatch / authorization_invalid / suspected_fraud | Yes | — |
|---|
↑ Back to list
GET /v1/identity-verification/status
Read the authenticated user's own verification status
- operationId
getMyIdentityVerificationStatus- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
All of：identity_verification.self.manage
Description (from the contract)
Read-only profile badge source for the authenticated tenant user. An approved initial personal identity keeps status verified; otherwise a submitted or reviewing latest case is pending, a rejected latest case is rejected, and no case, draft, withdrawn, or expired is unverified. The response never carries a document number, name, organization, fingerprint, material, or reviewer identity. Requires the same live identity_verification.self.manage check as reading an owned case.
Responses
getMyIdentityVerificationStatus Responses| Status | Description |
|---|
200 | The authenticated user's own verification status. Fields：status: string: unverified / pending / verified / rejected verified_at?: string(date-time) latest_case?: StatusCase |
|---|
400 | Strict header, query, path, body, or trusted material validation failed. |
|---|
401 | Authentication failed or did not produce a tenant Actor. |
|---|
403 | Live tenant membership/RBAC, self-review, or assignment check denied the operation. |
|---|
405 | The path exists but the HTTP method is not supported; the response includes Allow. |
|---|
408 | Request context was canceled. |
|---|
503 | Resolver, core store, read store, audit append, or bounded response is unavailable. No raw cause is returned. |
|---|
504 | Bounded command or query timeout elapsed. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list