GET
/
external-api
/
v1
/
followups
List Followups
curl --request GET \
  --url https://getbill.io/external-api/v1/followups \
  --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": "Successfully contacted debtor",
      "notes": "Customer agreed to payment plan starting next month",
      "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"
    }
  ],
  "pagination": {
    "total": 1247,
    "page": 1,
    "limit": 50,
    "pages": 25
  }
}

​
Overview

This endpoint returns a paginated list of all followup activities for debts belonging to your company. You can filter by status, type, date range, and other criteria.

​
Authentication

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

​
Request

​
Authorization
string
required
Bearer token for authentication

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination
​
limit
integer
default:"20"
Number of items per page (maximum 100)
​
status
string
Filter by followup status. Use simple string values: on_hold, scheduled, in_progress, sent, delivered, deal_found, no_answer, deal_not_found, bad_behavior, failed, cancelled
​
type
string
Filter by followup type: call, email, sms, whatsapp, voicemail, manual_call, physical, postmail
​
date_from
string
Filter followups from this date (YYYY-MM-DD)
​
date_to
string
Filter followups to this date (YYYY-MM-DD)
​
debt_id
string
Filter followups for a specific debt (encrypted ID)

​
Example Request

curl -X GET "/external-api/v1/followups?status=delivered&type=call&limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Response

​
error
boolean
Always false for successful requests
​
data
array
Array of followup objects
​
pagination
object
Pagination metadata

​
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": "Successfully contacted debtor",
      "notes": "Customer agreed to payment plan starting next month",
      "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"
    }
  ],
  "pagination": {
    "total": 1247,
    "page": 1,
    "limit": 50,
    "pages": 25
  }
}

​
Error Responses

{
  "error": true,
  "message": "Authentication credentials are missing or invalid",
  "code": 401
}

​
Rate Limiting

This endpoint is subject to rate limiting. See the Rate Limits documentation for details. Rate Limit: 1,000 requests per hour