Get Followups by Debt

curl --request GET \
  --url https://getbill.io/external-api/v1/followups/debt/{debtId} \
  --header 'Authorization: <authorization>'

{
  "error": false,
  "data": [
    {
      "id": "abc123def456",
      "debt_id": "xyz789ghi012",
      "status": "deal_found",
      "type": "call",
      "call_date": "2024-01-22T10:30:00+00:00",
      "scheduled_at": "2024-01-22T10:00:00+00:00",
      "summary": "Initial contact attempt - successful",
      "notes": "Customer answered, discussed payment options",
      "call_id": "call_789456",
      "audio_url": "https://s3.amazonaws.com/bucket/recordings/call_789456.mp3?X-Amz-Signature=...",
      "pdf_url": null,
      "duration_ms": 180000,
      "disconnection_reason": "completed_successfully",
      "direction": "outbound",
      "phone_number_used": "+33800123456",
      "is_retry": false,
      "processed_at": "2024-01-22T10:35:00+00:00",
      "triggered_payment": true,
      "email_opened": false,
      "email_open_count": 0,
      "email_first_opened_at": null,
      "email_clicked": false,
      "email_click_count": 0,
      "media_urls_expire_at": "2024-01-22T11:35:00+00:00"
    },
    {
      "id": "def456ghi789",
      "debt_id": "xyz789ghi012",
      "status": "delivered",
      "type": "email",
      "call_date": "2024-01-20T14:15:00+00:00",
      "scheduled_at": "2024-01-20T14:00:00+00:00",
      "summary": "Payment reminder sent",
      "notes": "Automated reminder email with payment instructions",
      "call_id": null,
      "audio_url": null,
      "pdf_url": null,
      "duration_ms": null,
      "disconnection_reason": null,
      "direction": null,
      "phone_number_used": null,
      "is_retry": false,
      "processed_at": "2024-01-20T14:15:00+00:00",
      "triggered_payment": false,
      "email_opened": true,
      "email_open_count": 3,
      "email_first_opened_at": "2024-01-20T15:30:00+00:00",
      "email_clicked": true,
      "email_click_count": 1
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

GET

external-api

followups

debt

{debtId}

Get Followups by Debt

curl --request GET \
  --url https://getbill.io/external-api/v1/followups/debt/{debtId} \
  --header 'Authorization: <authorization>'

{
  "error": false,
  "data": [
    {
      "id": "abc123def456",
      "debt_id": "xyz789ghi012",
      "status": "deal_found",
      "type": "call",
      "call_date": "2024-01-22T10:30:00+00:00",
      "scheduled_at": "2024-01-22T10:00:00+00:00",
      "summary": "Initial contact attempt - successful",
      "notes": "Customer answered, discussed payment options",
      "call_id": "call_789456",
      "audio_url": "https://s3.amazonaws.com/bucket/recordings/call_789456.mp3?X-Amz-Signature=...",
      "pdf_url": null,
      "duration_ms": 180000,
      "disconnection_reason": "completed_successfully",
      "direction": "outbound",
      "phone_number_used": "+33800123456",
      "is_retry": false,
      "processed_at": "2024-01-22T10:35:00+00:00",
      "triggered_payment": true,
      "email_opened": false,
      "email_open_count": 0,
      "email_first_opened_at": null,
      "email_clicked": false,
      "email_click_count": 0,
      "media_urls_expire_at": "2024-01-22T11:35:00+00:00"
    },
    {
      "id": "def456ghi789",
      "debt_id": "xyz789ghi012",
      "status": "delivered",
      "type": "email",
      "call_date": "2024-01-20T14:15:00+00:00",
      "scheduled_at": "2024-01-20T14:00:00+00:00",
      "summary": "Payment reminder sent",
      "notes": "Automated reminder email with payment instructions",
      "call_id": null,
      "audio_url": null,
      "pdf_url": null,
      "duration_ms": null,
      "disconnection_reason": null,
      "direction": null,
      "phone_number_used": null,
      "is_retry": false,
      "processed_at": "2024-01-20T14:15:00+00:00",
      "triggered_payment": false,
      "email_opened": true,
      "email_open_count": 3,
      "email_first_opened_at": "2024-01-20T15:30:00+00:00",
      "email_clicked": true,
      "email_click_count": 1
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

Overview

This endpoint returns a paginated list of all followup activities associated with a specific debt. This is useful for getting the complete communication history for a particular debtor.

Authentication

Requires a valid OAuth 2.0 access token with the followups:read scope.

Request

Authorization

string

required

Bearer token for authentication

debtId

string

required

The encrypted ID of the debt to get followups for

Query Parameters

page

integer

default:"1"

Page number for pagination

limit

integer

default:"20"

Number of items per page (maximum 100)

Example Request

curl -X GET "/external-api/v1/followups/debt/xyz789ghi012?limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

error

boolean

Always false for successful requests

data

array

Array of followup objects for the specified debt

Show followup object

string

Encrypted followup identifier

debt_id

string

Encrypted debt identifier (matches the requested debtId)

status

string

Followup status: on_hold, scheduled, in_progress, sent, delivered, deal_found, no_answer, deal_not_found, bad_behavior, failed, cancelled

type

string

Type of followup: call, email, sms, whatsapp, voicemail, manual_call, physical, postmail

call_date

string

When the followup was executed (ISO 8601 format)

scheduled_at

string

When the followup was scheduled (ISO 8601 format)

summary

string

Brief summary of the followup

notes

string

Detailed notes about the followup

call_id

string

External call ID from the provider

audio_url

string

Pre-signed URL to the call recording (expires after 1 hour)

pdf_url

string

Pre-signed URL to any associated PDF document (expires after 1 hour)

duration_ms

integer

Duration in milliseconds (for calls)

disconnection_reason

string

Reason for call disconnection

direction

string

Call direction: inbound or outbound

phone_number_used

string

Phone number used for the followup

is_retry

boolean

Whether this is a retry attempt

processed_at

string

Processing timestamp (ISO 8601 format)

triggered_payment

boolean

Whether this followup directly triggered a successful payment

email_opened

boolean

Whether the email was opened (for email followups)

email_open_count

integer

Number of times the email was opened

email_first_opened_at

string

Timestamp of first email open (ISO 8601 format)

email_clicked

boolean

Whether a link in the email was clicked

email_click_count

integer

Number of times links in the email were clicked

media_urls_expire_at

string

When the pre-signed media URLs expire (ISO 8601 format). Only present if audio_url or pdf_url are provided.

pagination

object

Pagination metadata

Show pagination

total

integer

Total number of followups for this debt

page

integer

Current page number

limit

integer

Items per page

pages

integer

Total number of pages

Success Response

{
  "error": false,
  "data": [
    {
      "id": "abc123def456",
      "debt_id": "xyz789ghi012",
      "status": "deal_found",
      "type": "call",
      "call_date": "2024-01-22T10:30:00+00:00",
      "scheduled_at": "2024-01-22T10:00:00+00:00",
      "summary": "Initial contact attempt - successful",
      "notes": "Customer answered, discussed payment options",
      "call_id": "call_789456",
      "audio_url": "https://s3.amazonaws.com/bucket/recordings/call_789456.mp3?X-Amz-Signature=...",
      "pdf_url": null,
      "duration_ms": 180000,
      "disconnection_reason": "completed_successfully",
      "direction": "outbound",
      "phone_number_used": "+33800123456",
      "is_retry": false,
      "processed_at": "2024-01-22T10:35:00+00:00",
      "triggered_payment": true,
      "email_opened": false,
      "email_open_count": 0,
      "email_first_opened_at": null,
      "email_clicked": false,
      "email_click_count": 0,
      "media_urls_expire_at": "2024-01-22T11:35:00+00:00"
    },
    {
      "id": "def456ghi789",
      "debt_id": "xyz789ghi012",
      "status": "delivered",
      "type": "email",
      "call_date": "2024-01-20T14:15:00+00:00",
      "scheduled_at": "2024-01-20T14:00:00+00:00",
      "summary": "Payment reminder sent",
      "notes": "Automated reminder email with payment instructions",
      "call_id": null,
      "audio_url": null,
      "pdf_url": null,
      "duration_ms": null,
      "disconnection_reason": null,
      "direction": null,
      "phone_number_used": null,
      "is_retry": false,
      "processed_at": "2024-01-20T14:15:00+00:00",
      "triggered_payment": false,
      "email_opened": true,
      "email_open_count": 3,
      "email_first_opened_at": "2024-01-20T15:30:00+00:00",
      "email_clicked": true,
      "email_click_count": 1
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "limit": 50,
    "pages": 1
  }
}

Use Cases

This endpoint is particularly useful for:

Complete Communication History: Get all interactions with a specific debtor
Timeline Analysis: Understand the progression of collection efforts
Performance Tracking: Analyze success rates for different followup types
Compliance: Maintain complete records of collection activities

Error Responses

{
  "error": true,
  "message": "Access denied to this debt",
  "code": 403
}

List Followups - Get all followups
Get Followup - Get specific followup details
Get Debt - Get the associated debt information

Get Followup Create Followup

Company API

Creditors API

Debtors API

Debts API

Followups API

Reports API

Todos API

Status API

Get Followups by Debt

Overview

Authentication

Request

Query Parameters

Example Request

Response

Success Response

Use Cases

Error Responses

Company API

Creditors API

Debtors API

Debts API

Followups API

Reports API

Todos API

Status API

​Overview

​Authentication

​Request

​Query Parameters

​Example Request

​Response

​Success Response

​Use Cases

​Error Responses

​Related Endpoints

Overview

Authentication

Request

Query Parameters

Example Request

Response

Success Response

Use Cases

Error Responses

Related Endpoints