Skip to main content

Entities and Relationships

Understanding the core data model and how different entities relate to each other in Debitura.

Core Entities​

Account​

Your Debitura account. Contains:

  • API credentials
  • Billing information
  • Settings and preferences
  • Bank account details
  • User access permissions

Relationships:

  • Has many Cases
  • Has many Bank Accounts
  • Has many Webhooks
  • Has many API Keys

Case​

A debt collection matter. The central entity in Debitura.

Key attributes:

  • Case ID (unique identifier)
  • Creditor information
  • Debtor information
  • Debt details (invoices, amounts, dates)
  • Current status
  • Assigned collection partner (if applicable)
  • Case history and timeline

Relationships:

  • Belongs to one Account
  • Has one Creditor
  • Has one Debtor
  • Has many Invoices
  • Has many Payments
  • Has many Events
  • May have one Collection Partner assignment
  • May have one Referral Partner

Creditor​

The party owed money (your business or your customer).

Key attributes:

  • Company/individual name
  • Registration number
  • Contact information
  • Bank account for payouts
  • Address

Relationships:

  • Belongs to one Account
  • Referenced by many Cases

Note: In multi-tenant scenarios (Referral Partners), one Account may have many Creditors.

Debtor​

The party who owes money.

Key attributes:

  • Company/individual name
  • Registration number (if company)
  • Contact information (email, phone)
  • Address
  • Country of residence

Relationships:

  • Referenced by one or more Cases
  • Has many Payments (across cases)
  • Has many Communications

Invoice​

An outstanding bill that is part of a case.

Key attributes:

  • Invoice number
  • Issue date
  • Due date
  • Original amount
  • Currency
  • Description
  • Invoice document (PDF)

Relationships:

  • Belongs to one Case
  • May have many Payments

Note: A Case can contain multiple invoices from the same creditor to the same debtor.

Payment​

Money received from the debtor.

Key attributes:

  • Amount
  • Currency
  • Payment date
  • Payment method
  • Reference number
  • Allocation (which invoices paid)

Relationships:

  • Belongs to one Case
  • May be allocated to one or more Invoices
  • Triggers one or more Payouts

Payout​

Money transferred from Debitura to the creditor.

Key attributes:

  • Amount
  • Currency
  • Payout date
  • Bank account
  • Related payments
  • Fees deducted

Relationships:

  • Belongs to one Account
  • Related to one or more Payments
  • Sent to one Bank Account

Supporting Entities​

Collection Partner​

An external agency or law firm assigned to work on cases.

Key attributes:

  • Partner name
  • Jurisdiction coverage
  • Specializations
  • Commission structure

Relationships:

  • Assigned to many Cases
  • Has many Events (case activities)

Referral Partner​

A SaaS platform or service provider that refers cases.

Key attributes:

  • Partner name
  • Revenue share percentage
  • White-label settings

Relationships:

  • Referred many Cases
  • Earns commission on related Payments

Event​

An activity or status change in a case.

Key attributes:

  • Event type
  • Timestamp
  • Description
  • Actor (who triggered it)
  • Related entities

Relationships:

  • Belongs to one Case
  • May trigger Webhooks

Event types:

  • Case created
  • Status changed
  • Payment received
  • Communication sent
  • Partner assigned
  • Document uploaded

Webhook​

A configured HTTP callback for events.

Key attributes:

  • Endpoint URL
  • Event types to notify
  • Active/inactive status
  • Secret for signature verification

Relationships:

  • Belongs to one Account
  • Triggered by many Events

Bank Account​

A bank account for receiving payouts.

Key attributes:

  • Account holder name
  • IBAN/account number
  • BIC/SWIFT code
  • Bank name
  • Currency

Relationships:

  • Belongs to one Account or Creditor
  • Receives many Payouts

Entity Relationship Diagram​

Account
  ├── Cases
  │     ├── Creditor
  │     ├── Debtor
  │     ├── Invoices
  │     ├── Payments
  │     ├── Events
  │     ├── Collection Partner (optional)
  │     └── Referral Partner (optional)
  ├── Bank Accounts
  │     └── Payouts
  ├── Webhooks
  └── API Keys

Data Flow Example​

Case Submission to Payment Flow​

  1. Account submits a Case via API
  2. Case contains Creditor and Debtor information
  3. Case includes one or more Invoices
  4. System creates Events for case creation
  5. Webhooks notify your system of case creation
  6. Collection Partner may be assigned
  7. Partner sends communications to Debtor
  8. Debtor makes a Payment
  9. Event created for payment received
  10. Webhook notifies your system
  11. Payout scheduled to Bank Account
  12. Event created for payout sent
  13. Webhook notifies your system

Object Hierarchies​

Case Object Structure​

Case
  ├── metadata (id, status, dates)
  ├── creditor (company info, contact)
  ├── debtor (company/person info, contact)
  ├── invoices[] (amount, date, documents)
  ├── payments[] (amount, date, allocation)
  ├── events[] (type, timestamp, description)
  ├── assignment (partner, date)
  └── financial_summary (amounts, fees, balance)

Payment Object Structure​

Payment
  ├── metadata (id, date, status)
  ├── amount (value, currency)
  ├── method (bank_transfer, card, etc.)
  ├── case_id (reference)
  ├── allocation[] (invoice splits)
  └── payout (related payout info)

Next Steps​