Enums Reference - GetBill Integrations

Overview

This page provides a comprehensive reference of all enum values used across the GetBill API. These values are used for status fields, types, and other categorical data.

Always use the exact values listed here. String matching is case-sensitive.

Debt status: Uses full prefix format (e.g., status.default.paid)
Followup status: Uses simple values (e.g., delivered, deal_found)

Campaign snapshots

Campaign mode

Value	Meaning
`full_sync`	Complete synchronization settles omitted debts outside GetBill; required by the Campaigns API
`status_sync`	Incremental updates create or update only present rows and leave omissions unchanged; not accepted by the Campaigns API

The optional SFTP Statut column is independent of these values. It can be supplied with either behavior.

Campaign status

Value	Meaning
`active`	Ready to accept snapshots when a timeline is configured
`paused`	Collection and snapshot ingestion are paused
`completed`	Campaign is closed to new snapshots

Snapshot delivery mode

Value	Meaning
`one_request`	Complete snapshot submitted in one request, maximum 20,000 rows
`staged`	Ordered chunks, maximum 100,000 rows total and 20,000 per chunk

Snapshot status

Value	Meaning
`uploading`	Staged upload accepts the next chunk or cancellation
`pending`	Finalization is queued
`processing`	Worker is validating or applying the snapshot
`processing_error`	Core may be committed; operator recovery is required
`completed`	Core and required post-processing completed
`failed`	Snapshot stopped before core application

Timeline start mode

Value	Meaning
`immediate`	Start applicable timeline work immediately; default
`next_day`	Start applicable timeline work the next day

See Synchronize Campaign Snapshots for state transitions and retry rules.

Debt Status

Debt statuses are stored as database entities with translation keys. All status values follow the pattern status.default.*.

Debt status is a database entity, not a hardcoded enum. Additional custom statuses may exist for specific companies.

Available Status Values

Status Value	Translation Key	Description	Color
`status.default.pending`	status.default.pending	Initial state, awaiting processing	Blue
`status.default.in_progress`	status.default.in_progress	Active collection in progress	Blue
`status.default.processing`	status.default.processing	Currently being processed	Blue
`status.default.settled`	status.default.settled	Debt settled through payment plan	Green
`status.default.paid`	status.default.paid	Fully paid off	Green
`status.default.partial`	status.default.partial	Partially paid	Purple
`status.default.failed`	status.default.failed	Collection failed	Red
`status.default.archived`	status.default.archived	Archived/closed	Gray
`status.default.invalid_phone`	status.default.invalid_phone	Invalid contact information	Orange
`status.default.on_hold`	status.default.on_hold	On hold (typically due to dispute)	Orange
`status.default.manual_takeover`	status.default.manual_takeover	Collection taken over manually	Orange
`status.default.refused`	status.default.refused	Debtor refused to pay	Red

Usage Examples

curl -X PUT "/external-api/v1/debts/abc123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "status.default.on_hold",
    "summary": "Customer disputed the charge"
  }'

const updateData = {
  status: 'status.default.paid',
  summary: 'Payment received via bank transfer'
};

const response = await fetch(`/external-api/v1/debts/${debtId}`, {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(updateData)
});

import requests

data = {
    "status": "status.default.settled",
    "summary": "Payment plan agreed"
}

response = requests.put(
    f"/external-api/v1/debts/{debt_id}",
    headers={"Authorization": f"Bearer {token}"},
    json=data
)

Status Workflow

Common status transitions:

Followup Status

Followup statuses track the state of collection attempts (calls, emails, SMS, WhatsApp).

Important: The External API uses simple string values for followup status (e.g., delivered, deal_found), NOT the prefixed format used internally. Do not include the followup.status. prefix when using the API.

Available Status Values

API Value	Internal Key	Description	Color Code
`on_hold`	followup.status.on_hold	Waiting/queued state	#94A3B8 (Gray)
`scheduled`	followup.status.scheduled	Scheduled for future	#FFA500 (Orange)
`in_progress`	followup.status.in_progress	Currently in progress	#4B8BF9 (Blue)
`sent`	followup.status.sent	Message sent successfully	#3EDBCF (Teal)
`delivered`	followup.status.delivered	Message delivered	#10B981 (Green)
`deal_found`	followup.status.deal_found	Agreement reached	#3EDBCF (Teal)
`no_answer`	followup.status.no_answer	No response received	#F59E0B (Amber)
`deal_not_found`	followup.status.deal_not_found	No agreement reached	#6B7280 (Gray)
`bad_behavior`	followup.status.bad_behavior	Negative behavior detected	#EF4444 (Red)
`failed`	followup.status.failed	Attempt failed	#DC2626 (Dark Red)
`cancelled`	followup.status.cancelled	Cancelled by user	#6B7280 (Gray)

Usage Examples

curl -X POST "/external-api/v1/followups" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "debt_id": "abc123",
    "type": "call",
    "status": "scheduled",
    "scheduled_at": "2024-03-15T10:00:00Z"
  }'

const followupData = {
  debt_id: 'abc123',
  type: 'email',
  status: 'sent',
  summary: 'Payment reminder sent'
};

const response = await fetch('/external-api/v1/followups', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(followupData)
});

import requests

followup = {
    "debt_id": "abc123",
    "type": "sms",
    "status": "delivered",
    "summary": "SMS delivered successfully"
}

