Create Debt

Overview

This endpoint allows you to create a new debt record. The debt will be associated with your authenticated company and can immediately be used for followup activities.

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

Request Body

firstname

string

required

Debtor’s first name

lastname

string

required

Debtor’s last name

civility

string

Civility/title (optional). Possible values: "Mr" or "Ms"

phone

string

Debtor’s phone number (international format recommended). At least one of phone or email must be valid. Note: French overseas mobile numbers with 069X prefix are not supported.

string

Debtor’s email address. At least one of phone or email must be valid.

amount

number

required

Debt amount (must be positive)

currency

string

required

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

birthdate

string

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

object

string

Description of what the debt is for (optional)

internal_id

string

Your internal reference ID for this debt (optional)

invoice_date

string

Original invoice date in YYYY-MM-DD format (optional)

due_date

string

Payment due date in YYYY-MM-DD format (optional)

address

string

Debtor’s full address (optional)

iban

string

IBAN where payment should be made (optional)

company

string

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

debtor_company

string

Debtor’s company name, if the debtor is a business (optional)

street_address

string

Street address (optional). Can be used with other address fields for structured address data

street_number

string

Street number (optional)

postal_code

string

Postal/ZIP code (optional)

city

string

City name (optional)

country

string

Country code in ISO 3166-1 alpha-2 format, e.g. “FR”, “US” (optional)

payment_link

string

Custom payment link URL for this debt (optional)

timeline_id

string

Encrypted timeline ID to associate with this debt (optional). When provided, the debt will be automatically processed according to the timeline’s actions (calls, emails, SMS, etc.). Use this to enable AI-powered collection workflows.How to get timeline IDs: See the Using Timelines guide for detailed instructions. You must be a company administrator and have created an OAuth client to view timeline IDs in your dashboard.

timeline_start_mode

string

Controls when the timeline processing should start (optional). Only used when timeline_id is provided. Options:

"immediate" (default): Start processing immediately using the import date
"next_day": Start processing on the next allowed business day (respects timeline’s excluded days and public holidays)

metadata

object

Custom metadata object for storing arbitrary JSON data (optional). 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. This field is returned in API responses and webhook payloads.

accept_expensive_destination

boolean

Required opt-in flag when the phone number belongs to an expensive destination (DOM-TOM, Maghreb, etc.). AI calls to these destinations cost significantly more credits (e.g., 100 for DOM-TOM, 125 for Maghreb vs. 25 for France). If the phone number is in an expensive destination and this flag is not set to true, the request will be rejected with a 422 error detailing the destination and cost. Set to true to acknowledge the higher cost and proceed.

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_date": "2023-12-01",
    "due_date": "2023-12-31",
    "address": "123 Main Street, 75001 Paris, France",
    "iban": "FR1420041010050500013M02606",
    "company": "Acme Corp",
    "timeline_id": "xyz789abc123",
    "timeline_start_mode": "next_day",
    "metadata": {"crm_id": "CRM-123", "source": "website", "priority": "high"}
  }'

Response

error

boolean

Always false for successful requests

message

string

Success message

data

object

The created debt object with all fields populated

Show debt object

string

Encrypted debt identifier (use this for subsequent API calls)

firstname

string

Debtor’s first name

lastname

string

Debtor’s last name

civility

string

Civility/title

phone

string

Debtor’s phone number

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

object

string

Description of the debt

internal_id

string

Your internal reference ID

invoice_date

string

Original invoice date (YYYY-MM-DD format)

due_date

string

Payment due date (YYYY-MM-DD format)

address

string

Debtor’s full address

street_address

string

Street address

street_number

string

Street number

postal_code

string

Postal/ZIP code

city

string

City name

country

string

Country code (ISO 3166-1 alpha-2)

status

string

Current debt status (always “Pending” for newly created debts). Read-only - changes through internal workflows only.

nb_reminders

integer

Number of reminders sent (initially 0)

nb_answered

integer

Number of responses received (initially 0)

summary

string

Summary or notes

iban

string

IBAN for payment

timeline_id

string

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

followups_count

integer

Number of followups (initially 0)

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 for this debt

metadata

object

Custom metadata object containing arbitrary JSON data. Returns null if no metadata was provided.

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_start_mode and internal workflows.

Success Response

{
  "error": false,
  "message": "Debt created successfully",
  "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_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": "xyz789abc123",
    "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
  }
}

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

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

firstname: Must not be empty
lastname: Must not be empty
amount: Must be a positive number (> 0)
currency: Must be a valid ISO 4217 currency code

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 greater than 0
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 silently ignored.

Expensive Destinations

Phone numbers in certain regions cost significantly more credits for AI calls. If a phone number is detected in an expensive destination, the request will be rejected with a 422 error unless you include "accept_expensive_destination": true.

Destination	Credits per call	Multiplier
France (mainland)	25	1.0x
EU countries	30	1.2x
DOM-TOM (Réunion, Guadeloupe, Martinique, French Guiana, Mayotte, New Caledonia, French Polynesia, etc.)	100	4.0x
Maghreb (Morocco, Algeria, Tunisia)	125	5.0x

The 422 response includes full destination details (country code, name, credits, multiplier) so you can make an informed decision before retrying with the opt-in flag.

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

Company API

Creditors API

Debtors API

Debts API

Followups API

Reports API

Todos API

Status API

Overview

Authentication

Request

Request Body

Example Request

Response

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

Company API

Creditors API

Debtors API

Debts API

Followups API

Reports API

Todos API

Status API

​Overview

​Authentication

​Request

​Request Body

​Example Request

​Response

​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

Request

Request Body

Example Request

Response

Success Response

Error Responses

Validation Rules

Rate Limiting

Best Practices

After Creation

Related Endpoints