POST
/
external-api
/
v1
/
followups
Create Followup
curl --request POST \
  --url https://getbill.io/external-api/v1/followups \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "debt_id": "<string>",
  "type": "<string>",
  "status": "<string>",
  "call_date": "<string>",
  "scheduled_at": "<string>",
  "summary": "<string>",
  "notes": "<string>",
  "call_id": "<string>",
  "audio_url": "<string>",
  "duration_ms": 123,
  "phone_number_used": "<string>",
  "direction": "<string>",
  "disconnection_reason": "<string>",
  "is_retry": true
}
'
{
  "error": false,
  "message": "Followup created successfully",
  "data": {
    "id": "abc123def456",
    "debt_id": "xyz789ghi012",
    "status": "scheduled",
    "type": "call",
    "call_date": null,
    "scheduled_at": "2024-01-25T10:00:00+00:00",
    "summary": "Follow-up call to discuss payment plan",
    "notes": "Customer previously expressed interest in monthly payment schedule",
    "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-22T15:30:00+00:00"
  }
}

​
Overview

This endpoint allows you to create a new followup activity for an existing debt. You can log calls, emails, SMS, or other communication activities.

​
Authentication

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

​
Request

​
Authorization
string
required
Bearer token for authentication
​
Content-Type
string
required
Must be application/json

​
Request Body

​
debt_id
string
required
Encrypted ID of the debt this followup belongs to
​
type
string
Type of followup: call, email, sms, whatsapp, voicemail, manual_call, physical, postmail
​
status
string
Followup status. Use simple string values: on_hold, scheduled, in_progress, sent, delivered, deal_found, no_answer, deal_not_found, bad_behavior, failed, cancelled. Defaults to on_hold.
​
call_date
string
When the followup was executed (ISO 8601 format)
​
scheduled_at
string
When to execute the followup (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
URL to the call recording
​
duration_ms
integer
Duration in milliseconds (for calls)
​
phone_number_used
string
Phone number used for the followup
​
direction
string
Call direction: inbound or outbound
​
disconnection_reason
string
Reason for call disconnection
​
is_retry
boolean
Whether this is a retry attempt

​
Example Request

curl -X POST "/external-api/v1/followups" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "debt_id": "xyz789ghi012",
    "type": "call",
    "status": "scheduled",
    "scheduled_at": "2024-01-25T10:00:00Z",
    "summary": "Follow-up call to discuss payment plan",
    "notes": "Customer previously expressed interest in monthly payment schedule"
  }'

​
Response

​
error
boolean
Always false for successful requests
​
message
string
Success message
​
data
object
The created followup object

​
Success Response

{
  "error": false,
  "message": "Followup created successfully",
  "data": {
    "id": "abc123def456",
    "debt_id": "xyz789ghi012",
    "status": "scheduled",
    "type": "call",
    "call_date": null,
    "scheduled_at": "2024-01-25T10:00:00+00:00",
    "summary": "Follow-up call to discuss payment plan",
    "notes": "Customer previously expressed interest in monthly payment schedule",
    "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-22T15:30:00+00:00"
  }
}

​
Validation Rules

  • debt_id: Must be a valid encrypted debt ID that belongs to your company
  • type: Must be one of: call, sms, email, whatsapp, voicemail, manual_call, physical, postmail
  • status: Must be one of: on_hold, scheduled, in_progress, sent, delivered, deal_found, no_answer, deal_not_found, bad_behavior, failed, cancelled
  • Default is on_hold if not specified
  • scheduled_at: Must be in ISO 8601 format if provided
  • call_date: Must be in ISO 8601 format if provided

​
Error Responses

{
  "error": true,
  "message": "Validation failed",
  "code": 400,
  "details": {
    "debt_id": "Debt ID is required",
    "type": "Invalid followup type. Valid types are: call, sms, email, whatsapp, voicemail, manual_call, physical, postmail"
  }
}

​
After Creation

Once a followup is created, you can:
  1. Monitor Progress: Use Get Followup to check status
  2. Update Details: Use Update Followup to modify information
  3. Track Results: View completion status and outcomes
  4. Generate Reports: Include followup data in your analytics