response = requests.post(
    "/external-api/v1/followups",
    headers={"Authorization": f"Bearer {token}"},
    json=followup
)

Status Workflow

Typical followup status progression:

Dispute Status

Dispute statuses track the review state of customer disputes detected by AI or reported manually.

Available Status Values

Status Value	Display Name	Description	Color Code	Badge Class
`suggested`	Pending Review	AI detected potential dispute, awaiting review	#f59e0b (Amber)	`status-badge--warning`
`validated`	Validated	Dispute confirmed as legitimate	#10b981 (Green)	`status-badge--success`
`rejected`	Rejected	Dispute rejected after review	#ef4444 (Red)	`status-badge--danger`

Usage Examples

# Update dispute status
curl -X PUT "/external-api/v1/todos/blocking_dispute/234/status" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "validated",
    "admin_notes": "Verified customer claim, payment was received"
  }'

const updateDispute = {
  status: 'rejected',
  admin_notes: 'Investigation showed no payment was made'
};

const response = await fetch('/external-api/v1/todos/blocking_dispute/234/status', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(updateDispute)
});

import requests

update = {
    "status": "validated",
    "admin_notes": "Customer provided proof of payment"
}

response = requests.put(
    f"/external-api/v1/todos/blocking_dispute/{dispute_id}/status",
    headers={"Authorization": f"Bearer {token}"},
    json=update
)

Dispute Workflow

When a blocking dispute is validated, the associated debt typically remains status.default.on_hold and collection is paused. When rejected, the debt may return to status.default.in_progress to resume collection.

Payment Status

Payment statuses track the state of payment transactions. Used internally for payment processing.

Payment status is primarily used for internal payment tracking and may not be directly exposed in all API endpoints.

Available Status Values

Status Value	Display Name	Description
`pending`	Pending	Payment initiated, awaiting processing
`processing`	Processing	Payment being processed
`succeeded`	Succeeded	Payment completed successfully
`failed`	Failed	Payment failed
`canceled`	Canceled	Payment cancelled
`refunded`	Refunded	Payment fully refunded
`partially_refunded`	Partially Refunded	Payment partially refunded
`requires_action`	Requires Action	Customer action needed (e.g., 3DS)
`requires_confirmation`	Requires Confirmation	Payment confirmation required
`requires_payment_method`	Requires Payment Method	Payment method required

Followup Type

Types of collection attempts available in the system.

Available Type Values

Type Value	Description
`call`	AI-powered voice call
`manual_call`	Manual voice call by agent
`email`	Email communication
`sms`	SMS text message
`whatsapp`	WhatsApp message
`voicemail`	Voicemail message
`physical`	Physical/in-person contact
`postmail`	Physical mail/letter

Usage Example

const followup = {
  debt_id: 'abc123',
  type: 'email',  // Must be one of: call, manual_call, email, sms, whatsapp, voicemail, physical, postmail
  status: 'scheduled',
  scheduled_at: '2024-03-15T10:00:00Z'
};

Todo Type

Types of todo items that require attention.

Available Type Values

Type Value	Description	Urgency
`agreement`	Payment plan/installment agreement	Normal
`blocking_dispute`	Urgent dispute - collection paused	High
`non_blocking_dispute`	Regular dispute - collection continues	Medium

Usage Example

# Filter todos by type
curl -X GET "/external-api/v1/todos?type=blocking_dispute&period=since_last_week" \
  -H "Authorization: Bearer YOUR_TOKEN"

Common Patterns

Filtering by Status

Most list endpoints support filtering by status:

# Filter debts by status (uses full prefix)
GET /external-api/v1/debts?status=status.default.paid

# Filter followups by status (uses simple value)
GET /external-api/v1/followups?status=delivered

Updating Status

Debt status uses the full status.default.* prefix, while followup status uses simple values.

For Debts:

{
  "status": "status.default.paid"
}

For Followups:

{
  "status": "delivered"
}

Status Validation

The API will return a 400 Bad Request error if an invalid status value is provided:

{
  "error": true,
  "message": "Invalid status value",
  "code": 400
}

Need Help?

If you encounter status values not listed here or have questions about when to use specific statuses, please refer to:

​Overview

​Campaign snapshots

​Campaign mode

​Campaign status

​Snapshot delivery mode

​Snapshot status

​Timeline start mode

​Debt Status

​Available Status Values

​Usage Examples

​Status Workflow

​Followup Status

​Available Status Values

​Usage Examples

​Status Workflow

​Dispute Status

​Available Status Values

​Usage Examples

​Dispute Workflow

​Payment Status

​Available Status Values

​Followup Type

​Available Type Values

​Usage Example

​Todo Type

​Available Type Values

​Usage Example

​Common Patterns

​Filtering by Status

​Updating Status

​Status Validation

​Need Help?

Overview

Campaign snapshots

Campaign mode

Campaign status

Snapshot delivery mode

Snapshot status

Timeline start mode

Debt Status

Available Status Values

Usage Examples

Status Workflow

Followup Status

Available Status Values

Usage Examples

Status Workflow

Dispute Status

Available Status Values

Usage Examples

Dispute Workflow

Payment Status

Available Status Values

Followup Type

Available Type Values

Usage Example

Todo Type

Available Type Values

Usage Example

Common Patterns

Filtering by Status

Updating Status

Status Validation

Need Help?