Batch Create Debts

Overview

This endpoint allows you to create multiple debt records in a single API call. It’s designed for bulk imports and can process up to 1,000 debts per request. Each debt 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

Authorization

string

required

Bearer token for authentication

Content-Type

string

required

Must be application/json

Request Body

batch_name

string

Custom name for this import batch (optional). Appears in the dashboard import filter. Default: “API Batch - DD/MM/YYYY HH:mm”

accept_expensive_destination

boolean

Batch-level opt-in for expensive destinations (DOM-TOM, Maghreb, etc.). When set to true, all debts in the batch with expensive destination phone numbers will be accepted. Can also be set per-debt inside the debts array. If not set, debts with expensive destination phones will fail validation with a specific error.

debts

array

required

Array of debt objects to create. Maximum 1,000 debts per request. Each debt object has the same structure as the Create Debt endpoint.

Show debt object fields

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.

amount

number

required

Debt amount (must be positive)

currency

string

required

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

string

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

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 enable AI-powered collection workflows (optional). See the Using Timelines guide for how to obtain timeline IDs (requires administrator access).

timeline_start_mode

string

When to start timeline processing (optional): "immediate" (default) or "next_day"

metadata

object

Custom metadata object for storing arbitrary JSON data (optional). Use this to store any additional information that your system needs to track. Returned in API responses and webhook payloads.

temp_id

string

Temporary ID you can use to track which debt this is in the response (optional)

accept_expensive_destination

boolean

Per-debt opt-in for expensive destinations. Overrides the batch-level setting for this specific debt. Required when the phone number is in a high-cost destination (DOM-TOM: 100 credits, Maghreb: 125 credits).

Example Request

curl -X POST "/external-api/v1/debts/batch" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_name": "January 2025 Invoices",
    "debts": [
      {
        "temp_id": "import-001",
        "firstname": "John",
        "lastname": "Doe",
        "civility": "Mr",
        "phone": "+33123456789",
        "email": "john.doe@example.com",
        "amount": 1250.00,
        "currency": "EUR",
        "object": "Invoice #INV-2024-001",
        "internal_id": "DEBT-2024-001",
        "due_date": "2023-12-31",
        "timeline_id": "xyz789abc123",
        "timeline_start_mode": "next_day",
        "metadata": {"crm_id": "CRM-001", "source": "batch_import"}
      },
      {
        "temp_id": "import-002",
        "firstname": "Jane",
        "lastname": "Smith",
        "civility": "Ms",
        "phone": "+33987654321",
        "email": "jane.smith@example.com",
        "amount": 750.00,
        "currency": "EUR",
        "object": "Invoice #INV-2024-002",
        "internal_id": "DEBT-2024-002",
        "due_date": "2023-12-31",
        "timeline_id": "xyz789abc123",
        "timeline_start_mode": "immediate",
        "metadata": {"crm_id": "CRM-002", "source": "batch_import"}
      }
    ]
  }'

Response

error

boolean

Always false for successful batch requests (even if some individual debts failed)

message

string

Success message

data

object

Batch operation results

Show data object

import_id

string

Encrypted ID of the Import record created for this batch. Use this to filter debts by import in the dashboard or track batches programmatically.

created

array

Array of successfully created debts

Show created item

index

integer

Original position in the input array

temp_id

string

Your temporary ID (if provided)

debt_id

string

Encrypted debt ID for subsequent API calls

status

string

Always "valid" for successfully created debts

data

object

Original input data for this debt

failed

array

Array of debts that failed validation or creation

Show failed item

index

integer

Original position in the input array

status

string

Always "error" for failed debts

errors

object

Detailed validation errors by field. Common error fields:

contact: At least one valid contact method required
phone: Invalid phone number format or unsupported prefix
email: Invalid email format
amount: Invalid amount or amount is zero/negative
firstname: First name is required
lastname: Last name is required
currency: Currency is required

data

object

Original input data for this debt (so you can identify which row failed)

skipped

array

Array of rows that were skipped (empty rows or instruction rows)

Show skipped item

index

integer

Original position in the input array

reason

string

Why this row was skipped (e.g., “Empty or instruction row”)

data

object

Original input data for this row

summary

object

Summary statistics

Show summary

total

integer

Total debts in the batch request

created

integer

Number successfully created

failed

integer

Number that failed validation

skipped

integer

Number of rows skipped (empty/instruction rows)

valid

integer

Number of valid rows (same as created)

error

integer

Number of rows with errors (same as failed)

Success Response

