Workflow: Status Tracking

Learn how to track and monitor the status of your debt collection cases through the Debitura Customer API. This guide covers real-time status retrieval, historical tracking, and status change notifications.

Overview

Status tracking is essential for maintaining visibility into your collection cases. The Customer API provides multiple ways to monitor case progress, from simple status queries to comprehensive activity logs.

Case Status Lifecycle

Primary Status Values

Cases move through the following primary statuses:

1. Created - Case submitted and pending validation
2. Validated - All checks passed, ready for assignment
3. Assigned - Assigned to collection partner
4. In Collection - Active collection activities underway
5. Payment Plan - Debtor on agreed payment schedule
6. Resolved - Case completed successfully
7. Closed - Case terminated without full resolution
8. On Hold - Temporarily suspended

Sub-Statuses

Each primary status may have detailed sub-statuses:

• In Collection

  • First reminder sent
  • Second reminder sent
  • Legal proceedings initiated
  • Negotiation in progress

• Payment Plan

  • Plan active
  • Payment received
  • Payment missed
  • Plan defaulted

• Resolved

  • Paid in full
  • Partial payment accepted
  • Settlement reached

Querying Case Status

Get Single Case Status

Retrieve the current status of a specific case:

Endpoint: GET /api/cases/{caseId}

GET /api/cases/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer your-access-token

Response:

{
  "caseId": "550e8400-e29b-41d4-a716-446655440000",
  "caseNumber": "DEB-2024-12345",
  "status": "In Collection",
  "subStatus": "Second reminder sent",
  "lastStatusChange": "2024-01-15T14:30:00Z",
  "currentStage": "Pre-legal",
  "daysInCurrentStatus": 7,
  "assignedPartner": "Partner Name"
}

Get Multiple Case Statuses

Retrieve status for multiple cases efficiently:

Endpoint: GET /api/cases?status={status}&limit={limit}

GET /api/cases?status=In+Collection&limit=50
Authorization: Bearer your-access-token

Response:

{
  "cases": [
    {
      "caseId": "uuid-1",
      "caseNumber": "DEB-2024-12345",
      "status": "In Collection",
      "subStatus": "First reminder sent"
    },
    // ... more cases
  ],
  "totalCount": 150,
  "page": 1,
  "pageSize": 50
}

Filter by Status

Filter cases using various criteria:

• Status value
• Status change date range
• Partner assignment
• Division
• Amount ranges

Example query:

GET /api/cases?status=Resolved&dateFrom=2024-01-01&dateTo=2024-01-31

Status History

View Status Timeline

Get complete status history for a case:

Endpoint: GET /api/cases/{caseId}/history

GET /api/cases/550e8400-e29b-41d4-a716-446655440000/history
Authorization: Bearer your-access-token

Response:

{
  "caseId": "550e8400-e29b-41d4-a716-446655440000",
  "history": [
    {
      "timestamp": "2024-01-02T10:30:00Z",
      "status": "Created",
      "subStatus": null,
      "changedBy": "API",
      "note": "Case created via API"
    },
    {
      "timestamp": "2024-01-02T11:00:00Z",
      "status": "Assigned",
      "subStatus": null,
      "changedBy": "System",
      "note": "Assigned to Collection Partner A"
    },
    {
      "timestamp": "2024-01-08T09:15:00Z",
      "status": "In Collection",
      "subStatus": "First reminder sent",
      "changedBy": "Partner Agent",
      "note": "Initial reminder sent to debtor"
    }
  ]
}

Real-Time Updates

Polling Strategy

For systems that poll for updates:

Best practices:

• Poll at reasonable intervals (e.g., every 15-30 minutes)
• Use the lastModified field to detect changes
• Implement exponential backoff for rate limiting
• Cache responses to reduce API calls

Example with lastModified:

GET /api/cases?lastModifiedAfter=2024-01-15T10:00:00Z

Webhook Integration

For real-time notifications, use webhooks instead of polling:

{
  "event": "case.status.changed",
  "caseId": "550e8400-e29b-41d4-a716-446655440000",
  "caseNumber": "DEB-2024-12345",
  "oldStatus": "Assigned",
  "newStatus": "In Collection",
  "newSubStatus": "First reminder sent",
  "timestamp": "2024-01-08T09:15:00Z"
}

See Webhooks Workflow for detailed webhook configuration.

Status Analytics

Aggregated Status Metrics

Get overview statistics across your cases:

Endpoint: GET /api/cases/analytics/status-summary

{
  "totalCases": 500,
  "statusBreakdown": {
    "Created": 25,
    "Assigned": 50,
    "In Collection": 300,
    "Payment Plan": 75,
    "Resolved": 40,
    "Closed": 10
  },
  "averageResolutionTime": 45,
  "successRate": 0.80
}

Integration Patterns

Dashboard Integration

Build status dashboards that display:

• Current case counts by status
• Status transition trends
• Partner performance metrics
• Average time in each status
• Resolution rates

Automated Workflows

Trigger actions based on status changes:

• Update internal systems when case is resolved
• Alert account managers on status escalations
• Generate reports on status distributions
• Update customer records automatically

Reporting

Generate reports using status data:

• Weekly status change summaries
• Month-end case status reports
• Partner performance reports
• Collection effectiveness analytics

Best Practices

Efficient Status Tracking

1. Use webhooks instead of polling when possible
2. Cache status data locally for frequently accessed cases
3. Batch queries when checking multiple cases
4. Filter precisely to reduce response sizes
5. Track changes using lastModified timestamps

Error Handling

Handle common scenarios:

• Case not found (404)
• Rate limit exceeded (429)
• Authentication expired (401)
• Server errors (500)

Performance Optimization

• Implement local caching with TTL
• Use pagination for large result sets
• Request only required fields
• Leverage CDN for static status definitions

Code Examples

Node.js Status Polling

// Poll for status changes
async function pollForStatusChanges(lastCheckTime) {
  const response = await fetch(
    `https://api.debitura.com/api/cases?lastModifiedAfter=${lastCheckTime}`,
    {
      headers: { 'Authorization': `Bearer ${accessToken}` }
    }
  );

  const { cases } = await response.json();

  cases.forEach(caseItem => {
    console.log(`Case ${caseItem.caseNumber} is now ${caseItem.status}`);
  });

  return new Date().toISOString();
}

C# Status Tracking

// Get case status with history
public async Task<CaseDetails> GetCaseWithHistory(string caseId)
{
    var caseDetails = await _httpClient.GetFromJsonAsync<CaseDetails>(
        $"https://api.debitura.com/api/cases/{caseId}"
    );

    var history = await _httpClient.GetFromJsonAsync<StatusHistory>(
        $"https://api.debitura.com/api/cases/{caseId}/history"
    );

    caseDetails.History = history;
    return caseDetails;
}

Related Resources

• Webhooks Configuration
• Case Creation Workflow
• Integration Examples
• API Reference

---

For real-time status updates, we strongly recommend implementing webhook integration rather than polling.