Update Debt

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>",
  "accept_expensive_destination": true,
  "email": "<string>",
  "birthdate": "<string>",
  "debtor_company": "<string>",
  "address": "<string>",
  "street_number": "<string>",
  "street_address": "<string>",
  "postal_code": "<string>",
  "city": "<string>",
  "country": "<string>",
  "amount": 123,
  "paidAmount": 123,
  "paid_amount": 123,
  "remainingAmount": 123,
  "remaining_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": {}
}
'

import requests

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

payload = {
    "firstname": "<string>",
    "lastname": "<string>",
    "civility": "<string>",
    "phone": "<string>",
    "accept_expensive_destination": True,
    "email": "<string>",
    "birthdate": "<string>",
    "debtor_company": "<string>",
    "address": "<string>",
    "street_number": "<string>",
    "street_address": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "country": "<string>",
    "amount": 123,
    "paidAmount": 123,
    "paid_amount": 123,
    "remainingAmount": 123,
    "remaining_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": {}
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    firstname: '<string>',
    lastname: '<string>',
    civility: '<string>',
    phone: '<string>',
    accept_expensive_destination: true,
    email: '<string>',
    birthdate: '<string>',
    debtor_company: '<string>',
    address: '<string>',
    street_number: '<string>',
    street_address: '<string>',
    postal_code: '<string>',
    city: '<string>',
    country: '<string>',
    amount: 123,
    paidAmount: 123,
    paid_amount: 123,
    remainingAmount: 123,
    remaining_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: {}
  })
};

fetch('https://getbill.io/external-api/v1/debts/{id}', 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/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'firstname' => '<string>',
    'lastname' => '<string>',
    'civility' => '<string>',
    'phone' => '<string>',
    'accept_expensive_destination' => true,
    'email' => '<string>',
    'birthdate' => '<string>',
    'debtor_company' => '<string>',
    'address' => '<string>',
    'street_number' => '<string>',
    'street_address' => '<string>',
    'postal_code' => '<string>',
    'city' => '<string>',
    'country' => '<string>',
    'amount' => 123,
    'paidAmount' => 123,
    'paid_amount' => 123,
    'remainingAmount' => 123,
    'remaining_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' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"firstname\": \"<string>\",\n  \"lastname\": \"<string>\",\n  \"civility\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"accept_expensive_destination\": true,\n  \"email\": \"<string>\",\n  \"birthdate\": \"<string>\",\n  \"debtor_company\": \"<string>\",\n  \"address\": \"<string>\",\n  \"street_number\": \"<string>\",\n  \"street_address\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"city\": \"<string>\",\n  \"country\": \"<string>\",\n  \"amount\": 123,\n  \"paidAmount\": 123,\n  \"paid_amount\": 123,\n  \"remainingAmount\": 123,\n  \"remaining_amount\": 123,\n  \"currency\": \"<string>\",\n  \"object\": \"<string>\",\n  \"internal_id\": \"<string>\",\n  \"invoice_reference\": \"<string>\",\n  \"debtor_reference\": \"<string>\",\n  \"invoice_date\": \"<string>\",\n  \"due_date\": \"<string>\",\n  \"status\": \"<string>\",\n  \"iban\": \"<string>\",\n  \"payment_link\": \"<string>\",\n  \"company\": \"<string>\",\n  \"timeline_id\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://getbill.io/external-api/v1/debts/{id}")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"firstname\": \"<string>\",\n  \"lastname\": \"<string>\",\n  \"civility\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"accept_expensive_destination\": true,\n  \"email\": \"<string>\",\n  \"birthdate\": \"<string>\",\n  \"debtor_company\": \"<string>\",\n  \"address\": \"<string>\",\n  \"street_number\": \"<string>\",\n  \"street_address\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"city\": \"<string>\",\n  \"country\": \"<string>\",\n  \"amount\": 123,\n  \"paidAmount\": 123,\n  \"paid_amount\": 123,\n  \"remainingAmount\": 123,\n  \"remaining_amount\": 123,\n  \"currency\": \"<string>\",\n  \"object\": \"<string>\",\n  \"internal_id\": \"<string>\",\n  \"invoice_reference\": \"<string>\",\n  \"debtor_reference\": \"<string>\",\n  \"invoice_date\": \"<string>\",\n  \"due_date\": \"<string>\",\n  \"status\": \"<string>\",\n  \"iban\": \"<string>\",\n  \"payment_link\": \"<string>\",\n  \"company\": \"<string>\",\n  \"timeline_id\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"firstname\": \"<string>\",\n  \"lastname\": \"<string>\",\n  \"civility\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"accept_expensive_destination\": true,\n  \"email\": \"<string>\",\n  \"birthdate\": \"<string>\",\n  \"debtor_company\": \"<string>\",\n  \"address\": \"<string>\",\n  \"street_number\": \"<string>\",\n  \"street_address\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"city\": \"<string>\",\n  \"country\": \"<string>\",\n  \"amount\": 123,\n  \"paidAmount\": 123,\n  \"paid_amount\": 123,\n  \"remainingAmount\": 123,\n  \"remaining_amount\": 123,\n  \"currency\": \"<string>\",\n  \"object\": \"<string>\",\n  \"internal_id\": \"<string>\",\n  \"invoice_reference\": \"<string>\",\n  \"debtor_reference\": \"<string>\",\n  \"invoice_date\": \"<string>\",\n  \"due_date\": \"<string>\",\n  \"status\": \"<string>\",\n  \"iban\": \"<string>\",\n  \"payment_link\": \"<string>\",\n  \"company\": \"<string>\",\n  \"timeline_id\": \"<string>\",\n  \"metadata\": {}\n}"

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

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

