Using Timelines for AI Workflows - GetBill External API

Overview

Timelines are predefined sequences of collection actions (AI calls, emails, SMS, WhatsApp messages) that automatically execute according to your configured schedule. By associating a timeline with a debt, you can trigger sophisticated AI-powered collection workflows without manual intervention.

What are Timelines?

A timeline defines:

Actions: What communication methods to use (AI calls, emails, SMS, etc.)
Timing: When each action should occur (days, hours, business days)
Conditions: Rules for when actions should execute or skip
Exclusions: Days when no actions should occur (weekends, holidays)

When you create a debt with a timeline_id, the system automatically schedules and executes these actions based on your timeline configuration.

Benefits of Using Timelines

Automation

Set up once, automate forever. Debts automatically follow your collection process.

AI-Powered

Leverage AI phone calls that adapt to debtor responses and gather structured data.

Consistency

Ensure every debt follows the same proven collection process.

Scale

Handle thousands of debts with automated follow-ups and smart scheduling.

Accessing Timeline IDs

To use timelines via the API, you need to access their encrypted IDs from your GetBill dashboard.

Requirements

To access timeline IDs, you must meet both requirements:

Administrator Access: You must be a company administrator
Active API Client: You must have created at least one OAuth client

This dual requirement ensures only authorized users with API integration needs can access timeline IDs for security purposes.

Finding Your Timeline IDs

Access your GetBill dashboard with an administrator account.

Navigate to Timeline Management

Go to the Timeline Management section from the main menu.

Open Timeline Details

Click on any existing timeline to view its details.

Copy the API ID

In the right panel, you’ll see an API ID box with a copy button. This is your encrypted timeline ID.

If you don’t see the API ID box in the timeline details:

Verify you have administrator access to your company
Ensure you have created at least one OAuth client in API Client Management
Contact your company administrator if needed

Using Timeline IDs in API Requests

Once you have a timeline ID, include it when creating debts to automatically trigger the collection workflow.

Create a Single Debt with Timeline

curl -X POST "https://getbill.io/external-api/v1/debts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+33123456789",
    "amount": 1250.00,
    "currency": "EUR",
    "timeline_id": "xyz789abc123",
    "timeline_start_mode": "next_day"
  }'

Batch Create Debts with Timeline

curl -X POST "https://getbill.io/external-api/v1/debts/batch" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "debts": [
      {
        "firstname": "John",
        "lastname": "Doe",
        "phone": "+33123456789",
        "amount": 500.00,
        "currency": "EUR"
      },
      {
        "firstname": "Jane",
        "lastname": "Smith",
        "phone": "+33987654321",
        "amount": 750.00,
        "currency": "EUR"
      }
    ],
    "timeline_id": "xyz789abc123",
    "timeline_start_mode": "next_day"
  }'

Timeline Start Modes

Control when the timeline processing should start using the timeline_start_mode parameter.

timeline_start_mode

string

Show options

immediate

string

Default behavior. Start processing immediately using the import date as the reference point. The first action will be scheduled relative to when the debt was created.

next_day

string

Recommended. Start processing on the next allowed business day. This mode:

Respects the timeline’s excluded days (e.g., weekends)
Honors configured public holidays
Ensures actions don’t start on non-business days
Provides more predictable scheduling for debtors

When to Use Each Mode

Immediate Mode
Next Day Mode

Best for:

Urgent collection cases
Real-time debt creation that needs immediate action
When you want actions to start as soon as possible

Example: A debt created on Friday at 3 PM with immediate mode will schedule the first action relative to Friday 3 PM, even if it falls on a weekend.

Timeline Validation

Valid Timeline IDs

Timeline must belong to your company
Timeline must be active and not archived
Timeline ID must be the encrypted format (visible in dashboard API ID field)

Invalid Timeline Handling

If an invalid timeline_id is provided, it will be silently ignored. The debt will be created successfully but without timeline association.

This means:

✅ The debt is created
❌ No automated actions are scheduled
ℹ️ No error is returned

Always verify that your timeline IDs are correct by checking that created debts have the timeline_id field populated in the response.

Example Workflow

Here’s a complete example of setting up and using timelines:

Create Timeline in Dashboard

Configure your collection timeline with actions:

Day 0: AI phone call
Day 3: Email reminder
Day 7: SMS reminder
Day 14: Final AI phone call

Get Timeline ID

Open the timeline details and copy the API ID (e.g., “xyz789abc123”)

Create Debts via API

Use the timeline ID when creating debts:

const response = await fetch('/external-api/v1/debts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    firstname: "John",
    lastname: "Doe",
    phone: "+33123456789",
    amount: 1250.00,
    currency: "EUR",
    timeline_id: "xyz789abc123",
    timeline_start_mode: "next_day"
  })
});

Actions Execute Automatically

The system will now:

