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.

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.

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

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",
    "detect_civility": true,
    "validate_emails": false,
    "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": "YOUR_TIMELINE_ID",
        "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": "YOUR_TIMELINE_ID",
        "timeline_start_mode": "immediate",
        "metadata": {"crm_id": "CRM-002", "source": "batch_import"}
      }
    ]
  }'

const debtsData = {
  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: "YOUR_TIMELINE_ID",
      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: "YOUR_TIMELINE_ID",
      timeline_start_mode: "immediate",
      metadata: { crm_id: "CRM-002", source: "batch_import" }
    }
  ]
};

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

const result = await response.json();

import requests

debts_data = {
    "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": "YOUR_TIMELINE_ID",
            "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": "YOUR_TIMELINE_ID",
            "timeline_start_mode": "immediate",
            "metadata": {"crm_id": "CRM-002", "source": "batch_import"}
        }
    ]
}

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

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

result = response.json()

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,
      "email_validation": {
        "valid": 0,
        "invalid": 0,
        "unverifiable": 0,
        "charged": 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"
        ]
      },
    ],
    "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
}

{
  "error": true,
  "message": "Maximum 1000 debts per batch request",
  "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 process batch request",
  "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.

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: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

Expensive Destinations

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 Processing

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:

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

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

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

​Overview

​Authentication

​Custom dynamic fields

​Example Request

​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

Custom dynamic fields

Example Request

Success Response

Partial Success Response

Error Responses

Validation Rules

Rate Limiting

Best Practices

Performance Considerations

After Batch Creation

Related Endpoints