List Debts

{
  "error": false,
  "data": [
    {
      "id": "abc123def456",
      "grouped": false,
      "group_debt_ids": ["abc123def456"],
      "civility": "Mr",
      "firstname": "John",
      "lastname": "Doe",
      "phone": "+33123456789",
      "email": "john.doe@example.com",
      "birthdate": "1985-03-15",
      "amount": 1250.00,
      "amount_text": "1250.00",
      "currency": "EUR",
      "object": "Outstanding invoice #INV-2024-001",
      "internal_id": "DEBT-2024-001",
      "invoice_reference": "INV-2024-001",
      "debtor_reference": "DEB-DOE-001",
      "invoice_date": "2023-12-01",
      "due_date": "2023-12-31",
      "address": "123 Main Street, 75001 Paris, France",
      "street_address": "Main Street",
      "street_number": "123",
      "postal_code": "75001",
      "city": "Paris",
      "country": "FR",
      "status": "status.default.in_progress",
      "timeline_id": "YOUR_TIMELINE_ID",
      "nb_reminders": 3,
      "nb_answered": 1,
      "summary": "Customer acknowledged debt, payment plan in discussion",
      "iban": "FR1420041010050500013M02606",
      "followups_count": 5,
      "company": "Acme Corp",
      "debtor_company": null,
      "payment_link": null,
      "import_date": "2024-01-15T10:30:00+00:00",
      "last_timeline_restart": "2024-01-15T10:30:00+00:00",
      "payment_plan_active": false,
      "plan_start_date": null
    },
    {
      "id": "xyz789ghi012",
      "grouped": true,
      "group_debt_ids": ["xyz789ghi012", "abc111bbb222"],
      "civility": "Ms",
      "firstname": "Jane",
      "lastname": "Smith",
      "phone": "+33987654321",
      "email": "jane.smith@example.com",
      "birthdate": "1990-07-22",
      "amount": 750.50,
      "amount_text": "750.50",
      "currency": "EUR",
      "object": "Service contract violation",
      "internal_id": "DEBT-2024-002",
      "invoice_reference": "INV-2024-002",
      "debtor_reference": null,
      "invoice_date": "2023-11-15",
      "due_date": "2023-12-15",
      "address": null,
      "street_address": "Oak Avenue",
      "street_number": "456",
      "postal_code": "69001",
      "city": "Lyon",
      "country": "FR",
      "status": "status.default.pending",
      "timeline_id": null,
      "nb_reminders": 2,
      "nb_answered": 0,
      "summary": null,
      "iban": "FR1420041010050500013M02606",
      "followups_count": 3,
      "company": "Service Plus SARL",
      "debtor_company": "Tech Solutions Inc",
      "payment_link": "https://pay.example.com/xyz789",
      "import_date": "2024-01-10T09:15:00+00:00",
      "last_timeline_restart": null,
      "payment_plan_active": false,
      "plan_start_date": null
    }
  ],
  "pagination": {
    "total": 1247,
    "page": 1,
    "limit": 50,
    "pages": 25
  }
}

{
  "error": true,
  "message": "Invalid filter parameter",
  "code": 400,
  "details": {
    "amount_min": ["Must be a valid number"]
  }
}

{
  "error": true,
  "message": "Authentication credentials are missing or invalid",
  "code": 401
}

{
  "error": true,
  "message": "Required scope \"debts:read\" not found in token",
  "code": 403
}

Overview

This endpoint returns a paginated list of debts belonging to the authenticated company. You can filter, search, and sort the results using query parameters.

Authentication

Requires a valid OAuth 2.0 access token with the debts:read scope.

Example Request

curl -X GET "/external-api/v1/debts?page=1&limit=50&status=active&amount_min=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

const params = new URLSearchParams({
  page: '1',
  limit: '50',
  status: 'active',
  amount_min: '100'
});

