List Debts

List Debts

curl --request GET \
  --url https://getbill.io/external-api/v1/debts \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://getbill.io/external-api/v1/debts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://getbill.io/external-api/v1/debts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://getbill.io/external-api/v1/debts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://getbill.io/external-api/v1/debts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "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": "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",
      "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
  }
}

GET

external-api

debts

List Debts

curl --request GET \
  --url https://getbill.io/external-api/v1/debts \
  --header 'Authorization: <authorization>'

const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

fetch('https://getbill.io/external-api/v1/debts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://getbill.io/external-api/v1/debts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://getbill.io/external-api/v1/debts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://getbill.io/external-api/v1/debts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "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": "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",
      "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
  }
}

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

string

required

Bearer token for authentication

Query Parameters

integer

default:"1"

Page number for pagination (starts at 1)

integer

default:"20"

Number of items per page (maximum 100)

string

Filter by debt status (e.g., “active”, “paid”, “disputed”)

string

Filter by currency code (e.g., “EUR”, “USD”)

number

Minimum debt amount filter

number

Maximum debt amount filter

string

Filter debts created after this date (ISO 8601 format)

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"

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()

Response

boolean

Always false for successful requests

array

Array of debt objects

Show debt object

string

Encrypted debt identifier

boolean

Whether the debt belongs to a group containing multiple non-archived debts

array

Encrypted IDs of the debts in the group. For an ungrouped debt, this contains only its own ID.

string

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

string

Debtor’s first name

string

Debtor’s last name

string

Debtor’s phone number (E.164 format)

string

Debtor’s email address

string

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

number

Debt amount

string

Debt amount as text

string

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

string

Description of the debt object/reason

string

Your internal reference ID for this debt

string

Invoice reference number

string

Your reference for the debtor

string

Original invoice date (YYYY-MM-DD format)

string

Payment due date (YYYY-MM-DD format)

string

Full address (legacy field)

string

Street name and type

string

Street number

string

Postal/ZIP code

string

City name

string

Country code or name

string

Current debt status (read-only)

string

Encrypted timeline ID associated with this debt

integer

Number of reminders sent

integer

Number of responses received

string

Brief summary or notes about the debt

string

IBAN for payment

integer

Number of followups for this debt

string

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

string

Debtor’s company name (for B2B debts)

string

Custom payment link URL

string

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

string

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

boolean

Whether the debt has an active payment plan

string

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

object

Pagination metadata

Show pagination

integer

Total number of debts matching the filters

integer

Current page number

integer

Number of items per page

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": "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",
      "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 Responses

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

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

​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