KYC reviewer version actions

A reviewer decides the outcome of a KYC profile version that is under review. Three decisions are available: approve the version, reject it, or request changes from the user. Each decision is a single Platform API call against the version ID and returns the updated review metadata.

These endpoints operate only on a version whose status is under_review. Submit a draft version for review first, then call one of the endpoints below. For the operator walkthrough in the Console, see Manage KYC data.

Prerequisites

• The caller holds the claimIssuer or identityManager system role.
• The target version status is under_review. The caller cannot review a draft, approved, or rejected version.

Choose a review decision

Direct HTTP integrations use these routes:

• Approve: POST /api/v2/kyc-profile-versions/{versionId}/approvals.
• Reject: POST /api/v2/kyc-profile-versions/{versionId}/rejections.
• Request update: POST /api/v2/kyc-profile-versions/{versionId}/update-requests.

Approve a version

Approving moves the version to approved and points the user's KYC profile at that version. DALP records the review outcome, review timestamp, and reviewer, syncs the approved name fields on the profile, and closes any open pending requests for that user's KYC profile.

const approved = await client.user.kyc.version.approve({
  params: { versionId: "kycv_01hzt7n4submittedversion" },
  body: {
    reviewNotes: "ID and proof of address verified against the form fields.",
  },
});

reviewNotes is optional. Depending on your organization's configuration these notes may be visible to the user, so keep internal-only detail out of them.

{
  "data": {
    "id": "kycv_01hzt7n4submittedversion",
    "status": "approved",
    "reviewOutcome": "approved",
    "reviewedAt": "2026-05-24T10:23:17.628Z",
    "reviewedBy": "usr_01hzt7n4reviewer001",
    "reviewNotes": "ID and proof of address verified against the form fields."
  }
}

After approval, issue the on-chain KYC verification. See Verify KYC.

Reject a version

Rejecting moves the version to rejected and records the rejection reason, reviewer, and review timestamp. The rejection reason is shown to the user, so state clearly what was wrong. If the user already has a previously approved version, that approved version stays active; otherwise the profile returns to incomplete.

const rejected = await client.user.kyc.version.reject({
  params: { versionId: "kycv_01hzt7n4submittedversion" },
  body: {
    rejectionReason: "Proof of address document is expired. Upload a statement from the last 3 months.",
    reviewNotes: "Utility bill dated 14 months ago.",
  },
});

rejectionReason requires at least 10 characters. reviewNotes is optional internal context.

{
  "data": {
    "id": "kycv_01hzt7n4submittedversion",
    "status": "rejected",
    "reviewOutcome": "rejected",
    "rejectionReason": "Proof of address document is expired. Upload a statement from the last 3 months.",
    "reviewedAt": "2026-05-24T10:25:02.114Z",
    "reviewedBy": "usr_01hzt7n4reviewer001"
  }
}

Request an update

Requesting an update keeps the version under_review with a review outcome of changes_requested, creates an open change request for the user, and marks the profile as needing an update. DALP creates the draft the user edits when they open the update flow, not from this call.

const updateRequest = await client.user.kyc.version.requestUpdate({
  params: { versionId: "kycv_01hzt7n4submittedversion" },
  body: {
    reason: "Add a proof of address document from the last 3 months.",
    requiredFields: ["proof_of_address"],
    dueAt: "2026-06-01T00:00:00.000Z",
  },
});

reason requires at least 10 characters. requiredFields and dueAt are optional. reviewNotes is optional; when omitted, DALP uses the reason as the review note.

{
  "data": {
    "version": {
      "id": "kycv_01hzt7n4submittedversion",
      "status": "under_review"
    },
    "actionRequest": {
      "id": "kycar_01hzt7n4openrequest001",
      "status": "open",
      "reason": "Add a proof of address document from the last 3 months.",
      "requiredFields": ["proof_of_address"],
      "dueAt": "2026-06-01T00:00:00.000Z",
      "requestedAt": "2026-05-24T10:26:40.902Z"
    }
  }
}

State transitions

CLI equivalents

The DALP CLI exposes the same reviewer decisions for operator scripts. Use these commands when a back-office job is easier to run outside the SDK:

Validation and error handling

Treat reviewer errors as terminal request errors unless the response says otherwise. Confirm the version status and your reviewer role before retrying. Store the request ID from the API response when you escalate a repeated platform error.

Related

• Manage KYC data
• KYC document uploads
• Verify KYC
• Platform API error reference