Create Debt

Overview

This endpoint creates a debt or records a credit note. A positive amount creates a debt; a negative amount creates or updates a credit note.

Authentication

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

Custom dynamic fields

extra_variables: Optional object of custom dynamic fields, for example {"contract_number": "CTR-123", "agency": "Paris"}. When omitted, existing values are preserved. When provided, replaces all dynamic fields; {} clears them.

For a credit note, send a negative amount, one identity field (internal_id or invoice_reference), and one target field (credited_invoice_reference or debtor_reference). A debtor-only target also requires timeline_id unless your company has exactly one timeline. Debtor names and contact details are not required.

Example Request

curl -X POST "/external-api/v1/debts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "John",
    "lastname": "Doe",
    "civility": "Mr",
    "phone": "+33123456789",
    "email": "john.doe@example.com",
    "birthdate": "1985-03-15",
    "amount": 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",
    "iban": "FR1420041010050500013M02606",
    "company": "Acme Corp",
    "timeline_id": "YOUR_TIMELINE_ID",
    "timeline_start_mode": "next_day",
    "detect_civility": true,
    "validate_emails": false,
    "metadata": {"crm_id": "CRM-123", "source": "website", "priority": "high"}
  }'

const debtData = {
  firstname: "John",
  lastname: "Doe",
  civility: "Mr",
  phone: "+33123456789",
  email: "john.doe@example.com",
  birthdate: "1985-03-15",
  amount: 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",
  iban: "FR1420041010050500013M02606",
  company: "Acme Corp",
  debtor_company: "ACME Corporation",
  timeline_id: "YOUR_TIMELINE_ID",
  timeline_start_mode: "next_day",
  detect_civility: true,
  validate_emails: false,
  metadata: { crm_id: "CRM-123", source: "website", priority: "high" }
};

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

const result = await response.json();

import requests

debt_data = {
    "firstname": "John",
    "lastname": "Doe",
    "civility": "Mr",
    "phone": "+33123456789",
    "email": "john.doe@example.com",
    "birthdate": "1985-03-15",
    "amount": 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",
    "iban": "FR1420041010050500013M02606",
    "company": "Acme Corp",
    "timeline_id": "YOUR_TIMELINE_ID",
    "timeline_start_mode": "next_day",
    "detect_civility": True,
    "validate_emails": False,
    "metadata": {"crm_id": "CRM-123", "source": "website", "priority": "high"}
}

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

response = requests.post(
    '/external-api/v1/debts',
    headers=headers,
    json=debt_data
)

result = response.json()

Success Response