const response = await fetch(`/external-api/v1/debts?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  }
});

const debts = await response.json();

import requests

params = {
    'page': 1,
    'limit': 50,
    'status': 'active',
    'amount_min': 100
}

headers = {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

response = requests.get(
    '/external-api/v1/debts',
    headers=headers,
    params=params
)

debts = response.json()

Example Response

{
  "error": false,
  "data": [
    {
      "id": "abc123def456",
      "grouped": false,
      "group_debt_ids": ["abc123def456"],
      "civility": "Mr",
      "firstname": "John",
      "lastname": "Doe",
      "phone": "+33123456789",
      "email": "john.doe@example.com",
      "birthdate": "1985-03-15",
      "amount": 1250.00,
      "amount_text": "1250.00",
      "currency": "EUR",
      "object": "Outstanding invoice #INV-2024-001",
      "internal_id": "DEBT-2024-001",
      "invoice_reference": "INV-2024-001",
      "debtor_reference": "DEB-DOE-001",
      "invoice_date": "2023-12-01",
      "due_date": "2023-12-31",
      "address": "123 Main Street, 75001 Paris, France",
      "street_address": "Main Street",
      "street_number": "123",
      "postal_code": "75001",
      "city": "Paris",
      "country": "FR",
      "status": "status.default.in_progress",
      "timeline_id": "YOUR_TIMELINE_ID",
      "nb_reminders": 3,
      "nb_answered": 1,
      "summary": "Customer acknowledged debt, payment plan in discussion",
      "iban": "FR1420041010050500013M02606",
      "followups_count": 5,
      "company": "Acme Corp",
      "debtor_company": null,
      "payment_link": null,
      "import_date": "2024-01-15T10:30:00+00:00",
      "last_timeline_restart": "2024-01-15T10:30:00+00:00",
      "payment_plan_active": false,
      "plan_start_date": null
    },
    {
      "id": "xyz789ghi012",
      "grouped": true,
      "group_debt_ids": ["xyz789ghi012", "abc111bbb222"],
      "civility": "Ms",
      "firstname": "Jane",
      "lastname": "Smith",
      "phone": "+33987654321",
      "email": "jane.smith@example.com",
      "birthdate": "1990-07-22",
      "amount": 750.50,
      "amount_text": "750.50",
      "currency": "EUR",
      "object": "Service contract violation",
      "internal_id": "DEBT-2024-002",
      "invoice_reference": "INV-2024-002",
      "debtor_reference": null,
      "invoice_date": "2023-11-15",
      "due_date": "2023-12-15",
      "address": null,
      "street_address": "Oak Avenue",
      "street_number": "456",
      "postal_code": "69001",
      "city": "Lyon",
      "country": "FR",
      "status": "status.default.pending",
      "timeline_id": null,
      "nb_reminders": 2,
      "nb_answered": 0,
      "summary": null,
      "iban": "FR1420041010050500013M02606",
      "followups_count": 3,
      "company": "Service Plus SARL",
      "debtor_company": "Tech Solutions Inc",
      "payment_link": "https://pay.example.com/xyz789",
      "import_date": "2024-01-10T09:15:00+00:00",
      "last_timeline_restart": null,
      "payment_plan_active": false,
      "plan_start_date": null
    }
  ],
  "pagination": {
    "total": 1247,
    "page": 1,
    "limit": 50,
    "pages": 25
  }
}

{
  "error": true,
  "message": "Invalid filter parameter",
  "code": 400,
  "details": {
    "amount_min": ["Must be a valid number"]
  }
}

{
  "error": true,
  "message": "Authentication credentials are missing or invalid",
  "code": 401
}

{
  "error": true,
  "message": "Required scope \"debts:read\" not found in token",
  "code": 403
}

Rate Limiting

This endpoint is subject to rate limiting. See the Rate Limits documentation for details. Rate Limit: 1,000 requests per hour

Usage Examples

Filter by Amount Range

curl -X GET "/external-api/v1/debts?amount_min=500&amount_max=2000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Search for Specific Debtor

curl -X GET "/external-api/v1/debts?search=john.doe@example.com" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Recent Debts

curl -X GET "/external-api/v1/debts?created_after=2024-01-01&limit=100" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Pagination

This endpoint supports pagination. See the Pagination documentation for detailed information on navigating through large result sets.

Get Single Debt - Get detailed information about a specific debt
Create Debt - Create a new debt
Update Debt - Update an existing debt
List Followups by Debt - Get followups for a specific debt

Get started

Guides

SFTP integration

Company API

Creditors API

Debtors API

Debts API

Timelines API

Campaigns API

Settings API

Invoice documents API

Followups API

Todos API

Status API

Overview

Authentication

Example Request

Example Response

Rate Limiting

Usage Examples

Filter by Amount Range

Search for Specific Debtor

Get Recent Debts

​Overview

​Authentication

​Example Request

​Example Response

​Rate Limiting

​Usage Examples

​Filter by Amount Range

​Search for Specific Debtor

​Get Recent Debts

​Pagination

​Related Endpoints

Overview

Authentication

Example Request

Example Response

Rate Limiting

Usage Examples

Filter by Amount Range

Search for Specific Debtor

Get Recent Debts

Pagination

Related Endpoints