List Debtors
curl --request GET \
--url https://getbill.io/external-api/v1/debtors \
--header 'Authorization: <authorization>'import requests
url = "https://getbill.io/external-api/v1/debtors"
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/debtors', 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/debtors",
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/debtors"
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))
}HttpResponse<String> response = Unirest.get("https://getbill.io/external-api/v1/debtors")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://getbill.io/external-api/v1/debtors")
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": "def456ghi789",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"phone": "+33612345678",
"address": "123 Main Street, 75001 Paris, France",
"dateOfBirth": "1985-03-15",
"firstSeenAt": "2024-01-15 10:30:00",
"lastSeenAt": "2024-01-20 14:22:00",
"lastUpdatedAt": "2024-01-20 14:22:00"
},
{
"id": "jkl012mno345",
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@example.com",
"phone": "+33698765432",
"address": "456 Oak Avenue, 69001 Lyon, France",
"dateOfBirth": "1990-07-22",
"firstSeenAt": "2024-01-10 09:15:00",
"lastSeenAt": "2024-01-18 11:45:00",
"lastUpdatedAt": "2024-01-18 11:45:00"
}
],
"pagination": {
"total": 512,
"page": 1,
"limit": 50,
"pages": 11
}
}
Debtors API
List Debtors
Retrieve a paginated list of debtors for the authenticated company
GET
/
external-api
/
v1
/
debtors
List Debtors
curl --request GET \
--url https://getbill.io/external-api/v1/debtors \
--header 'Authorization: <authorization>'import requests
url = "https://getbill.io/external-api/v1/debtors"
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/debtors', 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/debtors",
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/debtors"
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))
}HttpResponse<String> response = Unirest.get("https://getbill.io/external-api/v1/debtors")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://getbill.io/external-api/v1/debtors")
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": "def456ghi789",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"phone": "+33612345678",
"address": "123 Main Street, 75001 Paris, France",
"dateOfBirth": "1985-03-15",
"firstSeenAt": "2024-01-15 10:30:00",
"lastSeenAt": "2024-01-20 14:22:00",
"lastUpdatedAt": "2024-01-20 14:22:00"
},
{
"id": "jkl012mno345",
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@example.com",
"phone": "+33698765432",
"address": "456 Oak Avenue, 69001 Lyon, France",
"dateOfBirth": "1990-07-22",
"firstSeenAt": "2024-01-10 09:15:00",
"lastSeenAt": "2024-01-18 11:45:00",
"lastUpdatedAt": "2024-01-18 11:45:00"
}
],
"pagination": {
"total": 512,
"page": 1,
"limit": 50,
"pages": 11
}
}
Overview
This endpoint returns a paginated list of debtors who have debts belonging to your company. Debtors are individuals or entities that owe money.Authentication
Requires a valid OAuth 2.0 access token with thedebtors: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)
Example Request
curl -X GET "/external-api/v1/debtors?page=1&limit=50" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json"
const params = new URLSearchParams({
page: '1',
limit: '50'
});
const response = await fetch(`/external-api/v1/debtors?${params}`, {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
});
const debtors = await response.json();
import requests
params = {
'page': 1,
'limit': 50
}
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
response = requests.get(
'/external-api/v1/debtors',
headers=headers,
params=params
)
debtors = response.json()
Response
boolean
Always
false for successful requestsarray
Array of debtor objects
Show debtor object
Show debtor object
string
Encrypted debtor identifier
string
Debtor’s first name
string
Debtor’s last name
string
Debtor’s email address
string
Debtor’s phone number (E.164 format)
string
Debtor’s address
string
Debtor’s date of birth (YYYY-MM-DD format)
string
First time this debtor was seen (YYYY-MM-DD HH:mm:ss format). Read-only.
string
Last time this debtor was seen (YYYY-MM-DD HH:mm:ss format). Read-only.
string
Last update timestamp (YYYY-MM-DD HH:mm:ss format). Read-only.
object
Success Response
{
"error": false,
"data": [
{
"id": "def456ghi789",
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@example.com",
"phone": "+33612345678",
"address": "123 Main Street, 75001 Paris, France",
"dateOfBirth": "1985-03-15",
"firstSeenAt": "2024-01-15 10:30:00",
"lastSeenAt": "2024-01-20 14:22:00",
"lastUpdatedAt": "2024-01-20 14:22:00"
},
{
"id": "jkl012mno345",
"firstName": "Jane",
"lastName": "Smith",
"email": "jane.smith@example.com",
"phone": "+33698765432",
"address": "456 Oak Avenue, 69001 Lyon, France",
"dateOfBirth": "1990-07-22",
"firstSeenAt": "2024-01-10 09:15:00",
"lastSeenAt": "2024-01-18 11:45:00",
"lastUpdatedAt": "2024-01-18 11:45:00"
}
],
"pagination": {
"total": 512,
"page": 1,
"limit": 50,
"pages": 11
}
}
Error Responses
{
"error": true,
"message": "Authentication credentials are missing or invalid",
"code": 401
}
{
"error": true,
"message": "Required scope \"debtors:read\" not found in token",
"code": 403
}
{
"error": true,
"message": "Company not found or not authorized",
"code": 404
}
Rate Limiting
This endpoint is subject to rate limiting. See the Rate Limits documentation for details. Rate Limit: 1,000 requests per hourRelated Endpoints
- Get Single Debtor - Get detailed information about a specific debtor
- Update Debtor - Update an existing debtor
- List Debts by Debtor - Get all debts for a specific debtor