PUT

external-api

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>",
  "accept_expensive_destination": true,
  "email": "<string>",
  "birthdate": "<string>",
  "debtor_company": "<string>",
  "address": "<string>",
  "street_number": "<string>",
  "street_address": "<string>",
  "postal_code": "<string>",
  "city": "<string>",
  "country": "<string>",
  "amount": 123,
  "paidAmount": 123,
  "paid_amount": 123,
  "remainingAmount": 123,
  "remaining_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": {}
}
'

import requests

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

payload = {
    "firstname": "<string>",
    "lastname": "<string>",
    "civility": "<string>",
    "phone": "<string>",
    "accept_expensive_destination": True,
    "email": "<string>",
    "birthdate": "<string>",
    "debtor_company": "<string>",
    "address": "<string>",
    "street_number": "<string>",
    "street_address": "<string>",
    "postal_code": "<string>",
    "city": "<string>",
    "country": "<string>",
    "amount": 123,
    "paidAmount": 123,
    "paid_amount": 123,
    "remainingAmount": 123,
    "remaining_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": {}
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "<content-type>"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<authorization>', 'Content-Type': '<content-type>'},
  body: JSON.stringify({
    firstname: '<string>',
    lastname: '<string>',
    civility: '<string>',
    phone: '<string>',
    accept_expensive_destination: true,
    email: '<string>',
    birthdate: '<string>',
    debtor_company: '<string>',
    address: '<string>',
    street_number: '<string>',
    street_address: '<string>',
    postal_code: '<string>',
    city: '<string>',
    country: '<string>',
    amount: 123,
    paidAmount: 123,
    paid_amount: 123,
    remainingAmount: 123,
    remaining_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: {}
  })
};