{
  "error": false,
  "message": "Batch operation completed",
  "data": {
    "import_id": "enc_imp_abc123xyz",
    "created": [
      {
        "index": 0,
        "temp_id": "import-001",
        "debt_id": "abc123def456",
        "status": "valid",
        "data": {
          "firstname": "John",
          "lastname": "Doe",
          "phone": "+33123456789",
          "email": "john.doe@example.com",
          "amount": 1250.00,
          "currency": "EUR"
        }
      },
      {
        "index": 1,
        "temp_id": "import-002",
        "debt_id": "ghi789jkl012",
        "status": "valid",
        "data": {
          "firstname": "Jane",
          "lastname": "Smith",
          "phone": "+33987654321",
          "email": "jane.smith@example.com",
          "amount": 750.00,
          "currency": "EUR"
        }
      }
    ],
    "failed": [],
    "skipped": [],
    "summary": {
      "total": 2,
      "created": 2,
      "failed": 0,
      "skipped": 0,
      "valid": 2,
      "error": 0
    }
  }
}

Partial Success Response

{
  "error": false,
  "message": "Batch operation completed",
  "data": {
    "import_id": "enc_imp_def456ghi",
    "created": [
      {
        "index": 0,
        "temp_id": "import-001",
        "debt_id": "abc123def456",
        "status": "valid",
        "data": {
          "firstname": "John",
          "lastname": "Doe",
          "phone": "+33123456789",
          "email": "john.doe@example.com",
          "amount": 1250.00,
          "currency": "EUR"
        }
      }
    ],
    "failed": [
      {
        "index": 1,
        "status": "error",
        "errors": {
          "phone": "Invalid phone number",
          "contact": "At least one valid contact method (email or phone) is required"
        },
        "data": {
          "firstname": "Jane",
          "lastname": "Smith",
          "phone": "0690123456",
          "email": "invalid-email",
          "amount": 750.00,
          "currency": "EUR"
        }
      },
      {
        "index": 3,
        "status": "error",
        "errors": {
          "firstname": "First name is required",
          "lastname": "Last name is required",
          "amount": "Valid amount (greater than 0) is required"
        },
        "data": {
          "phone": "+33123456789",
          "amount": 0,
          "currency": "EUR"
        }
      },
      {
        "index": 2,
        "errors": [
          "Invalid phone number: \"12345\" - phone number too short"
        ]
      },
      {
        "index": 4,
        "status": "error",
        "errors": {
          "phone": "Expensive destination: Réunion (RE) — 100 credits per AI call. Add \"accept_expensive_destination\": true to proceed."
        },
        "data": {
          "firstname": "Marc",
          "lastname": "Dupont",
          "phone": "+262692123456",
          "amount": 500.00,
          "currency": "EUR"
        }
      }
    ],
    "skipped": [
      {
        "index": 2,
        "reason": "Empty or instruction row",
        "data": {}
      }
    ],
    "summary": {
      "total": 4,
      "created": 1,
      "failed": 2,
      "skipped": 1,
      "valid": 1,
      "error": 2
    }
  }
}

Error Responses

{
  "error": true,
  "message": "No debts provided in payload",
  "code": 400
}

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.

Batch Limits

Maximum 1,000 debts per batch request
Each debt is validated individually
Failed debts don’t stop processing of successful ones

Individual Debt Validation

Each debt is validated using the same rules as the web import interface:Required Fields:

firstname: Debtor’s first name (required)
lastname: Debtor’s last name (required)
amount: Must be a positive number (> 0)
currency: Required, must be valid ISO 4217 code

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

Expensive Destinations

Phone numbers in certain regions cost significantly more credits for AI calls. Debts with expensive destination phones will fail validation unless you opt in:

Batch-level: Set "accept_expensive_destination": true at the top level (next to debts array) to accept all expensive destinations in the batch
Per-debt: Set "accept_expensive_destination": true on individual debt objects

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

Failed debts will include the destination details and cost in the errors field.

Timeline Processing

timeline_id: Must be valid and belong to your company
timeline_start_mode: Applies individually to each debt
Invalid timeline IDs are silently ignored per debt
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 format (avoid 069X French overseas mobile), email format, positive amounts, required fields.

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:

Store Debt IDs: Map returned debt_id values to your temp_id or internal_id
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
Handle Skipped Rows: Check the skipped array for empty or instruction rows that were automatically filtered
Monitor Workflows: If timelines are assigned, collection actions will start automatically for successfully created debts
Track Progress: Use the statistics endpoints to monitor collection progress

Create Debt - Create a single debt
List Debts - Get all debts for your company
Update Debt - Modify individual debts
Get Debt - Retrieve specific debt details

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

Partial Success Response

Error Responses

Validation Rules

Rate Limiting

Best Practices

Use temp_id

Handle Partial Success

Batch Size Strategy

Validate Before Sending

Use Detailed Error Messages

Timeline Assignment

Monitor Progress

Performance Considerations

After Batch 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

​Partial Success Response

​Error Responses

​Validation Rules

​Rate Limiting

​Best Practices

Use temp_id

Handle Partial Success

Batch Size Strategy

Validate Before Sending

Use Detailed Error Messages

Timeline Assignment

Monitor Progress

​Performance Considerations

​After Batch Creation

​Related Endpoints

Overview

Authentication

Request

Request Body

Example Request

Response

Success Response

Partial Success Response

Error Responses

Validation Rules

Rate Limiting

Best Practices

Performance Considerations

After Batch Creation

Related Endpoints