List 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
  }
}

GET

external-api

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)

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

Show debt object

string

Encrypted debt identifier

civility

string

Civility/title (e.g., “Mr”, “Ms”)

firstname

string

Debtor’s first name

lastname

string

Debtor’s last name

phone

string

Debtor’s phone number (E.164 format)

string

Debtor’s email address

birthdate

string

Debtor’s birth date (YYYY-MM-DD format)

amount

number

Debt amount

amount_text

string

Debt amount as text

currency

string

Currency code (e.g., “EUR”, “USD”)

object

string

Description of the debt object/reason

internal_id

string

Your internal reference ID for this debt

invoice_reference

string

Invoice reference number

debtor_reference

string

Your reference for the debtor

invoice_date

string

Original invoice date (YYYY-MM-DD format)

due_date

string

Payment due date (YYYY-MM-DD format)

address

string

Full address (legacy field)

street_address

string

Street name and type

street_number

string

Street number

postal_code

string

Postal/ZIP code

city

string

City name

country

string

Country code or name

status

string

Current debt status (read-only)

timeline_id

string

Encrypted timeline ID associated with this debt

nb_reminders

integer

Number of reminders sent

nb_answered

integer

Number of responses received

summary

string

Brief summary or notes about the debt

iban

string

IBAN for payment

followups_count

integer

Number of followups for this debt

company

string

Creditor company name (only present for debt collection agencies collecting on behalf of other companies)

debtor_company

string

Debtor’s company name (for B2B debts)

payment_link

string

Custom payment link URL

import_date

string

Creation/import timestamp (ISO 8601 format). Read-only.

last_timeline_restart

string

Timestamp of last timeline restart (ISO 8601 format). Read-only.

payment_plan_active

boolean

Whether the debt has an active payment plan

plan_start_date

string

Payment plan start date (YYYY-MM-DD format), null if no plan

contacts

array

Additional contacts associated with this debt

pagination

object

Pagination metadata

Show pagination

total

integer

Total number of debts matching the filters

page

integer

Current page number

limit

integer

Number of items per page

pages

integer

Total number of pages

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.

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

Update Debtor Get Debt

Company API

Creditors API

Debtors API

Debts API

Followups API

Reports API

Todos API

Status API

Overview

Authentication

Request

Query Parameters

Example Request

Response

Success Response

Error Responses

Rate Limiting

Usage Examples

Filter by Amount Range

Search for Specific Debtor

Get Recent Debts

Company API

Creditors API

Debtors API

Debts API

Followups API

Reports API

Todos API

Status API

​Overview

​Authentication

​Request

​Query Parameters

​Example Request

​Response

​Success Response

​Error Responses

​Rate Limiting

​Usage Examples

​Filter by Amount Range

​Search for Specific Debtor

​Get Recent Debts

​Pagination

​Related Endpoints

Overview

Authentication

Request

Query Parameters

Example Request

Response

Success Response

Error Responses

Rate Limiting

Usage Examples

Filter by Amount Range

Search for Specific Debtor

Get Recent Debts

Pagination

Related Endpoints