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

​
Request

​
string
required
Bearer token for authentication
​
string
required
Must be application/json

​
Request Body

​
string
Debtor’s first name. Required for debts; optional for credit notes.
​
string
Debtor’s last name. Required for debts; optional for credit notes.
​
string
Civility/title (optional). Possible values: "Mr" or "Ms"
​
string
Debtor’s phone number (international format recommended). For debts, at least one of phone or email must be valid. Optional for credit notes. Note: French overseas mobile numbers with 069X prefix are not supported.
​
string
Debtor’s email address. For debts, at least one of phone or email must be valid. Optional for credit notes.
​
number
required
Positive debt amount or negative credit note amount. Zero is invalid.
​
string
required
Currency code (ISO 4217 format, e.g., “EUR”, “USD”)
​
string
Debtor’s birth date in YYYY-MM-DD format (optional)
​
string
Description of what the debt is for (optional)
​
string
Your internal reference ID. For a credit note, either internal_id or invoice_reference is required as its stable identity.
​
string
Invoice reference number. For a credit note, either internal_id or invoice_reference is required as its stable identity.
​
string
Invoice reference to credit. For a credit note, either credited_invoice_reference or debtor_reference is required as its target.
​
string
Your reference for the debtor. For a credit note, either credited_invoice_reference or debtor_reference is required as its target. When a credit note targets only debtor_reference, provide timeline_id unless your company has exactly one timeline.
​
string
Original invoice date in YYYY-MM-DD format (optional)
​
string
Payment due date in YYYY-MM-DD format (optional)
​
string
Debtor’s full address (optional)
​
string
IBAN where payment should be made (optional)
​
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.
​
string
Debtor’s company name, if the debtor is a business (optional)
​
string
Street address (optional). Can be used with other address fields for structured address data
​
string
Street number (optional)
​
string
Postal/ZIP code (optional)
​
string
City name (optional)
​
string
Country code in ISO 3166-1 alpha-2 format, e.g. “FR”, “US” (optional)
​
string
Custom payment link URL for this debt (optional)
​
string
Encrypted timeline ID to associate with this debt (optional). It is required for a credit note that targets only debtor_reference when your company has multiple timelines. Credit notes that target credited_invoice_reference can infer the timeline from the matching invoice. 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.
​
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)
​
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.
​
boolean
Controls phone communications to destinations whose configured AI-call price is at least 50 credits. Set true to allow them. Set false to restrict SMS, RCS, calls, WhatsApp, and voicemail for that phone while retaining the debt and allowing email and postal reminders. For a new phone, omitting the field has the same restrictive effect. For an unchanged existing phone, omission preserves its recorded choice. The field accepts JSON booleans only. For debt synchronized through a campaign, the GetBill campaign configuration takes priority.
​
boolean
Enables automatic civility/title completion when civility is missing and firstname is present. Default: true. Charged at 1 credit per 100 debts needing civility detection, rounded up.
​
boolean
Enables email deliverability validation for the provided email address. Default: false. Charged at 1 credit per 5 billable validation results. Invalid addresses are saved but marked as suppressed to prevent sending.
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

​
Response

​
boolean
Always false for successful requests
​
string
Success message
​
object
The created debt object or credit note result

​
Success Response

​
Error Responses

​
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.
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.
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
  • 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 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)
  • 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
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.
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:
  1. Start followup activities using the Followups API
  2. Update debt information using the Update Debt endpoint
  3. Track collection progress by retrieving followup statistics
  4. Generate reports that include this debt in your analytics