fetch('https://getbill.io/external-api/v1/debts/{id}', 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/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'firstname' => '<string>',
    'lastname' => '<string>',
    'civility' => '<string>',
    'phone' => '<string>',
    'accept_expensive_destination' => true,
    'email' => '<string>',
    'birthdate' => '<string>',
    'debtor_company' => '<string>',
    'address' => '<string>',
    'street_number' => '<string>',
    'street_address' => '<string>',
    'postal_code' => '<string>',
    'city' => '<string>',
    'country' => '<string>',
    'amount' => 123,
    'paidAmount' => 123,
    'paid_amount' => 123,
    'remainingAmount' => 123,
    'remaining_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' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: <content-type>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"firstname\": \"<string>\",\n  \"lastname\": \"<string>\",\n  \"civility\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"accept_expensive_destination\": true,\n  \"email\": \"<string>\",\n  \"birthdate\": \"<string>\",\n  \"debtor_company\": \"<string>\",\n  \"address\": \"<string>\",\n  \"street_number\": \"<string>\",\n  \"street_address\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"city\": \"<string>\",\n  \"country\": \"<string>\",\n  \"amount\": 123,\n  \"paidAmount\": 123,\n  \"paid_amount\": 123,\n  \"remainingAmount\": 123,\n  \"remaining_amount\": 123,\n  \"currency\": \"<string>\",\n  \"object\": \"<string>\",\n  \"internal_id\": \"<string>\",\n  \"invoice_reference\": \"<string>\",\n  \"debtor_reference\": \"<string>\",\n  \"invoice_date\": \"<string>\",\n  \"due_date\": \"<string>\",\n  \"status\": \"<string>\",\n  \"iban\": \"<string>\",\n  \"payment_link\": \"<string>\",\n  \"company\": \"<string>\",\n  \"timeline_id\": \"<string>\",\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "<content-type>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://getbill.io/external-api/v1/debts/{id}")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "<content-type>")
  .body("{\n  \"firstname\": \"<string>\",\n  \"lastname\": \"<string>\",\n  \"civility\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"accept_expensive_destination\": true,\n  \"email\": \"<string>\",\n  \"birthdate\": \"<string>\",\n  \"debtor_company\": \"<string>\",\n  \"address\": \"<string>\",\n  \"street_number\": \"<string>\",\n  \"street_address\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"city\": \"<string>\",\n  \"country\": \"<string>\",\n  \"amount\": 123,\n  \"paidAmount\": 123,\n  \"paid_amount\": 123,\n  \"remainingAmount\": 123,\n  \"remaining_amount\": 123,\n  \"currency\": \"<string>\",\n  \"object\": \"<string>\",\n  \"internal_id\": \"<string>\",\n  \"invoice_reference\": \"<string>\",\n  \"debtor_reference\": \"<string>\",\n  \"invoice_date\": \"<string>\",\n  \"due_date\": \"<string>\",\n  \"status\": \"<string>\",\n  \"iban\": \"<string>\",\n  \"payment_link\": \"<string>\",\n  \"company\": \"<string>\",\n  \"timeline_id\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = '<content-type>'
request.body = "{\n  \"firstname\": \"<string>\",\n  \"lastname\": \"<string>\",\n  \"civility\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"accept_expensive_destination\": true,\n  \"email\": \"<string>\",\n  \"birthdate\": \"<string>\",\n  \"debtor_company\": \"<string>\",\n  \"address\": \"<string>\",\n  \"street_number\": \"<string>\",\n  \"street_address\": \"<string>\",\n  \"postal_code\": \"<string>\",\n  \"city\": \"<string>\",\n  \"country\": \"<string>\",\n  \"amount\": 123,\n  \"paidAmount\": 123,\n  \"paid_amount\": 123,\n  \"remainingAmount\": 123,\n  \"remaining_amount\": 123,\n  \"currency\": \"<string>\",\n  \"object\": \"<string>\",\n  \"internal_id\": \"<string>\",\n  \"invoice_reference\": \"<string>\",\n  \"debtor_reference\": \"<string>\",\n  \"invoice_date\": \"<string>\",\n  \"due_date\": \"<string>\",\n  \"status\": \"<string>\",\n  \"iban\": \"<string>\",\n  \"payment_link\": \"<string>\",\n  \"company\": \"<string>\",\n  \"timeline_id\": \"<string>\",\n  \"metadata\": {}\n}"

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

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

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

string

required

Bearer token for authentication

string

required

Must be application/json

string

required

The encrypted ID of the debt to update

Request Body

Debtor Information

string

Debtor’s first name

string

Debtor’s last name

string

Civility/title. Possible values: "Mr" or "Ms"

string

Debtor’s phone number (will be normalized to E.164 format)

boolean

Explicitly permits (true) or restricts (false) phone communications to a destination whose configured AI-call price is at least 50 credits, for the supplied phone and secondary-contact phones. A restriction blocks SMS, RCS, calls, WhatsApp, and voicemail only; email and postal reminders continue. Omit the field with an unchanged phone to preserve its recorded choice. Supplying a new costly phone without this field records a restriction. A balance-only update, with neither phone nor option, does not change a recorded or historical decision. For a historical phone with no recorded decision, the first update that resends that phone without this field records a restriction. The field accepts JSON booleans only. For debt synchronized through a campaign, the GetBill campaign configuration takes priority.

string

Debtor’s email address

string

Debtor’s birthdate in YYYY-MM-DD or ISO 8601 format

string

Company name of the debtor (for B2B debts)

Address Information

string

Full address (legacy field, use structured address fields when possible)

string

Street number

string

Street name and type

string

Postal/ZIP code

string

City name

string

Country code or name

Debt Details

number

Debt amount

number

Non-negative cumulative amount already paid on the debt. Increasing it records an off-platform payment delta in GetBill. It cannot be lower than the currently tracked paid amount.

number

Snake_case alias for paidAmount.

number

Non-negative target remaining balance. Lowering it records an off-platform payment delta; setting it to 0 marks the debt as fully paid when applicable.

number

Snake_case alias for remainingAmount.

When both paid and remaining amounts are sent, their sum must equal the debt amount.

string

Currency code (ISO 4217 format, e.g., "EUR", "USD")

string

Description or object of the debt (e.g., invoice reference, service description)

string

Your internal reference ID for this debt

string

Invoice reference number for this debt

string

Your reference for the debtor

string

Invoice date in YYYY-MM-DD or ISO 8601 format

string

Payment due date in YYYY-MM-DD or ISO 8601 format

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

string

IBAN for payment

string

Custom payment link URL

Creditor Information (Debt Collection Agencies Only)

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

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

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

const debtId = 'abc123def456';
const updateData = {
  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'
};

const response = await fetch(`/external-api/v1/debts/${debtId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(updateData)
});

const result = await response.json();

Response

Returns the updated debt object with the same structure as the Get Debt endpoint. For a costly phone destination without authorization, the update succeeds and includes an expensive_destination_not_accepted warning. It does not return 422 solely because of the destination.

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

Error Responses

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

{
  "error": true,
  "message": "Access denied to this debt",
  "code": 403
}

{
  "error": true,
  "message": "Debt not found or invalid ID",
  "code": 404
}

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

Request Body

Debtor Information

Address Information

Debt Details

Creditor Information (Debt Collection Agencies Only)

Timeline Configuration

Custom Data

Example Request

Response

Success Response

Error Responses

​Overview

​Authentication

​Request

​Request Body

​Debtor Information

​Address Information

​Debt Details

​Creditor Information (Debt Collection Agencies Only)

​Timeline Configuration

​Custom Data

​Example Request

​Response

​Success Response

​Error Responses

Overview

Authentication

Request

Request Body

Debtor Information

Address Information

Debt Details

Creditor Information (Debt Collection Agencies Only)

Timeline Configuration

Custom Data

Example Request

Response

Success Response

Error Responses