PUT
/
external-api
/
v1
/
debts
/
{id}
Update Debt
curl --request PUT \
  --url https://getbill.io/external-api/v1/debts/{id} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "firstname": "<string>",
  "lastname": "<string>",
  "civility": "<string>",
  "phone": "<string>",
  "email": "<string>",
  "birthdate": "<string>",
  "debtor_company": "<string>",
  "address": "<string>",
  "street_number": "<string>",
  "street_address": "<string>",
  "postal_code": "<string>",
  "city": "<string>",
  "country": "<string>",
  "amount": 123,
  "currency": "<string>",
  "object": "<string>",
  "internal_id": "<string>",
  "invoice_reference": "<string>",
  "debtor_reference": "<string>",
  "invoice_date": "<string>",
  "due_date": "<string>",
  "status": "<string>",
  "iban": "<string>",
  "payment_link": "<string>",
  "company": "<string>",
  "timeline_id": "<string>",
  "metadata": {}
}
'
{
  "error": false,
  "message": "Debt updated successfully",
  "data": {
    "id": "abc123def456",
    "civility": "Mr",
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+33987654321",
    "email": "john.doe@newmail.com",
    "birthdate": "1985-06-15",
    "amount": 1250.00,
    "amount_text": "1250.00",
    "currency": "EUR",
    "object": "Invoice #2024-001",
    "internal_id": "INV-2024-001",
    "invoice_date": "2024-01-01",
    "due_date": "2024-02-15",
    "address": null,
    "street_address": "123 Main Street",
    "street_number": null,
    "postal_code": "75001",
    "city": "Paris",
    "country": "FR",
    "status": "status.default.paid",
    "timeline_id": "xyz789abc123",
    "nb_reminders": 2,
    "nb_answered": 1,
    "summary": null,
    "iban": null,
    "followups_count": 3,
    "company": "GetBill SAS",
    "debtor_company": "ACME Corporation",
    "payment_link": null,
    "import_date": "2024-01-15T10:30:00+00:00",
    "last_timeline_restart": null,
    "payment_plan_active": false,
    "plan_start_date": null,
    "contacts": []
  }
}

​
Overview

This endpoint allows you to update information for an existing debt. You can modify debtor details, amounts, addresses, and other debt-related information.
The status field can be updated via API to: status.default.paid, status.default.in_progress, status.default.on_hold, status.default.failed, or status.default.archived. Other statuses are managed through internal workflows only.

​
Authentication

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

​
Request

​
Authorization
string
required
Bearer token for authentication
​
Content-Type
string
required
Must be application/json
​
id
string
required
The encrypted ID of the debt to update

​
Request Body

​
Debtor Information

​
firstname
string
Debtor’s first name
​
lastname
string
Debtor’s last name
​
civility
string
Civility/title. Possible values: "Mr" or "Ms"
​
phone
string
Debtor’s phone number (will be normalized to E.164 format)
​
email
string
Debtor’s email address
​
birthdate
string
Debtor’s birthdate in YYYY-MM-DD or ISO 8601 format
​
debtor_company
string
Company name of the debtor (for B2B debts)

​
Address Information

​
address
string
Full address (legacy field, use structured address fields when possible)
​
street_number
string
Street number
​
street_address
string
Street name and type
​
postal_code
string
Postal/ZIP code
​
city
string
City name
​
country
string
Country code or name

​
Debt Details

​
amount
number
Debt amount
​
currency
string
Currency code (ISO 4217 format, e.g., "EUR", "USD")
​
object
string
Description or object of the debt (e.g., invoice reference, service description)
​
internal_id
string
Your internal reference ID for this debt
​
invoice_reference
string
Invoice reference number for this debt
​
debtor_reference
string
Your reference for the debtor
​
invoice_date
string
Invoice date in YYYY-MM-DD or ISO 8601 format
​
due_date
string
Payment due date in YYYY-MM-DD or ISO 8601 format
​
status
string
Debt status. Only the following statuses can be set via API:Allowed values:
  • status.default.paid - Mark debt as fully paid
  • status.default.in_progress - Mark debt as collection in progress
  • status.default.on_hold - Put debt collection on hold
  • status.default.failed - Mark collection as failed
  • status.default.archived - Archive the debt
​
iban
string
IBAN for payment
​
payment_link
string
Custom payment link URL

​
Creditor Information (Debt Collection Agencies Only)

​
company
string
Name of the creditor company you are collecting on behalf of. Only used by debt collection agencies who manage debts for multiple client companies. If you are collecting your own debts, leave this field empty.

​
Timeline Configuration

​
timeline_id
string
Encrypted timeline ID to associate with this debt. Set to change the timeline or enable AI-powered workflows. Note: Changing the timeline on an existing debt with active followups should be done carefully.

​
Custom Data

​
metadata
object
Custom metadata object for storing arbitrary JSON data. Use this to store any additional information that your system needs to track, such as CRM IDs, order references, custom tags, or integration-specific data. Pass null to clear existing metadata.

​
Example Request

curl -X PUT "/external-api/v1/debts/abc123def456" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+33987654321",
    "email": "john.doe@newmail.com",
    "debtor_company": "ACME Corporation",
    "street_address": "123 Main Street",
    "city": "Paris",
    "postal_code": "75001",
    "due_date": "2024-02-15",
    "status": "status.default.paid"
  }'

​
Response

Returns the updated debt object with the same structure as the Get Debt endpoint.

​
Success Response

{
  "error": false,
  "message": "Debt updated successfully",
  "data": {
    "id": "abc123def456",
    "civility": "Mr",
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+33987654321",
    "email": "john.doe@newmail.com",
    "birthdate": "1985-06-15",
    "amount": 1250.00,
    "amount_text": "1250.00",
    "currency": "EUR",
    "object": "Invoice #2024-001",
    "internal_id": "INV-2024-001",
    "invoice_date": "2024-01-01",
    "due_date": "2024-02-15",
    "address": null,
    "street_address": "123 Main Street",
    "street_number": null,
    "postal_code": "75001",
    "city": "Paris",
    "country": "FR",
    "status": "status.default.paid",
    "timeline_id": "xyz789abc123",
    "nb_reminders": 2,
    "nb_answered": 1,
    "summary": null,
    "iban": null,
    "followups_count": 3,
    "company": "GetBill SAS",
    "debtor_company": "ACME Corporation",
    "payment_link": null,
    "import_date": "2024-01-15T10:30:00+00:00",
    "last_timeline_restart": null,
    "payment_plan_active": false,
    "plan_start_date": null,
    "contacts": []
  }
}

​
Error Responses

{
  "error": true,
  "message": "Invalid JSON payload",
  "code": 400
}