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.

The user resolves the open request after they resubmit the corrected data. See KYC action request fulfillment.

{
  "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

A reviewer decision returns two classes of error, and your retry logic should treat them differently. A terminal error means the request or the version state is wrong, so a blind retry fails the same way. An operational write failure means the decision passed validation but an internal write did not complete. These are marked non-retryable, so do not resend the same call automatically.

Terminal request errors

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

Operational write failures

These return HTTP 500 after the decision passed validation: DALP completed the state-transition check, then a database write returned no result. The error envelope marks these as non-retryable, so do not resend the same call automatically. Escalate with the request ID and the version ID rather than changing the payload. Each code names the exact write that did not complete, so a stalled review is traceable to a single operation for your audit trail.

Related

• Manage KYC data
• KYC action request fulfillment
• KYC document uploads
• Verify KYC
• Platform API error reference