Cleavr Connect API Documentation

Overview

Cleavr Connect enables platforms to seamlessly integrate professional debt recovery services into their existing workflows. Your users can send unpaid invoices to recovery without leaving your platform, while you maintain control over the user experience.

Why Cleavr Connect?

• Quick integration: Get up and running in days, not months
• Outcome-based pricing: Pay only when debts are recovered
• Compliance baked in: KYB, AML, and GDPR handled automatically
• Real-time updates: Webhooks keep you informed at every step
• Co-branded experience: Maintain trust with your brand alongside ours

How It Works

Integration Models

// Initialize Cleavr Connect
const cleavr = new CleavrConnect({
  clientId: process.env.CLEAVR_CLIENT_ID,
  clientSecret: process.env.CLEAVR_CLIENT_SECRET
});

// Launch hosted onboarding
const onboardingUrl = await cleavr.users.getOnboardingUrl(userId);

// Hand off receivables with one API call
await cleavr.receivables.create({
  amount: 1500,
  currency: 'EUR',
  debtor: { email: 'debtor@company.com' }
});

Commission Structure

Our commission is success-based and varies by debt age:

Quick Start

1. Get Your Credentials

After approval, you'll receive:

• client_id: Your platform identifier
• client_secret: Your secret key (keep secure!)
• webhook_secret: For validating webhook signatures

2. Set Up OAuth

// Redirect users to authorize
const authUrl = cleavr.oauth.getAuthorizationUrl({
  redirectUri: 'https://yourapp.com/callback',
  state: 'unique_session_id'
});

// Exchange code for token
const token = await cleavr.oauth.exchangeCode(code);

3. Create User & Start Recovery

// Create user with prefilled data
const user = await cleavr.users.create({
  email: 'user@company.com',
  company: {
    name: 'ACME Corp',
    siret: '123456789'
  }
});

// User completes KYB via hosted flow
const onboardingUrl = await cleavr.users.getOnboardingUrl(user.id);

// Submit receivable
const receivable = await cleavr.receivables.create({
  userId: user.id,
  invoice: {
    number: 'INV-001',
    amount: 1500.00,
    dueDate: '2025-08-15'
  },
  debtor: {
    name: 'Debtor Company',
    email: 'accounting@debtor.com',
    phone: '+33612345678'
  }
});

Key Concepts

Platform vs User Accounts

• Platform Account: Your organization's account for API access
• User Account: Your customers' accounts for recovery services

Receivable Lifecycle

pending → in_process → recovered
                    ↘ disputed
                    ↘ cancelled

Contact Requirements

• Email: Required (blocks submission without it)
• Phone: Recommended (Increased success rate)
• Multiple Contacts: Supported with priority levels

Implementation Checklist

Track your integration progress with this comprehensive checklist:

Phase 1: Platform Setup

• [ ] Register via partner form
• [ ] Receive OAuth credentials (client_id, client_secret)
• [ ] Configure webhook endpoint
• [ ] Implement signature verification

Phase 2: Authentication

• [ ] OAuth authorization flow
• [ ] Token storage and refresh
• [ ] Error handling
• [ ] Security measures (PKCE, state parameter)

Phase 3: User Management

• [ ] User creation with prefilling
• [ ] Onboarding URL handling
• [ ] Callback processing
• [ ] Status checking

Phase 4: Recovery Operations

• [ ] Receivable submission
• [ ] Contact validation
• [ ] OCR integration (optional)
• [ ] Dispute handling

Phase 5: Monitoring

• [ ] Webhook processing
• [ ] Event handling by type
• [ ] Status tracking
• [ ] Reporting integration

Support

• Documentation: docs.cleavr.fr/connect
• Technical Support: platform@cleavr.fr
• Sales: Contact form

API Versioning

We use date-based versioning. Set the API version via the Cleavr-Version header:

Cleavr-Version: 2025-08-28

Building with LLMs? Check our LLM Export for structured API schemas.