KYC reviewer version actions

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

These endpoints act only on a version whose status is under_review. Submit a draft version for review first, then call one of the actions 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. A draft, approved, or rejected version cannot be actioned.

Choosing an action

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 action 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 is required and must be 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 action request for the user, and marks the profile as needing an update. The draft the user edits is created when they open the update flow, not by 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 is required and must be 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 actions for operator scripts:

Validation and error handling

Treat reviewer action 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