GET
/
external-api
/
v1
/
debts
List Debts
curl --request GET \
  --url https://getbill.io/external-api/v1/debts \
  --header 'Authorization: <authorization>'
{
  "error": false,
  "data": [
    {
      "id": "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": "xyz789abc123",
      "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,
      "contacts": []
    },
    {
      "id": "xyz789ghi012",
      "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,
      "contacts": []
    }
  ],
  "pagination": {
    "total": 1247,
    "page": 1,
    "limit": 50,
    "pages": 25
  }
}

​
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.

​
Request

​
Authorization
string
required
Bearer token for authentication

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination (starts at 1)
​
limit
integer
default:"20"
Number of items per page (maximum 100)
​
status
string
Filter by debt status (e.g., “active”, “paid”, “disputed”)
​
currency
string
Filter by currency code (e.g., “EUR”, “USD”)
​
amount_min
number
Minimum debt amount filter
​
amount_max
number
Maximum debt amount filter
​
created_after
string
Filter debts created after this date (ISO 8601 format)
​
created_before
string
Filter debts created before this date (ISO 8601 format)
​
search
string
Search in internal_id or amount_text. Note: Due to encryption, firstname, lastname, phone, and email cannot be searched via this parameter.

​
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"

​
Response

​
error
boolean
Always false for successful requests
​
data
array
Array of debt objects
​
pagination
object
Pagination metadata

​
Success Response

{
  "error": false,
  "data": [
    {
      "id": "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": "xyz789abc123",
      "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,
      "contacts": []
    },
    {
      "id": "xyz789ghi012",
      "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,
      "contacts": []
    }
  ],
  "pagination": {
    "total": 1247,
    "page": 1,
    "limit": 50,
    "pages": 25
  }
}

​
Error Responses

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

​
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.