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

​
Overview

This endpoint returns a paginated list of all debts issued by a specific creditor. You can filter and search 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

​
Path Parameters

​
creditorId
string
required
The encrypted creditor ID

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

​
Example Request

curl -X GET "/external-api/v1/debts/by-creditor/abc123def456?page=1&limit=50&status=active" \
  -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": "xyz789abc123",
      "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": "abc123def456",
      "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": []
    }
  ],
  "pagination": {
    "total": 87,
    "page": 1,
    "limit": 50,
    "pages": 2
  }
}

​
Error Responses

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

​
Rate Limiting

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