KYC & Compliance

Overview

This skill enables AI agents and applications to check and manage KYC (Know Your Customer) verification status for Eclipse customers.

It supports:

• Retrieving current KYC verification status and individual check results
• Triggering or re-triggering KYC ratification
• Interpreting PASSED, FAILED, and PENDING states for operator action

KYC verification in Eclipse is called ratification. Ratification checks may include identity verification, liveness detection, and sanctions screening — the specific checks performed depend on the KYC provider configured for the tenant.

1. Get KYC Status

Trigger: "check KYC", "KYC status", "verify customer identity", "is the customer verified"

Required inputs: tenantId, customerId

GET {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/ratify
Authorization: Bearer {jwt}

Returns a list of EclipseKycResult objects, most recent first. Pass offset=0&limit=1 for the latest result only.

Response — PASSED:

[
  {
    "status": "PASSED",
    "lastModified": "2026-05-19T08:30:20.000Z",
    "sanctionsListCheck": { "checked": true, "passed": true, "pending": false },
    "selfieMatchesNationalIdentity": { "checked": true, "passed": true, "pending": false },
    "nationalIdentityIsLegitimate": { "checked": true, "passed": true, "pending": false }
  }
]

Response — FAILED:

[
  {
    "status": "FAILED",
    "lastModified": "2026-05-19T08:30:20.000Z",
    "sanctionsListCheck": { "checked": true, "passed": false, "pending": false, "comment": "Match found on OFAC list" },
    "selfieMatchesNationalIdentity": { "checked": true, "passed": true, "pending": false }
  }
]

Each check field (e.g. sanctionsListCheck, selfieMatchesNationalIdentity, identityNumberMatchesNationalIdentity) contains checked (was this check run?), passed (did it pass?), pending (still in progress?), and optionally score and comment.

Notes

• PASSED — customer fully verified; no action needed.
• FAILED — review individual check fields where passed=false. Common causes: ID mismatch, name mismatch, sanctions hit, poor document quality.
• PENDING at the result level or on individual checks — verification is still in progress; poll after 30–60 seconds.
• Sanctions check failures must be escalated to a compliance officer; do not clear them via API alone.

API Reference: GET /customers/{customerId}/ratify · POST /customers/{customerId}/ratify

2. Trigger KYC Ratification

Trigger: "ratify user", "run KYC", "re-verify customer"

Required inputs: tenantId, customerId

POST {baseUrl}/eclipse-conductor/rest/v1/tenants/{tenantId}/customers/{customerId}/ratify
Authorization: Bearer {jwt}
Content-Type: application/json

{}

Request body may be empty ({}) to run the default check set, or include type (NORMAL or COMPARISON) and checksToRun to limit which checks are executed.

Response: A single EclipseKycResult object with individual check fields, status, and lastModified.

After submitting, poll GET .../ratify?offset=0&limit=1 every 30–60 seconds until the top-level status is no longer PENDING.

Expected output: State the overall status. For FAILED or PENDING, list each failing check with its description so the operator knows what to address.

Common Patterns for AI Agents

1. KYC Status Check Flow

1. Get KYC status
2. PASSED — no action needed; report to operator
3. PENDING — advise operator to check back in 30–60 seconds
4. FAILED — list each failed check with its description; escalate any sanctions failures to compliance

2. Re-Ratification Flow

Use only when:

• The customer has updated their identity documents
• A previous FAILED attempt had a correctable cause (e.g. name mismatch now resolved)
• Explicitly instructed by an authorised operator

Warning: Re-triggering on a PASSED customer restarts the KYC process. The customer becomes PENDING again until verification completes.

Error Handling

[
  {
    "type": "BUSINESS",
    "severity": "LOW",
    "description": "KYC ratification already in progress",
    "code": "KYC001",
    "traceId": "3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d",
    "spanId": "1a2b3c4d5e6f7a8b",
    "environment": "eclipse-sandbox"
  }
]

Best Practices

• Never re-trigger KYC on a PASSED customer without explicit operator instruction.
• Escalate all sanctions check failures to a compliance officer immediately; do not attempt to clear them programmatically.
• Always state the individual check results when reporting a FAILED status — the top-level status alone is insufficient for diagnosis.
• Apply a 30–60 second polling interval for PENDING status; verification involves external providers and polling faster provides no benefit.
• When a traceId is returned in an error, record it and reference it in any support escalation.