{
  "error": false,
  "message": "Debt created successfully",
  "data": {
    "id": "abc123def456",
    "civility": "Mr",
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+33123456789",
    "email": "john.doe@example.com",
    "email_validation": {
      "status": "valid",
      "reason": "accepted_email",
      "charged": true,
      "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": null,
    "street_number": null,
    "postal_code": null,
    "city": null,
    "country": null,
    "status": "status.default.pending",
    "timeline_id": "YOUR_TIMELINE_ID",
    "nb_reminders": 0,
    "nb_answered": 0,
    "summary": null,
    "iban": "FR1420041010050500013M02606",
    "followups_count": 0,
    "company": "Acme Corp",
    "debtor_company": "ACME Corporation",
    "payment_link": null,
    "metadata": {"crm_id": "CRM-123", "source": "website", "priority": "high"},
    "import_date": "2024-01-22T10:30:00+00:00",
    "last_timeline_restart": null,
    "payment_plan_active": false,
    "plan_start_date": null
  }
}

Error Responses

{
  "error": true,
  "message": "Validation failed",
  "code": 400,
  "details": {
    "firstname": "First name is required",
    "lastname": "Last name is required",
    "amount": "Valid amount (greater than 0) is required",
    "contact": "At least one valid contact method (email or phone) is required",
    "phone": "Invalid phone number"
  }
}

{
  "error": true,
  "message": "Invalid phone number: \"12345\" - phone number too short",
  "code": 400
}

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

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

{
  "error": true,
  "message": "Failed to create debt",
  "code": 500
}

Validation Rules

Validation Update (2025): Phone number validation is now strictly enforced to match the web interface behavior. Phone numbers are validated using international standards (libphonenumber library). If you were previously sending phone numbers without proper formatting or French overseas mobile numbers (069X prefix), these will now be rejected. You can now use email as an alternative to phone.

Required Fields

Debt (amount > 0):

firstname and lastname: Must not be empty
phone or email: At least one valid contact method

Credit note (amount < 0):

internal_id or invoice_reference: Stable credit note identity
credited_invoice_reference or debtor_reference: Debt target
timeline_id: Required for a debtor-only target unless the company has exactly one timeline

amount must not be zero and currency must be a valid ISO 4217 currency code.

Debt Contact Information (At Least One Required)

At least one valid contact method is required:

phone: Must be a valid phone number if provided
- Supported: French mainland numbers, most international numbers, French overseas fixed lines
- NOT Supported: French overseas mobile numbers with 069X prefix (e.g., 0690123456)
- International format recommended (e.g., +33123456789)
email: Must be a valid email format if provided

Validation behavior:

If only phone is provided, it must be valid
If only email is provided, it must be valid
If both are provided, at least one must be valid
If neither is valid, the request will fail

Format Validation

birthdate: Must be in YYYY-MM-DD format if provided
invoice_date: Must be in YYYY-MM-DD format if provided
due_date: Must be in YYYY-MM-DD format if provided
phone: Validated and normalized to E.164 format. International format recommended (e.g., +33123456789). French numbers without country code (e.g., 0612345678 or 612345678) are automatically normalized to +33 format.
iban: Must be a valid IBAN if provided

Phone Validation

Phone numbers are validated against carrier databases. Invalid phones will be rejected with a specific error message:

"phone number too short" - Number has too few digits
"phone number too long" - Number has too many digits
"invalid country code" - Country code not recognized
"number format is not valid" - Number doesn’t match expected format
"number not registered in carrier database" - Number range not allocated to any carrier (may affect some overseas territories)

Business Rules

amount: Must be positive for a debt or negative for a credit note; zero is invalid
due_date: Should be after invoice_date if both are provided
internal_id: Should be unique within your company (recommended)
currency: Must be supported by the system
status: Automatically set to “pending” on creation. Status cannot be set via API and will change through internal workflows only.
timeline_id: Must be a valid encrypted timeline ID belonging to your company
timeline_start_mode: Only used when timeline_id is provided
Invalid timeline IDs are ignored for debts and rejected for credit notes

Expensive Destinations

A costly phone destination does not reject an otherwise valid debt. The successful response includes an expensive_destination_not_accepted warning when phone communications are restricted. The restriction applies only to that phone, including secondary-contact phones; email and postal reminders keep their normal behavior.

{
  "warnings": [{
    "code": "expensive_destination_not_accepted",
    "message": "Debt accepted; phone communications restricted for an expensive destination.",
    "field": "phone",
    "blocked_channels": ["sms", "rcs", "call", "whatsapp", "voicemail"]
  }]
}

Send "accept_expensive_destination": true to permit the costly phone communications. Send false to restrict them explicitly. This is based on configured pricing, not on whether a number is foreign.

Rate Limiting

This endpoint is subject to rate limiting. See the Rate Limits documentation for details. Rate Limit: 500 requests per hour (write operations)

Best Practices

Use Internal IDs

Always provide an internal_id to link the debt to your own systems and avoid duplicates.

Validate Data

Validate all data on your side before sending to reduce API errors and improve performance.

Handle Errors

Implement proper error handling to deal with validation failures and network issues.

Store Debt IDs

Store the returned encrypted id for future API calls - it’s the primary identifier.

Enable AI Workflows

Use timeline_id to automatically trigger AI-powered collection actions (calls, emails, SMS) based on your timeline configuration.

Control Start Timing

Use timeline_start_mode: "next_day" to respect business hours and excluded days when starting the collection process.

After Creation

Once a debt is created, you can:

Start followup activities using the Followups API
Update debt information using the Update Debt endpoint
Track collection progress by retrieving followup statistics
Generate reports that include this debt in your analytics

List Debts - Get all debts for your company
Get Debt - Retrieve a specific debt
Update Debt - Modify debt information
Create Followup - Start collection activities

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

Custom dynamic fields

Example Request

Success Response

Error Responses

Validation Rules

Rate Limiting

Best Practices

Use Internal IDs

Validate Data

Handle Errors

Store Debt IDs

Enable AI Workflows

Control Start Timing

After Creation

​Overview

​Authentication

​Custom dynamic fields

​Example Request

​Success Response

​Error Responses

​Validation Rules

​Rate Limiting

​Best Practices

Use Internal IDs

Validate Data

Handle Errors

Store Debt IDs

Enable AI Workflows

Control Start Timing

​After Creation

​Related Endpoints

Overview

Authentication

Custom dynamic fields

Example Request

Success Response

Error Responses

Validation Rules

Rate Limiting

Best Practices

After Creation

Related Endpoints