Get Debt - GetBill External API

Get Debt

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

{
  "error": false,
  "message": "Success",
  "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": "ACME Corporation",
    "payment_link": "https://pay.example.com/debt/abc123",
    "import_date": "2023-11-15T10:30:00+00:00",
    "last_timeline_restart": "2023-12-01T09:00:00+00:00",
    "payment_plan_active": false,
    "plan_start_date": null,
    "contacts": []
  }
}

GET

external-api

debts

{id}

Get Debt

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

{
  "error": false,
  "message": "Success",
  "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": "ACME Corporation",
    "payment_link": "https://pay.example.com/debt/abc123",
    "import_date": "2023-11-15T10:30:00+00:00",
    "last_timeline_restart": "2023-12-01T09:00:00+00:00",
    "payment_plan_active": false,
    "plan_start_date": null,
    "contacts": []
  }
}

Overview

This endpoint returns comprehensive information about a single debt, including all related data such as followup history, payment status, and debtor details.

Authentication

Requires a valid OAuth 2.0 access token with the debts:read scope.

Request

Authorization

string

required

Bearer token for authentication

string

required

The encrypted ID of the debt to retrieve

Example Request

curl -X GET "/external-api/v1/debts/abc123def456" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response

error

boolean

Always false for successful requests

message

string

Success message

data

object

Complete debt information

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. Can be set to status.default.paid, status.default.in_progress, status.default.on_hold, status.default.failed, or status.default.archived via the Update Debt endpoint.

timeline_id

string

Encrypted timeline ID associated with this debt (null if no timeline)

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 - automatically set by the system.

last_timeline_restart

string

Timestamp of last timeline restart (ISO 8601 format). Read-only - managed by the system based on timeline workflows.

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

Success Response

{
  "error": false,
  "message": "Success",
  "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": "ACME Corporation",
    "payment_link": "https://pay.example.com/debt/abc123",
    "import_date": "2023-11-15T10:30:00+00:00",
    "last_timeline_restart": "2023-12-01T09:00:00+00:00",
    "payment_plan_active": false,
    "plan_start_date": null,
    "contacts": []
  }
}

Error Responses

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

List Debts - Get all debts for your company
Update Debt - Modify debt information
Delete Debt - Remove a debt
Get Followups by Debt - Get followups for this debt

List Debts Create Debt

​Overview

​Authentication

​Request

​Example Request

​Response

​Success Response

​Error Responses

​Related Endpoints

Overview

Authentication

Request

Example Request

Response

Success Response

Error Responses

Related Endpoints