{"openapi":"3.1.0","info":{"title":"Clarivy Partner API","version":"1.0.0","description":"Open a purpose-bound legal-entity case from an approved external system. Clarivy derives tenant and actor authority from a scoped service credential, binds the active policy, and makes retries safe with a required idempotency key.","contact":{"name":"Clarivy integration support","url":"https://clarivy.pro/contact"}},"servers":[{"url":"/clarivio/api","description":"Clarivy API"}],"tags":[{"name":"Partner case intake","description":"Create governed legal-entity cases. The service credential must include case.create and the requested use-case scope."}],"paths":{"/integrations/v1/cases":{"post":{"tags":["Partner case intake"],"summary":"Create a governed case","description":"Creates one purpose-bound legal-entity case using the tenant and actor authority attached to the service credential. Send a unique Idempotency-Key for every logical request; replaying the same key and payload returns the original case without creating a duplicate.","operationId":"createGovernedCase","security":[{"HTTPBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":8,"maxLength":255},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalCaseCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalCaseCreateResponse"}}}},"400":{"description":"The required Idempotency-Key header is missing."},"401":{"description":"The service credential is invalid, expired, or revoked."},"403":{"description":"The credential lacks the required scope."},"409":{"description":"The idempotency key conflicts or is still processing."},"422":{"description":"The request body failed contract validation."}}}}},"components":{"schemas":{"ApplicationChannel":{"type":"string","enum":["internal","direct","partner","api"],"title":"ApplicationChannel"},"ApplicationContext":{"properties":{"merchant_reference":{"anyOf":[{"type":"string","maxLength":120,"minLength":3},{"type":"null"}],"title":"Merchant Reference"},"application_type":{"$ref":"#/components/schemas/ApplicationType","default":"onboarding"},"product_references":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Product References"},"requested_change":{"anyOf":[{"type":"string","maxLength":600},{"type":"null"}],"title":"Requested Change"},"source_channel":{"$ref":"#/components/schemas/ApplicationChannel","default":"internal"},"communication_locale":{"$ref":"#/components/schemas/CommunicationLocale","default":"en"},"contact_name":{"anyOf":[{"type":"string","maxLength":160,"minLength":2},{"type":"null"}],"title":"Contact Name"},"contact_email":{"anyOf":[{"type":"string","maxLength":254,"minLength":5},{"type":"null"}],"title":"Contact Email"},"contact_phone":{"anyOf":[{"type":"string","maxLength":40,"minLength":5},{"type":"null"}],"title":"Contact Phone"},"identifiers":{"additionalProperties":{"type":"string"},"type":"object","title":"Identifiers"}},"type":"object","title":"ApplicationContext","description":"Application facts kept separate from the reusable legal-entity profile."},"ApplicationType":{"type":"string","enum":["onboarding","product_addition","limit_change","material_change","periodic_review","due_diligence","recovery","investigation"],"title":"ApplicationType","description":"The business change being reviewed in one independent application."},"CaseRecord":{"properties":{"reference":{"type":"string","maxLength":80,"minLength":3,"title":"Reference"},"title":{"type":"string","maxLength":160,"minLength":3,"title":"Title"},"purpose":{"type":"string","maxLength":600,"minLength":10,"title":"Purpose"},"use_case":{"$ref":"#/components/schemas/InvestigationUseCase"},"subject_name":{"type":"string","maxLength":200,"minLength":2,"title":"Subject Name"},"subject_type":{"type":"string","title":"Subject Type","default":"legal_entity"},"legal_basis":{"$ref":"#/components/schemas/LegalBasis"},"jurisdiction":{"type":"string","maxLength":10,"minLength":2,"title":"Jurisdiction","default":"AE"},"owner":{"type":"string","maxLength":120,"minLength":2,"title":"Owner"},"retention_days":{"type":"integer","maximum":2555,"minimum":30,"title":"Retention Days","default":180},"application":{"$ref":"#/components/schemas/ApplicationContext"},"id":{"type":"string","title":"Id"},"status":{"$ref":"#/components/schemas/CaseStatus"},"policy_configuration_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policy Configuration Id"},"policy_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policy Name"},"policy_version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Policy Version"},"policy_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policy Hash"},"policy_status_at_open":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Policy Status At Open"},"processing_restricted":{"type":"boolean","title":"Processing Restricted","default":false},"restriction_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Restriction Reason"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"}},"type":"object","required":["reference","title","purpose","use_case","subject_name","legal_basis","owner","id","status","created_at","updated_at","expires_at"],"title":"CaseRecord"},"CaseStatus":{"type":"string","enum":["draft","active","in_review","closed"],"title":"CaseStatus"},"CommunicationLocale":{"type":"string","enum":["en","zh-Hans","fr","es","de"],"title":"CommunicationLocale"},"ExternalCaseCreate":{"properties":{"reference":{"type":"string","maxLength":80,"minLength":3,"title":"Reference","description":"Stable case reference from the calling system.","examples":["LOS-2026-00184"]},"title":{"type":"string","maxLength":160,"minLength":3,"title":"Title","description":"Short human-readable case title.","examples":["Merchant eligibility review"]},"purpose":{"type":"string","maxLength":600,"minLength":10,"title":"Purpose","description":"Approved business purpose for opening the evidence case.","examples":["Assess this merchant against the approved SME lending policy."]},"use_case":{"$ref":"#/components/schemas/InvestigationUseCase","description":"Clarivy workflow family that controls the applicable policy."},"subject_name":{"type":"string","maxLength":200,"minLength":2,"title":"Subject Name","description":"Registered or supplied legal-entity name.","examples":["Example Trading LLC"]},"subject_type":{"type":"string","title":"Subject Type","description":"Only legal_entity is accepted by the Partner API.","default":"legal_entity","examples":["legal_entity"]},"legal_basis":{"$ref":"#/components/schemas/LegalBasis","description":"Approved legal basis recorded with the case."},"jurisdiction":{"type":"string","maxLength":10,"minLength":2,"title":"Jurisdiction","description":"ISO country or approved jurisdiction code.","default":"AE","examples":["AE"]},"retention_days":{"type":"integer","maximum":2555,"minimum":30,"title":"Retention Days","description":"Requested retention period, subject to tenant policy.","default":180,"examples":[180]},"application":{"$ref":"#/components/schemas/ApplicationContext","description":"Application-specific context such as product references and requested change. Clarivy keeps this separate from reusable merchant facts."}},"type":"object","required":["reference","title","purpose","use_case","subject_name","legal_basis"],"title":"ExternalCaseCreate","description":"Public case intake contract; authority fields are server-derived."},"ExternalCaseCreateResponse":{"properties":{"request_id":{"type":"string","title":"Request Id","description":"Clarivy correlation identifier returned in the response header."},"idempotent_replay":{"type":"boolean","title":"Idempotent Replay","description":"True when the response is a safe replay of an earlier request."},"case":{"$ref":"#/components/schemas/CaseRecord","description":"The governed case created by Clarivy."}},"type":"object","required":["request_id","idempotent_replay","case"],"title":"ExternalCaseCreateResponse"},"InvestigationUseCase":{"type":"string","enum":["corporate_recovery","corporate_due_diligence","merchant_eligibility","aml_cft","payment_fraud"],"title":"InvestigationUseCase"},"LegalBasis":{"type":"string","enum":["contract_performance","legal_claim","regulatory_obligation","legitimate_interest_reviewed"],"title":"LegalBasis"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}