Choose the right integration path
| Path | Use it for | Preserved provenance |
|---|---|---|
| Partner API | A loan-origination, merchant or case system opening a governed case. | Credential, request ID, policy snapshot and integration actor |
| LMS or lending gateway | An LMS or lending gateway exchanges application stages, policy results, exceptions and reviewed dispositions. | Application reference, event ID, source stage, callback status and payload hash |
| Signed webhook | A risk, fraud, screening or transaction-monitoring provider sending an event. | Provider, event ID, signature, timestamp and payload hash |
| Document upload | Evidence already held by an authorized analyst or submitted through the portal. | Filename, media type, size, file hash, case and uploader |
| Web citation | An observation from an approved official or public-business page. | URL, exact excerpt, collector, observation time and hash |
Open a case through the Partner API
- 1
Create one credential per system and environment
An administrator selects allowed workflows, scopes and expiry, then copies the secret once into a managed secret store.
- 2
Send a stable idempotency key
Generate one durable value for the logical business operation. Reuse it after a timeout; do not create a new value for the retry.
- 3
Record the request identifier
Store X-Clarivy-Request-Id with the source-system event for support and reconciliation.
- 4
Treat the response as a governed case reference
The case contains the policy snapshot and audit actor; it is not an automated lending, recovery or compliance decision.
Request example
cURL
curl --request POST \
'https://app.clarivy.pro/api/integrations/v1/cases' \
--header 'Authorization: Bearer <service-key>' \
--header 'Idempotency-Key: <stable-unique-request-id>' \
--header 'Content-Type: application/json' \
--data '{
"reference": "LOS-2026-000184",
"title": "Merchant lending eligibility review",
"purpose": "Assess the merchant against approved SME lending controls.",
"use_case": "merchant_eligibility",
"subject_name": "Example Merchant LLC",
"subject_type": "legal_entity",
"legal_basis": "contract_performance",
"jurisdiction": "AE",
"retention_days": 180
}'Response
{
"request_id": "0f635ea8-3cb3-4be1-8b7f-ff6eb3fcb889",
"idempotent_replay": false,
"case": {
"id": "4d135a11-f817-4272-9ef8-66ea48808193",
"reference": "LOS-2026-000184",
"owner": "Integration: Loan origination system",
"policy_name": "Merchant eligibility evidence policy",
"policy_version": 3,
"policy_status_at_open": "published"
}
}Credential lifecycle
| Stage | Required control |
|---|---|
| Create | Admin-only; least-privilege action and workflow scopes. |
| Deliver | One-time display into the customer secret manager. |
| Store | Hash in Clarivy; encrypted secret in the calling platform. |
| Use | TLS, bearer header, idempotency key and bounded request size. |
| Observe | Last-used time, request identifier, audit actor and anomaly alerts. |
| Rotate | Deploy a replacement, verify use, then revoke the old key. |
| Revoke | Immediate server-side rejection without redeploying the caller. |
Partner API capability map
| Capability | Route | Required scope |
|---|---|---|
| Create a governed case | POST /integrations/v1/cases | case.create + approved use-case scope |
| List or inspect cases | GET /integrations/v1/cases · GET /cases/{case_id} | case.read |
| Add a source-cited finding | POST /cases/{case_id}/evidence | evidence.write |
| Upload and extract a document | POST /cases/{case_id}/documents | evidence.write |
| Read policy-bound document options | GET /cases/{case_id}/document-request-options | request.write |
| Create or inspect secure document requests | POST or GET /cases/{case_id}/document-requests | request.write or case.read |
| Retrieve source and decision lineage | GET /cases/{case_id}/lineage | case.read |
| Export the signed verification bundle | GET /cases/{case_id}/verification-bundle | bundle.read |
Human decision boundary
Partner integrations can supply facts, documents and provider signals, and they can retrieve the resulting controlled record. They cannot approve, reject or silently change a material outcome. Those actions remain on the authenticated reviewer surface with a named human owner.
Connector presets
| Connector | Clarivy role | Availability meaning |
|---|---|---|
| Generic signed webhook | Receive customer risk, fraud, credit, recovery or monitoring events. | Preset requires tenant mapping and certification. |
| Lending middleware / LOS gateway | Receive application, knockout, stage and manual-review events; return a reviewed disposition. | Customer API mapping and end-to-end certification required. |
| Sumsub | Receive KYC, KYB, AML and monitoring outcomes. | Public contract mapped; customer licence and credentials required. |
| ComplyAdvantage | Receive screening, monitoring and KYB updates. | Gateway hardening and provider controls required. |
| SEON | Receive fraud, AML and identity events. | Preset does not imply an active provider connection. |
| Alloy | Receive Journey, evaluation and step-up workflow events. | Tenant-specific event mapping is required. |
| Stripe Radar | Receive review, fraud-warning and dispute events. | Provider event remains a signal until reviewed. |
| UAE FIU open data | Preserve official publication versions and controlled citations. | Monitoring does not create merchant-specific evidence automatically. |
Connector boundary
A connector preset is not a licence, production certification or guarantee of source accuracy. No connector can bypass tenant isolation, case authority, evidence review or the customer’s final decision ownership.
Continue reading
Interactive API reference
Explore the live OpenAPI schema, operation details and generated examples.