List Debts by Debtor

curl --request GET \
  --url https://getbill.io/external-api/v1/debts/by-debtor/{debtorId} \
  --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": []
    },
    {
      "id": "def789xyz456",
      "civility": "Mr",
      "firstname": "John",
      "lastname": "Doe",
      "phone": "+33123456789",
      "email": "john.doe@example.com",
      "birthdate": "1985-03-15",
      "amount": 750.00,
      "amount_text": "750.00",
      "currency": "EUR",
      "object": "Service contract penalty",
      "internal_id": "DEBT-2024-025",
      "invoice_reference": "INV-2024-025",
      "debtor_reference": null,
      "invoice_date": "2024-01-01",
      "due_date": "2024-01-31",
      "address": null,
      "street_address": "Main Street",
      "street_number": "123",
      "postal_code": "75001",
      "city": "Paris",
      "country": "FR",
      "status": "status.default.pending",
      "timeline_id": null,
      "nb_reminders": 1,
      "nb_answered": 0,
      "summary": null,
      "iban": "FR1420041010050500013M02606",
      "followups_count": 2,
      "company": "Service Plus SARL",
      "debtor_company": null,
      "payment_link": null,
      "import_date": "2024-01-20T09:15:00+00:00",
      "last_timeline_restart": null,
      "payment_plan_active": false,
      "plan_start_date": null,
      "contacts": []
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

GET

external-api

debts

by-debtor

{debtorId}

List Debts by Debtor

curl --request GET \
  --url https://getbill.io/external-api/v1/debts/by-debtor/{debtorId} \
  --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": []
    },
    {
      "id": "def789xyz456",
      "civility": "Mr",
      "firstname": "John",
      "lastname": "Doe",
      "phone": "+33123456789",
      "email": "john.doe@example.com",
      "birthdate": "1985-03-15",
      "amount": 750.00,
      "amount_text": "750.00",
      "currency": "EUR",
      "object": "Service contract penalty",
      "internal_id": "DEBT-2024-025",
      "invoice_reference": "INV-2024-025",
      "debtor_reference": null,
      "invoice_date": "2024-01-01",
      "due_date": "2024-01-31",
      "address": null,
      "street_address": "Main Street",
      "street_number": "123",
      "postal_code": "75001",
      "city": "Paris",
      "country": "FR",
      "status": "status.default.pending",
      "timeline_id": null,
      "nb_reminders": 1,
      "nb_answered": 0,
      "summary": null,
      "iban": "FR1420041010050500013M02606",
      "followups_count": 2,
      "company": "Service Plus SARL",
      "debtor_company": null,
      "payment_link": null,
      "import_date": "2024-01-20T09:15:00+00:00",
      "last_timeline_restart": null,
      "payment_plan_active": false,
      "plan_start_date": null,
      "contacts": []
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

Overview

This endpoint returns a paginated list of all debts owed by a specific debtor. 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

debtorId

string

required

The encrypted debtor 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)

string

Search in internal_id or amount_text fields

Example Request

curl -X GET "/external-api/v1/debts/by-debtor/def456ghi789?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

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 for this debtor

page

integer

Current page number

limit

integer

Number of items per page

pages

integer

Total number of pages

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": []
    },
    {
      "id": "def789xyz456",
      "civility": "Mr",
      "firstname": "John",
      "lastname": "Doe",
      "phone": "+33123456789",
      "email": "john.doe@example.com",
      "birthdate": "1985-03-15",
      "amount": 750.00,
      "amount_text": "750.00",
      "currency": "EUR",
      "object": "Service contract penalty",
      "internal_id": "DEBT-2024-025",
      "invoice_reference": "INV-2024-025",
      "debtor_reference": null,
      "invoice_date": "2024-01-01",
      "due_date": "2024-01-31",
      "address": null,
      "street_address": "Main Street",
      "street_number": "123",
      "postal_code": "75001",
      "city": "Paris",
      "country": "FR",
      "status": "status.default.pending",
      "timeline_id": null,
      "nb_reminders": 1,
      "nb_answered": 0,
      "summary": null,
      "iban": "FR1420041010050500013M02606",
      "followups_count": 2,
      "company": "Service Plus SARL",
      "debtor_company": null,
      "payment_link": null,
      "import_date": "2024-01-20T09:15:00+00:00",
      "last_timeline_restart": null,
      "payment_plan_active": false,
      "plan_start_date": null,
      "contacts": []
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

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

List All Debts - Get all debts for your company
Get Debtor - Get debtor information
List Debts by Creditor - Get all debts for a specific creditor

List Debts by Creditor List Followups

​Overview

​Authentication

​Request

​Path Parameters

​Query Parameters

​Example Request

​Response

​Success Response

​Error Responses

​Rate Limiting

​Related Endpoints

Overview

Authentication

Request

Path Parameters

Query Parameters

Example Request

Response

Success Response

Error Responses

Rate Limiting

Related Endpoints