Update Debtor

Update Debtor

curl --request PUT \
  --url https://getbill.io/external-api/v1/debtors/{id} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "<string>",
  "lastName": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "address": "<string>",
  "dateOfBirth": "<string>"
}
'

import requests

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

payload = {
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "address": "<string>",
    "dateOfBirth": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    firstName: '<string>',
    lastName: '<string>',
    email: '<string>',
    phone: '<string>',
    address: '<string>',
    dateOfBirth: '<string>'
  })
};

fetch('https://getbill.io/external-api/v1/debtors/{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/debtors/{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>',
    'email' => '<string>',
    'phone' => '<string>',
    'address' => '<string>',
    'dateOfBirth' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$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/debtors/{id}"

	payload := strings.NewReader("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": \"<string>\",\n  \"dateOfBirth\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	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/debtors/{id}")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": \"<string>\",\n  \"dateOfBirth\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://getbill.io/external-api/v1/debtors/{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"] = 'application/json'
request.body = "{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": \"<string>\",\n  \"dateOfBirth\": \"<string>\"\n}"

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

{
  "error": false,
  "message": "Success",
  "data": {
    "data": {
      "id": "def456ghi789",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.newemail@example.com",
      "phone": "+33699999999",
      "address": "456 New Street, 75002 Paris, France",
      "dateOfBirth": "1985-03-15",
      "firstSeenAt": "2024-01-15 10:30:00",
      "lastSeenAt": "2024-01-20 14:22:00",
      "lastUpdatedAt": "2024-02-01 15:45:00",
      "totalDebtAmount": 2500.00,
      "totalPaidAmount": 750.00,
      "averageRepaymentScore": 65,
      "debtsCount": 3
    },
    "message": "Debtor updated successfully"
  }
}

PUT

external-api

debtors

{id}

Update Debtor

curl --request PUT \
  --url https://getbill.io/external-api/v1/debtors/{id} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "<string>",
  "lastName": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "address": "<string>",
  "dateOfBirth": "<string>"
}
'

import requests

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

payload = {
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "address": "<string>",
    "dateOfBirth": "<string>"
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    firstName: '<string>',
    lastName: '<string>',
    email: '<string>',
    phone: '<string>',
    address: '<string>',
    dateOfBirth: '<string>'
  })
};

fetch('https://getbill.io/external-api/v1/debtors/{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/debtors/{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>',
    'email' => '<string>',
    'phone' => '<string>',
    'address' => '<string>',
    'dateOfBirth' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$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/debtors/{id}"

	payload := strings.NewReader("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": \"<string>\",\n  \"dateOfBirth\": \"<string>\"\n}")

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

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	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/debtors/{id}")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": \"<string>\",\n  \"dateOfBirth\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://getbill.io/external-api/v1/debtors/{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"] = 'application/json'
request.body = "{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"address\": \"<string>\",\n  \"dateOfBirth\": \"<string>\"\n}"

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

{
  "error": false,
  "message": "Success",
  "data": {
    "data": {
      "id": "def456ghi789",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.newemail@example.com",
      "phone": "+33699999999",
      "address": "456 New Street, 75002 Paris, France",
      "dateOfBirth": "1985-03-15",
      "firstSeenAt": "2024-01-15 10:30:00",
      "lastSeenAt": "2024-01-20 14:22:00",
      "lastUpdatedAt": "2024-02-01 15:45:00",
      "totalDebtAmount": 2500.00,
      "totalPaidAmount": 750.00,
      "averageRepaymentScore": 65,
      "debtsCount": 3
    },
    "message": "Debtor updated successfully"
  }
}

Overview

This endpoint allows you to update debtor information. You can use either PUT (full update) or PATCH (partial update) methods.

Authentication

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

Request

string

required

Bearer token for authentication

Path Parameters

string

required

The encrypted debtor ID

Request Body

All fields are optional. Only include the fields you want to update.

string

Debtor’s first name

string

Debtor’s last name

string

Debtor’s email address

string

Debtor’s phone number (E.164 format recommended)

string

Debtor’s full address

string

Debtor’s date of birth (YYYY-MM-DD format)

Example Request

curl -X PUT "/external-api/v1/debtors/def456ghi789" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "john.newemail@example.com",
    "phone": "+33699999999",
    "address": "456 New Street, 75002 Paris, France"
  }'

const debtorId = 'def456ghi789';
const updateData = {
  email: 'john.newemail@example.com',
  phone: '+33699999999',
  address: '456 New Street, 75002 Paris, France'
};

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

const updatedDebtor = await response.json();

import requests
import json

debtor_id = 'def456ghi789'
update_data = {
    'email': 'john.newemail@example.com',
    'phone': '+33699999999',
    'address': '456 New Street, 75002 Paris, France'
}

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

response = requests.put(
    f'/external-api/v1/debtors/{debtor_id}',
    headers=headers,
    data=json.dumps(update_data)
)

updated_debtor = response.json()

Response

boolean

Always false for successful requests

string

Success message

object

Response data wrapper

Show data object

object

Updated debtor object with detailed information

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 full 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.

number

Total amount of all debts for this debtor. Read-only.

number

Total amount paid across all debts. Read-only.

integer

Average repayment score across all debts (0-100). Read-only.

integer

Number of debts for this debtor. Read-only.

string

Confirmation message (e.g., “Debtor updated successfully”)

Success Response

{
  "error": false,
  "message": "Success",
  "data": {
    "data": {
      "id": "def456ghi789",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.newemail@example.com",
      "phone": "+33699999999",
      "address": "456 New Street, 75002 Paris, France",
      "dateOfBirth": "1985-03-15",
      "firstSeenAt": "2024-01-15 10:30:00",
      "lastSeenAt": "2024-01-20 14:22:00",
      "lastUpdatedAt": "2024-02-01 15:45:00",
      "totalDebtAmount": 2500.00,
      "totalPaidAmount": 750.00,
      "averageRepaymentScore": 65,
      "debtsCount": 3
    },
    "message": "Debtor updated successfully"
  }
}

Error Responses

{
  "error": true,
  "message": "Invalid dateOfBirth format. Use YYYY-MM-DD",
  "code": 400
}

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

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

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

{
  "error": true,
  "message": "Debtor 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 hour

Get Debtor - Get debtor information
List Debtors - Get a list of all debtors
List Debts by Debtor - Get all debts for this debtor

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

Path Parameters

Request Body

Example Request

Response

Success Response

Error Responses

Rate Limiting

​Overview

​Authentication

​Request

​Path Parameters

​Request Body

​Example Request

​Response

​Success Response

​Error Responses

​Rate Limiting

​Related Endpoints

Overview

Authentication

Request

Path Parameters

Request Body

Example Request

Response

Success Response

Error Responses

Rate Limiting

Related Endpoints