Compliance
Package compliance is your KYC/KYB onboarding, accreditation records, and the evidence trail behind them.
Package compliance is your KYC/KYB onboarding, accreditation records, and the evidence trail behind them.
| Base URL | https://api.hanzo.ai |
| Operations | 17 |
| Auth | Authorization: Bearer $HANZO_API_KEY |
compliance
DecideAccreditation records an org reviewer's decision on an accreditation record — a reviewer confirmation, a provider verification the reviewer has evidence of (a CPA/attorney letter, a verifier report), a rejection, or an expiry.
POST /v1/compliance/accreditation/{id}/decision
DecideAccreditation records an org reviewer's decision on an accreditation record — a reviewer confirmation, a provider verification the reviewer has evidence of (a CPA/attorney letter, a verifier report), a rejection, or an expiry. ROLE-GATED (an org admin or platform reviewer) and ATTRIBUTED: the reviewer's identity is recorded as ReviewerSub and audited. Human-in-the-loop: the platform never confirms on its own, and even a provider_verified state carries the reviewer who recorded it.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the accreditation record to decide, from the path. |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
id | string | — | ID is the accreditation record to decide, from the path. |
status | string | — | Status is the decision being recorded: reviewer_confirmed, provider_verified, rejected, or expired. |
GetAccreditation returns one tracked accreditation record.
GET /v1/compliance/accreditation/{id}
GetAccreditation returns one tracked accreditation record.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the accreditation record to read, from the path. |
ListAccreditation returns the org's tracked accreditation-state records, newest first — evidence entries the org keeps, never a platform certification.
GET /v1/compliance/accreditation
ListAccreditation returns the org's tracked accreditation-state records, newest first — evidence entries the org keeps, never a platform certification.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer | — | Limit caps the rows returned; non-positive means the server default. |
CreateAccreditation records an ASSERTED accreditation state for a subject — the subject's own assertion, with no verifier.
POST /v1/compliance/accreditation
CreateAccreditation records an ASSERTED accreditation state for a subject — the subject's own assertion, with no verifier. Every CONFIRMED state (provider_verified, reviewer_confirmed) and every rejected/expired state is a DECISION recorded via the decision endpoint, attributed to the reviewer — a create can never stamp a confirmation. The underlying figures (income, net worth) are never stored; only the method, category, and state.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
basis | string | — | Basis is the qualification category: income, net_worth, professional_license, or entity. |
evidenceDocId | string | — | EvidenceDocID references an evidence document in the org's sealed data room. |
expiresAt | integer | — | ExpiresAt is the unix second a confirmation ages out; 0 means none. |
method | string | — | Method is how the state was established: self_attested, third_party_letter, or provider_verified. |
note | string | — | Note is a non-PII operator note. |
status | string | — | Status may only be "asserted" (empty reads as asserted); every confirmed, rejected or expired state is recorded via the |
subjectId | string | — | SubjectID names the subject this record is about; it must exist within the org. |
AuditRead is the compliance-scoped read of the SHARED tamper-evident audit plane — the SOC 2 posture surface (privileged actions: who started/decided what, when).
GET /v1/compliance/audit
AuditRead is the compliance-scoped read of the SHARED tamper-evident audit plane — the SOC 2 posture surface (privileged actions: who started/decided what, when). The org is PINNED to the caller's validated org and the rows are narrowed to compliance.* actions. Fail-closed: no principal is a 403, no configured audit store a 501.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
result | query | string | — | Result filters rows by outcome result: success, deny, or error; empty means all. |
Health reports subsystem liveness and the wired verification provider.
GET /v1/compliance/health
Health reports subsystem liveness and the wired verification provider. Fail-open on purpose: it never probes the external provider, so a provider outage cannot fail liveness.
ListRecords is the unified compliance-record view for the org: its verifications and accreditation records together, each provider-reported or tracked, never platform-asserted.
GET /v1/compliance/records
ListRecords is the unified compliance-record view for the org: its verifications and accreditation records together, each provider-reported or tracked, never platform-asserted. PII stays in the subject store; records carry only opaque ids and statuses.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer | — | Limit caps the rows returned; non-positive means the server default. |
Status is the org's honest posture read: the wired provider and the per-status tally of its verifications.
GET /v1/compliance/status
Status is the org's honest posture read: the wired provider and the per-status tally of its verifications. It is deliberately NOT a boolean "compliant" — it reports counts of provider-reported states and carries the boundary disclaimer.
GetSubject returns one subject WITH its contact PII — the only surface that returns it, and only to the owning org.
GET /v1/compliance/subjects/{id}
GetSubject returns one subject WITH its contact PII — the only surface that returns it, and only to the owning org. The response is never cached by any intermediary.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the subject to read, from the path. |
ListSubjects returns the org's subjects as PII-MINIMIZED summaries — no name or email, only whether an email is on file.
GET /v1/compliance/subjects
ListSubjects returns the org's subjects as PII-MINIMIZED summaries — no name or email, only whether an email is on file. The full record is returned only by the explicit single-subject read.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer | — | Limit caps the rows returned; non-positive means the server default. |
CreateSubject records a party the org is verifying as part of its own onboarding/compliance — a team member, vendor, customer, or counterparty.
POST /v1/compliance/subjects
CreateSubject records a party the org is verifying as part of its own onboarding/compliance — a team member, vendor, customer, or counterparty. The subject's contact PII (name/email) is sealed at rest and returned only to the owning org; downstream records reference the subject by opaque id.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
email | string | — | Email is the subject's contact email, sealed at rest. |
kind | string | — | Kind is the party type: "individual" (KYC) or "business" (KYB). |
name | string | — | Name is the subject's name, sealed at rest. |
ref | string | — | Ref is the org's own opaque external id for this subject. |
DecideVerification records a privileged reviewer's MANUAL decision on a verification — the human-in-the-loop path, and the ONLY route to a passing status when no real provider is wired.
POST /v1/compliance/verifications/{id}/decision
DecideVerification records a privileged reviewer's MANUAL decision on a verification — the human-in-the-loop path, and the ONLY route to a passing status when no real provider is wired. It produces a DISTINCT reviewer_confirmed, never a provider_verified (a provider decision is the provider's to report, via the webhook or a reconcile), and it is ROLE-GATED (an org admin or platform reviewer) AND ATTRIBUTED (the reviewer's user id is DecidedBy), so a manual pass is always accountable.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the verification to decide, from the path. |
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
id | string | — | ID is the verification to decide, from the path. |
status | string | — | Status is the reviewer's decision: "reviewer_confirmed" (a pass) or "manual_review" (withheld for review) — never a prov |
RefreshVerification polls the wired provider for its current decision and records it, ATTRIBUTED to the provider — the internal PULL reconcile.
POST /v1/compliance/verifications/{id}/refresh
RefreshVerification polls the wired provider for its current decision and records it, ATTRIBUTED to the provider — the internal PULL reconcile. For the Manual provider the check stays pending; for a hosted provider it reflects the provider's settled status. A poll error is a 502, never a verification.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the verification to act on, from the path. |
GetVerification returns one verification — its opaque subject reference and provider-reported status, no subject PII.
GET /v1/compliance/verifications/{id}
GetVerification returns one verification — its opaque subject reference and provider-reported status, no subject PII.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | yes | ID is the verification to act on, from the path. |
post_v1_compliance_verifications_webhook
POST /v1/compliance/verifications/webhook
ListVerifications returns the org's KYC/KYB verifications, newest first — opaque subject references and provider-reported statuses only, no subject PII.
GET /v1/compliance/verifications
ListVerifications returns the org's KYC/KYB verifications, newest first — opaque subject references and provider-reported statuses only, no subject PII.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit | query | integer | — | Limit caps the rows returned; non-positive means the server default. |
StartVerification begins a KYC/KYB verification of a subject through the wired provider — an existing subject by id, or one created inline from the request.
POST /v1/compliance/verifications
StartVerification begins a KYC/KYB verification of a subject through the wired provider — an existing subject by id, or one created inline from the request. The returned status is provider-reported and never terminal on a fresh start: starting a verification can never yield a verified record, and a provider error is a 502, never a verification.
Request body — application/json (required)
| Field | Type | Required | Description |
|---|---|---|---|
email | string | — | Email is an inline subject's contact email, sealed at rest. |
kind | string | — | Kind is an inline subject's party type: "individual" (KYC) or "business" (KYB). |
name | string | — | Name is an inline subject's name, sealed at rest. |
ref | string | — | Ref is the org's own opaque external id for an inline subject. |
subjectId | string | — | SubjectID names an existing subject to verify; empty creates one inline. |
How is this guide?