List Debts by Debtor

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

import requests

url = "https://getbill.io/external-api/v1/debts/by-debtor/{debtorId}"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

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

fetch('https://getbill.io/external-api/v1/debts/by-debtor/{debtorId}', 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/by-debtor/{debtorId}",
  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/by-debtor/{debtorId}"

	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/by-debtor/{debtorId}")

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

import requests

url = "https://getbill.io/external-api/v1/debts/by-debtor/{debtorId}"

headers = {"Authorization": "<authorization>"}

response = requests.get(url, headers=headers)

print(response.text)

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

fetch('https://getbill.io/external-api/v1/debts/by-debtor/{debtorId}', 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/by-debtor/{debtorId}",
  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/by-debtor/{debtorId}"

	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/by-debtor/{debtorId}")

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

string

required

Bearer token for authentication

Path Parameters

string

required

The encrypted debtor ID

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

const debtorId = 'def456ghi789';
const params = new URLSearchParams({
  page: '1',
  limit: '50',
  status: 'active'
});

const response = await fetch(`/external-api/v1/debts/by-debtor/${debtorId}?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  }
});

const debts = await response.json();

import requests

debtor_id = 'def456ghi789'
params = {
    'page': 1,
    'limit': 50,
    'status': 'active'
}

headers = {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
}

response = requests.get(
    f'/external-api/v1/debts/by-debtor/{debtor_id}',
    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 for this debtor

integer

Current page number

integer

Number of items per page

integer

Total number of pages

Success Response

{
  "error": false,
  "data": [
    {
      "id": "YOUR_DEBT_ID",
      "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
    },
    {
      "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
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

Error Responses

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

{
  "error": true,
  "message": "Required scope \"debts:read\" not found in token",
  "code": 403
}

{
  "error": true,
  "message": "Debtor not found or not authorized",
  "code": 404
}

{
  "error": true,
  "message": "Internal server error",
  "code": 500
}

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

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

List Debts by Debtor

Overview

Authentication

Request

Path Parameters

Query Parameters

Example Request

Response

Success Response

Error Responses

Rate Limiting

​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