POST
/
external-api
/
v1
/
debts
Create Debt
curl --request POST \
  --url https://getbill.io/external-api/v1/debts \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "firstname": "<string>",
  "lastname": "<string>",
  "civility": "<string>",
  "phone": "<string>",
  "email": "<string>",
  "amount": 123,
  "currency": "<string>",
  "birthdate": "<string>",
  "object": "<string>",
  "internal_id": "<string>",
  "invoice_reference": "<string>",
  "debtor_reference": "<string>",
  "invoice_date": "<string>",
  "due_date": "<string>",
  "address": "<string>",
  "iban": "<string>",
  "company": "<string>",
  "debtor_company": "<string>",
  "street_address": "<string>",
  "street_number": "<string>",
  "postal_code": "<string>",
  "city": "<string>",
  "country": "<string>",
  "payment_link": "<string>",
  "timeline_id": "<string>",
  "timeline_start_mode": "<string>",
  "metadata": {},
  "accept_expensive_destination": true,
  "detect_civility": true,
  "validate_emails": true
}
'
{
  "error": false,
  "message": "Debt created successfully",
  "data": {
    "id": "abc123def456",
    "civility": "Mr",
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+33123456789",
    "email": "john.doe@example.com",
    "email_validation": {
      "status": "valid",
      "reason": "accepted_email",
      "charged": true,
      "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_reference": "INV-2024-001",
    "debtor_reference": "DEB-DOE-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,
    "payment_plan_active": false,
    "plan_start_date": null,
    "contacts": []
  }
}

​
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.
​
email
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_reference
string
Invoice reference number for this debt (optional). Used for matching debts during upsert imports and displayed in communications.
​
debtor_reference
string
Your reference for the debtor (optional). A cross-reference identifier to link this debt to the debtor in your own system.
​
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.
​
detect_civility
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.
​
validate_emails
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.

​
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_reference": "INV-2024-001",
    "debtor_reference": "DEB-DOE-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",
    "detect_civility": true,
    "validate_emails": false,
    "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

​
Success Response

{
  "error": false,
  "message": "Debt created successfully",
  "data": {
    "id": "abc123def456",
    "civility": "Mr",
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+33123456789",
    "email": "john.doe@example.com",
    "email_validation": {
      "status": "valid",
      "reason": "accepted_email",
      "charged": true,
      "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_reference": "INV-2024-001",
    "debtor_reference": "DEB-DOE-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,
    "payment_plan_active": false,
    "plan_start_date": null,
    "contacts": []
  }
}

​
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.
  • 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
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 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.
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.
DestinationCredits per callMultiplier
France (mainland)251.0x
EU countries301.2x
DOM-TOM (Réunion, Guadeloupe, Martinique, French Guiana, Mayotte, New Caledonia, French Polynesia, etc.)1004.0x
Maghreb (Morocco, Algeria, Tunisia)1255.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:
  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