Schedule all timeline actions
Execute AI calls at configured times
Send emails and SMS as scheduled
Track all responses and outcomes

Monitor Progress

Use the Followups API to track action results:

curl -X GET "https://getbill.io/external-api/v1/followups?debt_id=abc123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Best Practices

Use next_day for Batch Imports

When importing large batches of debts, always use timeline_start_mode: "next_day" to:

Distribute actions across business days
Avoid overwhelming your AI calling capacity
Provide better debtor experience
Respect business hours consistently

Test with Small Batches First

Before importing thousands of debts:

Test with 5-10 debts
Verify timeline actions are scheduled correctly
Check that actions execute as expected
Adjust timeline configuration if needed

Store Timeline IDs Securely

Store timeline IDs in your configuration/environment
Don’t hardcode them in your application
Use different timelines for different debt types
Document which timeline is used for which scenario

Monitor Timeline Performance

Regularly check:

Action success rates
Debtor response rates
Collection effectiveness
Timeline completion rates

Adjust your timeline configuration based on these metrics.

Handle Timeline Updates

When you update a timeline configuration:

Existing debts continue with old configuration
New debts use the updated configuration
Plan timeline changes during low-volume periods

Common Use Cases

Basic Collection Timeline

// Standard 30-day collection process
{
  "timeline_id": "basic_30day_timeline",
  "timeline_start_mode": "next_day"
}

Actions: Call → Email → SMS → Final Call over 30 days

Urgent Collection Timeline

// Accelerated 7-day collection for urgent cases
{
  "timeline_id": "urgent_7day_timeline",
  "timeline_start_mode": "immediate"
}

Actions: Immediate call → Email (day 2) → SMS (day 4) → Final call (day 7)

Soft Reminder Timeline

// Gentle reminder process for valued customers
{
  "timeline_id": "soft_reminder_timeline",
  "timeline_start_mode": "next_day"
}

Actions: Email → SMS → Polite call over 45 days

Troubleshooting

Timeline ID not visible in dashboard

Problem: Can’t see the API ID box in timeline details.Solution:

Verify you’re logged in as an administrator
Check that you’ve created at least one OAuth client
Refresh the page after creating an OAuth client
Contact support if still not visible

Debt created but no actions scheduled

Problem: Debt is created successfully but timeline actions don’t execute.Solution:

Verify the timeline_id in the API response matches what you sent
Check if the timeline is active in your dashboard
Ensure the timeline has configured actions
Verify your company has sufficient credits for AI calls/SMS

Actions starting at wrong time

Problem: Timeline actions don’t respect business hours.Solution:

Use timeline_start_mode: "next_day" instead of immediate
Check excluded days configuration in your timeline
Verify public holiday calendar is configured
Check timeline timezone settings

Invalid timeline ID error

Problem: Getting validation errors about timeline ID.Solution:

Use the encrypted ID from the dashboard, not the numeric ID
Ensure the timeline belongs to your company
Check that the timeline hasn’t been deleted
Verify you’re using the correct OAuth client for your company

API Reference

For detailed parameter information, see:

Create Debt - Single debt creation with timeline
Batch Create Debts - Bulk debt creation with timeline
Get Followups - Monitor timeline action results

Next Steps

Create Your First Timeline

Set up a basic collection timeline in your dashboard with a few simple actions.

Test API Integration

Create test debts with your timeline ID and verify actions are scheduled.

Configure AI Voice

Set up your AI voice agent and conversation scripts for phone calls.

Monitor Results

Track timeline performance and optimize your collection strategy.

Guides

​Overview

​What are Timelines?

​Benefits of Using Timelines

Automation

AI-Powered

Consistency

Scale

​Accessing Timeline IDs

​Requirements

​Finding Your Timeline IDs

​Using Timeline IDs in API Requests

​Create a Single Debt with Timeline

​Batch Create Debts with Timeline

​Timeline Start Modes

​When to Use Each Mode

​Timeline Validation

​Valid Timeline IDs

​Invalid Timeline Handling

​Example Workflow

​Best Practices

​Common Use Cases

​Basic Collection Timeline

​Urgent Collection Timeline

​Soft Reminder Timeline

​Troubleshooting

​API Reference

​Next Steps

Create Your First Timeline

Test API Integration

Configure AI Voice

Monitor Results

Overview

What are Timelines?

Benefits of Using Timelines

Accessing Timeline IDs

Requirements

Finding Your Timeline IDs

Using Timeline IDs in API Requests

Create a Single Debt with Timeline

Batch Create Debts with Timeline

Timeline Start Modes

When to Use Each Mode

Timeline Validation

Valid Timeline IDs

Invalid Timeline Handling

Example Workflow

Best Practices

Common Use Cases

Basic Collection Timeline

Urgent Collection Timeline

Soft Reminder Timeline

Troubleshooting

API Reference

Next Steps