Connect
v2025-08-28Support

API Reference

Complete reference for all Cleavr Connect API endpoints.

Info

Full Specification: Download the OpenAPI Spec or view in Swagger UI for complete details.

Base URL

Command Line
https://api.cleavr.fr

Authentication

All API requests require Bearer token authentication.

http
Authorization: Bearer {access_token}
Cleavr-Version: 2025-08-28
Content-Type: application/json

Endpoints

Authentication

OAuth Authorization

Command Line
GET /oauth/authorize

Start the OAuth flow to authorize your platform.

Parameters:

  • client_id - Your platform identifier
  • redirect_uri - Callback URL
  • response_type - Must be code
  • scope - Space-separated permissions
  • state - CSRF protection token

Exchange Authorization Code

Command Line
POST /oauth/token

Exchange authorization code for access token.

Body:

  • grant_type - authorization_code or refresh_token
  • code - Authorization code (if grant_type=authorization_code)
  • refresh_token - Refresh token (if grant_type=refresh_token)
  • client_id - Your platform identifier
  • client_secret - Your platform secret

Users

Create User

Command Line
POST /v1/users

Create a new user account for recovery services.

Get Onboarding Status

Command Line
GET /v1/users/{id}/onboarding-status

Check user's KYB verification status and capabilities.

Get Requirements

Command Line
GET /v1/users/{id}/requirements

List missing documents or information needed for onboarding.

Receivables

Submit Receivable

Command Line
POST /v1/receivables

Submit an unpaid invoice for recovery.

Submit via OCR

Command Line
POST /v1/receivables/ocr

Extract invoice data from PDF and create receivable.

Body: Multipart form with PDF file

Get Receivable Status

Command Line
GET /v1/receivables/{id}

Retrieve current status and recovery progress.

Cancel Recovery

Command Line
POST /v1/receivables/{id}/cancel

Stop recovery process for a receivable.

Submit Dispute Evidence

Command Line
POST /v1/receivables/{id}/evidence

Upload documents to resolve a dispute.

Commission

Calculate Fees

Command Line
POST /v1/commission/calculate

Calculate commission for a given amount and debt age.

Body:

json
{
  "amount": 5000.00,
  "days_overdue": 60
}

Get Rate Table

Command Line
GET /v1/commission/rates

Retrieve current commission rate structure.

Webhooks

Register Endpoint

Command Line
POST /v1/webhooks

Configure a webhook endpoint to receive events.

Body:

json
{
  "url": "https://yourapp.com/webhooks/cleavr",
  "events": ["receivable.*", "user.onboarding.completed"],
  "description": "Production webhook"
}

Rotate Secret

Command Line
POST /v1/webhooks/{id}/rotate-secret

Generate new webhook signing secret for security.

Reports

Get Statistics

Command Line
GET /v1/reports/stats

Retrieve recovery performance metrics.

Query Parameters:

  • from - Start date (ISO 8601)
  • to - End date (ISO 8601)
  • user_id - Filter by specific user (optional)

Response Format

All API responses follow this structure:

Success Response

json
{
  "data": {
    // Response data
  },
  "meta": {
    "request_id": "req_xxxxx",
    "timestamp": "2025-08-28T10:00:00Z"
  }
}

Error Response

json
{
  "error": {
    "code": "MISSING_EMAIL_CONTACT",
    "message": "At least one contact with email is required",
    "details": {
      "field": "debtor.contacts",
      "received": []
    }
  },
  "meta": {
    "request_id": "req_xxxxx",
    "timestamp": "2025-08-28T10:00:00Z"
  }
}

Rate Limits

TierRequests/MinuteRequests/Hour
Standard1003,000
Receivables50/min-
OCR10/min-

Rate limit headers are included in every response:

Command Line
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Further Documentation