DebtRecoup

API Documentation ​

Overview ​

The DebtRecoup API provides programmatic access to core platform functionality, enabling integration with external systems and automation of collection workflows.

API Access ​

Authentication ​

All API requests require authentication using:

  • API key authentication
  • OAuth 2.0 tokens
  • JWT bearer tokens

Base URL ​

https://api.debtrecoup.com/v1/

Rate Limiting ​

  • 1000 requests per hour per API key
  • 100 concurrent connections
  • Bulk operations count as single requests

Available Endpoints ​

Accounts ​

  • GET /accounts - List accounts
  • GET /accounts/{id} - Get account details
  • PUT /accounts/{id} - Update account
  • POST /accounts/{id}/notes - Add note

Payments ​

  • POST /payments - Record payment
  • GET /payments/{id} - Get payment details
  • PUT /payments/{id} - Update payment
  • DELETE /payments/{id} - Reverse payment

Communications ​

  • POST /emails - Send email
  • GET /emails/{id} - Get email status
  • POST /letters - Generate letter
  • GET /communications - List communications

Reports ​

  • GET /reports/financial - Financial data
  • GET /reports/performance - Performance metrics
  • GET /reports/payments - Payment analytics
  • POST /reports/custom - Custom reports

Request Format ​

Headers ​

http
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json

Example Request ​

bash
curl -X GET \
  https://api.debtrecoup.com/v1/accounts/12345 \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json'

Response Format ​

Success Response ​

json
{
  "success": true,
  "data": {
    "id": "12345",
    "accountNumber": "ABC-123",
    "balance": 1500.00,
    "status": "active"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Response ​

json
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Account not found",
    "details": "No account exists with ID 12345"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Common Operations ​

Search Accounts ​

http
GET /accounts?search=smith&status=active&limit=50

Record Payment ​

http
POST /payments
{
  "accountId": "12345",
  "amount": 100.00,
  "method": "credit_card",
  "date": "2024-01-15"
}

Add Note ​

http
POST /accounts/12345/notes
{
  "content": "Spoke with debtor, payment arranged",
  "type": "collection_note"
}

Webhooks ​

Available Events ​

  • payment.created
  • payment.reversed
  • account.updated
  • communication.sent
  • status.changed

Webhook Format ​

json
{
  "event": "payment.created",
  "data": {
    "paymentId": "67890",
    "accountId": "12345",
    "amount": 100.00
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

SDKs and Libraries ​

Official SDKs ​

  • JavaScript/Node.js
  • Python
  • PHP
  • .NET
  • Java

Example Usage (JavaScript) ​

javascript
const DebtRecoup = require('@debtrecoup/sdk');

const client = new DebtRecoup({
  apiKey: 'YOUR_API_KEY'
});

const account = await client.accounts.get('12345');
const payment = await client.payments.create({
  accountId: '12345',
  amount: 100.00
});

Error Codes ​

HTTP Status Codes ​

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 429 - Rate Limited
  • 500 - Server Error

Application Error Codes ​

  • INVALID_REQUEST - Malformed request
  • AUTHENTICATION_FAILED - Invalid credentials
  • PERMISSION_DENIED - Insufficient permissions
  • RESOURCE_NOT_FOUND - Entity not found
  • VALIDATION_ERROR - Invalid data
  • RATE_LIMIT_EXCEEDED - Too many requests

Best Practices ​

Security ​

  • Store API keys securely
  • Use HTTPS for all requests
  • Implement request signing
  • Rotate keys regularly

Performance ​

  • Use pagination for large datasets
  • Implement caching where appropriate
  • Batch operations when possible
  • Handle rate limits gracefully

Error Handling ​

  • Implement retry logic
  • Log all errors
  • Handle timeout scenarios
  • Validate responses

API Changelog ​

Version 1.2.0 (Latest) ​

  • Added bulk payment processing
  • Enhanced search capabilities
  • New webhook events
  • Performance improvements

Version 1.1.0 ​

  • Added custom fields support
  • Improved error messages
  • New report endpoints
  • Bug fixes

Support ​

Getting Help ​

Testing ​

  • Sandbox environment available
  • Test API keys provided
  • Sample data for testing
  • Webhook testing tools

DebtRecoup is a product of Global SaaS Group.

All rights reserved.