PUT
/
external-api
/
v1
/
followups
/
{id}
Update Followup
curl --request PUT \
  --url https://getbill.io/external-api/v1/followups/{id} \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "status": "<string>",
  "type": "<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 updated successfully",
  "data": {
    "id": "abc123def456",
    "debt_id": "xyz789ghi012",
    "status": "deal_found",
    "type": "call",
    "call_date": "2024-01-25T10:15:00+00:00",
    "scheduled_at": "2024-01-25T10:00:00+00:00",
    "summary": "Successful contact, payment plan agreed",
    "notes": "Customer agreed to pay €500 monthly starting February 1st.",
    "call_id": "call_789456",
    "audio_url": "https://s3.amazonaws.com/bucket/recordings/call_789456.mp3?X-Amz-Signature=...",
    "pdf_url": null,
    "duration_ms": 240000,
    "disconnection_reason": "completed_successfully",
    "direction": "outbound",
    "phone_number_used": "+33800123456",
    "is_retry": false,
    "processed_at": "2024-01-25T10:20:00+00:00",
    "media_urls_expire_at": "2024-01-25T11:20:00+00:00"
  }
}

​
Overview

This endpoint allows you to update information for an existing followup. You can modify status, add results, update notes, and record completion details. Note that the debt_id cannot be changed.

​
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
​
id
string
required
The encrypted ID of the followup to update

​
Request Body

All fields are optional. Only include the fields you want to update.
​
status
string
Update the 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
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 to execute the followup (ISO 8601 format)
​
summary
string
Brief summary of the followup results
​
notes
string
Detailed notes about what happened during the followup
​
call_id
string
External call ID from the provider
​
audio_url
string
URL to 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 PUT "/external-api/v1/followups/abc123def456" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "deal_found",
    "call_date": "2024-01-25T10:15:00Z",
    "duration_ms": 240000,
    "summary": "Successful contact, payment plan agreed",
    "notes": "Customer agreed to pay €500 monthly starting February 1st."
  }'

​
Response

Returns the updated followup object with the same structure as the Get Followup endpoint.

​
Success Response

{
  "error": false,
  "message": "Followup updated successfully",
  "data": {
    "id": "abc123def456",
    "debt_id": "xyz789ghi012",
    "status": "deal_found",
    "type": "call",
    "call_date": "2024-01-25T10:15:00+00:00",
    "scheduled_at": "2024-01-25T10:00:00+00:00",
    "summary": "Successful contact, payment plan agreed",
    "notes": "Customer agreed to pay €500 monthly starting February 1st.",
    "call_id": "call_789456",
    "audio_url": "https://s3.amazonaws.com/bucket/recordings/call_789456.mp3?X-Amz-Signature=...",
    "pdf_url": null,
    "duration_ms": 240000,
    "disconnection_reason": "completed_successfully",
    "direction": "outbound",
    "phone_number_used": "+33800123456",
    "is_retry": false,
    "processed_at": "2024-01-25T10:20:00+00:00",
    "media_urls_expire_at": "2024-01-25T11:20:00+00:00"
  }
}

​
Common Update Scenarios

​
Mark as Deal Found

{
  "status": "deal_found",
  "call_date": "2024-01-25T10:15:00Z",
  "summary": "Customer contacted successfully, agreement reached"
}

​
Mark as Delivered (for messages)

{
  "status": "delivered",
  "call_date": "2024-01-25T10:15:00Z",
  "summary": "Message delivered to recipient"
}

​
Record Failed Attempt

{
  "status": "no_answer",
  "call_date": "2024-01-25T10:15:00Z",
  "summary": "No answer after multiple attempts",
  "notes": "Phone rang but no answer. Will try again tomorrow."
}

​
Add Call Results

{
  "status": "deal_found",
  "duration_ms": 180000,
  "summary": "Payment discussion",
  "notes": "Customer acknowledged debt and requested payment plan options"
}

​
Cancel Followup

{
  "status": "cancelled",
  "notes": "Customer paid in full before followup was executed"
}

​
Validation Rules

  • status: Must be one of: on_hold, scheduled, in_progress, sent, delivered, deal_found, no_answer, deal_not_found, bad_behavior, failed, cancelled
  • type: Must be one of: call, sms, email, whatsapp, voicemail, manual_call, physical, postmail
  • call_date: Must be in ISO 8601 format
  • scheduled_at: Must be in ISO 8601 format

​
Error Responses

{
  "error": true,
  "message": "Invalid JSON payload",
  "code": 400
}