POST
Batch Create Debts

​
Overview

This endpoint creates multiple debts and credit notes in a single API call. It’s designed for bulk imports and can process up to 1,000 rows per request. Each row is validated individually, and the endpoint returns both successful creations and any failures.

​
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
Custom name for this import batch (optional). Appears in the dashboard import filter. Default: “API Batch - DD/MM/YYYY HH:mm”
​
boolean
Default choice for costly phone destinations in this batch. true permits phone communications; false restricts SMS, RCS, calls, WhatsApp, and voicemail while retaining the debt and its email/postal reminders. A per-debt explicit boolean overrides this value, including false overriding a batch-level true. For debt synchronized through a campaign, the GetBill campaign configuration takes priority.
​
boolean
Enables automatic civility/title completion for created debts where 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 created debts in the batch. Default: false. Emails are deduplicated before validation. Charged at 1 credit per 5 billable validation results. Invalid addresses are saved but marked as suppressed to prevent sending.
​
array
required
Array of debt or credit note objects. Maximum 1,000 rows per request. Each object has the same structure as the Create Debt endpoint.
A batch may mix debts and credit notes. 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 must resolve an unambiguous timeline from timeline_id, the batch, or the company’s single timeline. Debtor names and contact details are not required.

​
Example Request

​
Response

​
boolean
Always false for successful batch requests (even if some individual debts failed)
​
string
Success message
​
object
Batch operation results

​
Success Response

​
Partial 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.
  • Maximum 1,000 debts per batch request
  • Each debt is validated individually
  • Failed debts don’t stop processing of successful ones
Each debt is validated using the same rules as the web import interface:Debt (amount > 0):
  • firstname and lastname: Required
  • 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 when no unambiguous batch or company timeline can be resolved
amount must not be zero and currency must be a valid ISO 4217 code.Debt contact information (at least one required):
  • phone OR email: At least one must be valid
  • phone: Must be a valid phone number. International format recommended (e.g., +33123456789)
    • Unsupported: French overseas mobile numbers with 069X prefix (e.g., 0690123456)
    • Supported: French mainland, most international numbers, French overseas fixed lines
  • email: Must be a valid email format
Optional Fields:
  • Date fields: Must be in YYYY-MM-DD format if provided
  • phone: Validated and normalized to E.164 format. French numbers without country code are automatically normalized. Invalid phones are rejected with specific error messages.
  • All other fields are optional
Automatic Skipping:
  • Empty rows are automatically skipped
  • Instruction rows (starting with *, containing “champs obligatoires”, etc.) are skipped
A costly phone destination does not fail an otherwise valid debt. The debt appears in created with an expensive_destination_not_accepted item in its warnings array when phone communications are restricted. Email and postal reminders remain available.Set "accept_expensive_destination": true at the batch level for the default, or set it on an individual debt to override the default. This is based on configured pricing, not on every foreign number.
  • timeline_id: Must be valid and belong to your company
  • timeline_start_mode: Applies individually to each debt
  • Invalid timeline IDs are ignored for debts and rejected for credit notes
  • Public holidays and excluded days are respected for next_day mode

​
Rate Limiting

This endpoint is subject to rate limiting. See the Rate Limits documentation for details. Rate Limit: 50 requests per hour (batch operations) Note: Each batch request can contain up to 1,000 debts, making this much more efficient than individual creation.

​
Best Practices

Use temp_id

Always provide a temp_id for each debt to easily match responses to your original data.

Handle Partial Success

Always check created, failed, and skipped arrays. Process successful debts, identify why failures occurred using the detailed errors field, and retry or fix validation issues.

Batch Size Strategy

While you can send 1,000 debts, consider batches of 100-500 for better error handling and progress tracking.

Validate Before Sending

Pre-validate data on your side to minimize API failures. Key checks: phone and email formats for debts, non-zero amounts, and the required identity and target references for credit notes.

Use Detailed Error Messages

Each failed debt includes the original data and specific field-level errors. Use this to build error reports for manual correction or automated retry logic.

Timeline Assignment

Assign the same timeline_id to all debts in a batch for consistent AI-powered collection workflows.

Monitor Progress

Use the summary object to track overall success rate and identify issues quickly.

​
Performance Considerations

  • All debts in a batch are processed in a single database transaction
  • Failed validations don’t affect successful creations
  • Expected processing time: ~100-500ms for 100 debts
  • Timeline calculations (next_day mode) add minimal overhead

​
After Batch Creation

Once debts are created via batch:
  1. Store Debt IDs: Map returned debt_id values to your temp_id or internal_id
  2. Process Failures: Review the failed array for validation errors. Each failed item includes:
    • Original data (data field) to identify which row failed
    • Detailed field-level errors (errors field) to understand why
    • Common fixes: Update invalid phone numbers (avoid 069X), fix email formats, ensure required fields
  3. Handle Skipped Rows: Check the skipped array for empty or instruction rows that were automatically filtered
  4. Monitor Workflows: If timelines are assigned, collection actions will start automatically for successfully created debts
  5. Track Progress: Use the statistics endpoints to monitor collection progress