Skip to main content

Quickstart: Link Client and Create Case

Get started with the Referral Partner API in minutes. This guide walks you through linking your first client and creating a test case.

Prerequisites​

Before you begin, ensure you have:

  • API Credentials - Contact your account manager for sandbox API keys
  • Development Environment - Access to make HTTP requests (cURL, Postman, or your preferred tool)
  • Test Data - Sample customer information for testing

Step 1: Authenticate​

All API requests require authentication using your API key in the Authorization header.

curl https://api.sandbox.debitura.com/v1/referral-partners/ping \
  -H "Authorization: Bearer deb_test_your_key_here"

Expected response:

{
  "status": "ok",
  "partner_id": "ref_partner_123",
  "environment": "sandbox"
}

Link one of your customers to Debitura. This creates the connection that allows you to create cases on their behalf.

curl https://api.sandbox.debitura.com/v1/referral-partners/clients \
  -H "Authorization: Bearer deb_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "cust_12345",
    "company_name": "Acme Corporation",
    "country": "DK",
    "email": "contact@acme.com",
    "onboarding_type": "api_only"
  }'

Request Parameters:

FieldTypeDescription
external_idstringYour internal customer ID (for reference)
company_namestringCustomer's company name
countrystringISO 3166-1 alpha-2 country code
emailstringPrimary contact email
onboarding_typestringapi_only or white_label

Response:

{
  "client_id": "cli_abc123def456",
  "external_id": "cust_12345",
  "status": "active",
  "bearer_token": "tok_xyz789abc012",
  "created_at": "2024-01-15T10:30:00Z"
}

Save the bearer_token - you'll need it to create cases on behalf of this client.

Step 3: Create a Case​

Now create a debt collection case on behalf of your linked client using their bearer token.

curl https://api.sandbox.debitura.com/v1/cases \
  -H "Authorization: Bearer tok_xyz789abc012" \
  -H "Content-Type: application/json" \
  -d '{
    "debtor": {
      "name": "John Doe",
      "email": "john@example.com",
      "country": "DK"
    },
    "amount": {
      "value": 5000,
      "currency": "DKK"
    },
    "invoice_number": "INV-001",
    "due_date": "2024-01-01"
  }'

Response:

{
  "case_id": "case_789xyz123abc",
  "status": "pending_verification",
  "debtor_name": "John Doe",
  "amount": {
    "value": 5000,
    "currency": "DKK"
  },
  "created_at": "2024-01-15T10:35:00Z"
}

What Happens Next?​

  1. Case Verification - Debitura verifies the case details (typically within 24 hours)
  2. Collection Process - Once verified, collection activities begin
  3. Revenue Attribution - The case is automatically attributed to your partnership
  4. Webhooks - You'll receive updates via webhooks (if configured)

Testing Your Integration​

Use these test scenarios to verify your integration:

Scenario 1: Successful Case Creation​

  • Use valid debtor information
  • Expect status: "pending_verification"

Scenario 2: Duplicate Detection​

  • Create the same case twice
  • Expect 409 Conflict with existing case details

Scenario 3: Validation Error​

  • Omit required fields
  • Expect 400 Bad Request with validation details

Common Issues​

401 Unauthorized

  • Verify your API key is correct
  • Check you're using the right environment (sandbox vs production)

403 Forbidden

  • Ensure client linking was successful
  • Verify bearer token is not expired

409 Conflict

Next Steps​

Now that you've created your first case, explore: