English

Svenska

English

Svenska

Appearance

Case Flow Example ​

The diagram below shows the basic sequence of API calls for managing a case, with each step described in the following sections.

A case is registered with all customer and debt details required to start the debt collection process. As recommended, the original invoice document is uploaded in connection to this. After this point we can at any time get the current status of the case, including detailed case information, state changes and history. The flow then describes how to register a creditor payment if the customer pays directly to the creditor, and finally shows the updated case status after payment closure.


Step-by-Step Guide ​

All API requests require a valid authentication token in the X-API-Key header. For details about the authentication process and token management, see the Authentication documentation.

In this guide, we will use the AuthTokenProvider class (documented in the authentication guide) to handle token management.

1. Register a Case ​

Register a new case with debt collection as the first action using the Case Registration endpoint:

typescript
const caseData = {
  account: '674dbeaf08847b9501cc9132',
  creditor: '674dbeb208847b9501cc9138',
  first_action: 'debt_collection',
  currency: 'SEK',
  customer: {
    name: 'ACME Inc.',
    id_number: '5560269986',
    is_company: true,
    address: {
      address_line_1: 'Storgatan 42',
      zip_code: '12345',
      city: 'Stockholm',
      country: 'SE',
    },
  },
  debts: [
    {
      invoice_number: 'INV-2025-003',
      debt_description: 'Services',
      invoice_date: 'Mon, 07 Jul 2025 00:00:00 GMT',
      capital_to_claim: 2000.0,
      invoice_due_days_after_invoice_date: 31,
    },
  ],
}

const token = await auth.getValidToken()
const response = await axios.post(
  'https://api-sandbox.amili.se/case--registrations',
  caseData,
  {
    headers: {
      'X-API-Key': token,
      'Content-Type': 'application/json',
    },
  }
)
python
case_data = {
    "account": "674dbeaf08847b9501cc9132",
    "creditor": "674dbeb208847b9501cc9138",
    "first_action": "debt_collection",
    "currency": "SEK",
    "customer": {
        "name": "ACME Inc.",
        "id_number": "5560269986",
        "is_company": True,
        "address": {
            "address_line_1": "Storgatan 42",
            "zip_code": "12345",
            "city": "Stockholm",
            "country": "SE"
        }
    },
    "debts": [{
        "invoice_number": "INV-2025-003",
        "debt_description": "Services",
        "invoice_date": "Mon, 07 Jul 2025 00:00:00 GMT",
        "capital_to_claim": 2000.0,
        "invoice_due_days_after_invoice_date": 31
    }]
}

token = auth.get_valid_token()
response = requests.post(
    'https://api-sandbox.amili.se/case--registrations',
    json=case_data,
    headers={
        'X-API-Key': token,
        'Content-Type': 'application/json'
    }
)
response.raise_for_status()
result = response.json()

The response will be:

json
{
  "_updated": "Wed, 03 Sep 2025 07:56:11 GMT",
  "_created": "Wed, 03 Sep 2025 07:56:11 GMT",
  "_etag": "74829ce9b219a58bb00a5276a495bec0d7e22457",
  "_id": "68b7f49cb8903ae30ebb85ec",
  "_status": "OK",
  "_cases": ["68b7f49c7b02934caddab092"],
  "_ocr_numbers": ["68b7f49cb8903ae30ebb85f0"],
  "_ocr_numbers_ocr": ["20252463478311301072"]
}

2. Upload Original Invoice ​

Upload the original invoice document to the case using the Media Upload endpoint:

typescript
const token = await auth.getValidToken()
const caseId = '68b7f49c7b02934caddab092'

const formData = new FormData()
formData.append('file', fileBlob, 'original_invoice.pdf')
formData.append('domain', 'cases')
formData.append('dotted_path', 'original_invoice')

const response = await axios.post(
  `https://api-sandbox.amili.se/media--upload/${caseId}`,
  formData,
  {
    headers: {
      'X-API-Key': token,
      'Content-Type': 'multipart/form-data',
    },
  }
)
python
token = auth.get_valid_token()
case_id = '68b7f49c7b02934caddab092'

files = {
    'file': ('original_invoice.pdf', open('original_invoice.pdf', 'rb'), 'application/pdf')
}
data = {
    'domain': 'cases',
    'dotted_path': 'original_invoice'
}

response = requests.post(
    f'https://api-sandbox.amili.se/media--upload/{case_id}',
    files=files,
    data=data,
    headers={'X-API-Key': token}
)
response.raise_for_status()
result = response.json()

The response will be:

json
{
  "url": "https://storage.googleapis.com/stage-ada-vcom-api-files/stage/cases/68b7f49c7b02934caddab092-95cd1aa42c0f491499d3bc5bc70dbf50?Expires=1756889787&GoogleAccessId=stage-ada-vcom-pod-svc%40stage-ada-vcom.iam.gserviceaccount.com&Signature=YHeCsV%2BeABeaQhUCfITyn9OoourBmjdElC4wplX3j8V5wnEhVEOesMlb%2FbullXadFejJofTPAMPQ7sxRirqatdYgWGXLAxNQQ31HG2h%2BN%2FrRRGjUj65eos924Lu226zareS%2BtzUDX1%2B%2BFapXoQrqCn18PKdlg%2BnRXn%2B0PEhS1vsrEQ3brUby9FzdNchZsCR4HJ96iVQvUpUP%2BZl2bedT8K6Bpzi875u4GDcN8VpIrBbkmJVYsjzyPy8KfpH%2BGy1qDGLme6H2Pw6%2Bn84sJWRsomsnsXCLP2MRlitQ1EzuNzdcoFRBsoesDedEZDUOYfju4QUOzFB9wI%2BR%2Fo8taVAkjg%3D%3D"
}

3. Check Case Status ​

Get the current status of the case using the Case endpoint:

typescript
const token = await auth.getValidToken()
const caseId = '68b7f49c7b02934caddab092'

const response = await axios.get(
  `https://api-sandbox.amili.se/cases/${caseId}`,
  {
    headers: {
      'X-API-Key': token,
    },
  }
)
python
token = auth.get_valid_token()
case_id = '68b7f49c7b02934caddab092'

response = requests.get(
    f'https://api-sandbox.amili.se/cases/{case_id}',
    headers={'X-API-Key': token}
)
response.raise_for_status()
result = response.json()

The response will be:

json
{
  "_id": "68b7f49c7b02934caddab092",
  "debt": {
    "invoice_date": "Mon, 07 Jul 2025 00:00:00 GMT",
    "invoice_due_days_after_invoice_date": 31,
    "capital_to_claim": 2000,
    "debt_description": "Services",
    "invoice_number": "INV-2025-003",
    "payout_reference": "INV-2025-003",
    "interest_days_after_invoice_date": 31
  },
  "creditor": "674dbeb208847b9501cc9138",
  "_created": "Wed, 03 Sep 2025 07:56:12 GMT",
  "_etag": "2feb48de91244e42a56f0c7083fd3499",
  "_updated": "Wed, 03 Sep 2025 09:10:17 GMT",
  "account": "674dbeaf08847b9501cc9132",
  "agreement_version": "6790c2ec38ebf4814061f0b5",
  "case_registration": "68b7f49cb8903ae30ebb85ec",
  "case_settings": {
    "interest_rate": {
      "reference_rate": true
    }
  },
  "creditor_name": "Amili Integration Team",
  "currency": "SEK",
  "customer": "67ea693a65e2ae992e484c4e",
  "customer_id_number": "5560269986",
  "customer_name": "ACME Inc.",
  "customer_status": "initialized",
  "debtor": "6645d2ebe749de8a2ee09f6f",
  "debtor_id_number": "5560269986",
  "debtor_name": "ACME Inc.",
  "latest_state_date": "Wed, 03 Sep 2025 09:00:23 GMT",
  "local_added_capital_amount": 2000,
  "local_added_costs_amount": 0,
  "local_added_interest_amount": 14.0,
  "local_added_transaction_amount": 2014.0,
  "local_remaining_capital_amount": 2000,
  "local_remaining_costs_amount": 0,
  "local_remaining_interest_amount": 14.0,
  "local_remaining_transaction_amount": 2014.0,
  "state": "debt_collection",
  "state_history": [
    {
      "state": "initializing",
      "state_date": "Wed, 03 Sep 2025 07:56:12 GMT"
    },
    {
      "state": "debt_collection",
      "state_date": "Wed, 03 Sep 2025 09:00:23 GMT"
    }
  ],
  "status": "debt_collection",
  "status_history": [
    {
      "status": "initializing",
      "status_date": "Wed, 03 Sep 2025 07:56:12 GMT"
    },
    {
      "status": "initialized",
      "status_date": "Wed, 03 Sep 2025 08:00:17 GMT"
    },
    {
      "status": "debt_collection",
      "status_date": "Wed, 03 Sep 2025 09:00:23 GMT"
    }
  ],
  "total_added_capital_amount": 2000,
  "total_added_costs_amount": 0,
  "total_added_interest_amount": 14.0,
  "total_added_transaction_amount": 2014.0,
  "total_remaining_capital_amount": 2000,
  "total_remaining_costs_amount": 0,
  "total_remaining_interest_amount": 14.0,
  "total_remaining_transaction_amount": 2014.0,
  "transactions": [
    {
      "bank_transaction_date": "Mon, 07 Jul 2025 00:00:00 GMT",
      "registration_date": "Wed, 03 Sep 2025 06:02:09 GMT",
      "origin": "creditor_system",
      "type": "capital",
      "description_locale_tag": "api.transaction.case_registration",
      "amount": 2000
    },
    {
      "bank_transaction_date": "Wed, 03 Sep 2025 08:00:17 GMT",
      "registration_date": "Wed, 03 Sep 2025 08:00:17 GMT",
      "origin": "solicitor_system",
      "type": "interest",
      "description_locale_tag": "api.transaction.case_flow",
      "amount": 14.0
    }
  ],
  "reference_number": "48640",
  "original_invoice": {
    "id": "95cd1aa42c0f491499d3bc5bc70dbf50",
    "filename": "original_invoice.pdf",
    "content_type": "application/pdf",
    "size": 12937
  },
  "next_flow_item": {
    "item": "case--debt-collections__debt_statement",
    "schedule_to_execute": "Fri, 19 Sep 2025 00:00:00 GMT",
    "flow_config": "665e138e8dd7c7b8996f2a7e",
    "is_failed": false,
    "waiting_for": "api.wait.waiting_for_debt_collection_payment",
    "moved_to_next_state": true,
    "flow_config_name_locale": "api.flow_config.default"
  },
  "debt_collection": "68b803a6131658107a9919fa",
  "services": [
    {
      "service": "debt_collection",
      "service_date": "Wed, 03 Sep 2025 09:00:23 GMT"
    }
  ],
  "limitation": {
    "break_date": "Wed, 03 Sep 2025 09:10:17 GMT",
    "limitation_date": "Mon, 03 Sep 2035 09:10:17 GMT",
    "locale_annotation": "api.log_messages.letter_sent_debt_collection"
  },
  "event_listeners": {}
}

4. Register Creditor Payment ​

When the customer makes a payment directly to the creditor, register the payment using the Creditor Payment endpoint:

typescript
const paymentData = {
  account: '674dbeaf08847b9501cc9132',
  creditor: '674dbeb208847b9501cc9138',
  case: '68b7f49c7b02934caddab092',
  currency: 'SEK',
  amount: 2000.0,
  bank_transaction_date: 'Wed, 03 Sep 2025 08:00:00 GMT',
  creditor_payment_reference: 'PAY-REF-001',
  origin: 'creditor_system',
}

const token = await auth.getValidToken()
const response = await axios.post(
  'https://api-sandbox.amili.se/creditor--payments',
  paymentData,
  {
    headers: {
      'X-API-Key': token,
      'Content-Type': 'application/json',
    },
  }
)
python
payment_data = {
    "account": "674dbeaf08847b9501cc9132",
    "creditor": "674dbeb208847b9501cc9138",
    "case": "68b7f49c7b02934caddab092",
    "currency": "SEK",
    "amount": 2000.0,
    "bank_transaction_date": "Wed, 03 Sep 2025 08:00:00 GMT",
    "creditor_payment_reference": "PAY-REF-001",
    "origin": "creditor_system"
}

token = auth.get_valid_token()
response = requests.post(
    'https://api-sandbox.amili.se/creditor--payments',
    json=payment_data,
    headers={
        'X-API-Key': token,
        'Content-Type': 'application/json'
    }
)
response.raise_for_status()
result = response.json()

The response will be:

json
{
  "_updated": "Wed, 03 Sep 2025 11:18:58 GMT",
  "_created": "Wed, 03 Sep 2025 11:18:58 GMT",
  "_etag": "4a44ca23f947e3e0ec3b24352f0f49bbb072d6ae",
  "_id": "68b82422d6fd1d378f18d2e9",
  "_status": "OK",
  "_payment_status": "completed"
}

5. Final Case Status ​

Check the case status after payment to see the updated state using the Case endpoint:

typescript
const token = await auth.getValidToken()
const caseId = '68b7f49c7b02934caddab092'

const response = await axios.get(
  `https://api-sandbox.amili.se/cases/${caseId}`,
  {
    headers: {
      'X-API-Key': token,
    },
  }
)
python
token = auth.get_valid_token()
case_id = '68b7f49c7b02934caddab092'

response = requests.get(
    f'https://api-sandbox.amili.se/cases/{case_id}',
    headers={'X-API-Key': token}
)
response.raise_for_status()
result = response.json()

The response will show the case is now closed:

json
{
  "_id": "68b7f49c7b02934caddab092",
  "debt": {
    "invoice_date": "Mon, 07 Jul 2025 00:00:00 GMT",
    "invoice_due_days_after_invoice_date": 31,
    "capital_to_claim": 2000,
    "debt_description": "Services",
    "invoice_number": "INV-2025-003",
    "payout_reference": "INV-2025-003",
    "interest_days_after_invoice_date": 31
  },
  "creditor": "674dbeb208847b9501cc9138",
  "_created": "Wed, 03 Sep 2025 07:56:12 GMT",
  "_etag": "8c58d51b39ae4909902d5b706d420ad9",
  "_updated": "Wed, 03 Sep 2025 11:18:59 GMT",
  "account": "674dbeaf08847b9501cc9132",
  "agreement_version": "6790c2ec38ebf4814061f0b5",
  "case_registration": "68b7f49cb8903ae30ebb85ec",
  "case_settings": {
    "interest_rate": {
      "reference_rate": true
    }
  },
  "creditor_name": "Amili Integration Team",
  "currency": "SEK",
  "customer": "67ea693a65e2ae992e484c4e",
  "customer_id_number": "5560269986",
  "customer_name": "ACME Inc.",
  "customer_status": "initialized",
  "debtor": "6645d2ebe749de8a2ee09f6f",
  "debtor_id_number": "5560269986",
  "debtor_name": "ACME Inc.",
  "latest_state_date": "Wed, 03 Sep 2025 09:00:23 GMT",
  "local_added_capital_amount": 2000,
  "local_added_costs_amount": 0,
  "local_added_interest_amount": 14.0,
  "local_added_transaction_amount": 2014.0,
  "local_remaining_capital_amount": 0,
  "local_remaining_costs_amount": 0,
  "local_remaining_interest_amount": 0.0,
  "local_remaining_transaction_amount": 0.0,
  "state": "debt_collection",
  "state_history": [
    {
      "state": "initializing",
      "state_date": "Wed, 03 Sep 2025 07:56:12 GMT"
    },
    {
      "state": "debt_collection",
      "state_date": "Wed, 03 Sep 2025 09:00:23 GMT"
    }
  ],
  "status": "closed",
  "status_history": [
    {
      "status": "initializing",
      "status_date": "Wed, 03 Sep 2025 07:56:12 GMT"
    },
    {
      "status": "initialized",
      "status_date": "Wed, 03 Sep 2025 08:00:17 GMT"
    },
    {
      "status": "debt_collection",
      "status_date": "Wed, 03 Sep 2025 09:00:23 GMT"
    },
    {
      "status": "closed",
      "status_date": "Wed, 03 Sep 2025 11:18:59 GMT"
    }
  ],
  "total_added_capital_amount": 2000,
  "total_added_costs_amount": 0,
  "total_added_interest_amount": 14.0,
  "total_added_transaction_amount": 2014.0,
  "total_remaining_capital_amount": 0,
  "total_remaining_costs_amount": 0,
  "total_remaining_interest_amount": 0.0,
  "total_remaining_transaction_amount": 0.0,
  "transactions": [
    {
      "bank_transaction_date": "Mon, 07 Jul 2025 00:00:00 GMT",
      "registration_date": "Wed, 03 Sep 2025 06:02:09 GMT",
      "origin": "creditor_system",
      "type": "capital",
      "description_locale_tag": "api.transaction.case_registration",
      "amount": 2000
    },
    {
      "bank_transaction_date": "Wed, 03 Sep 2025 08:00:17 GMT",
      "registration_date": "Wed, 03 Sep 2025 08:00:17 GMT",
      "origin": "solicitor_system",
      "type": "interest",
      "description_locale_tag": "api.transaction.case_flow",
      "amount": 14.0
    },
    {
      "bank_transaction_date": "Wed, 03 Sep 2025 08:00:00 GMT",
      "registration_date": "Wed, 03 Sep 2025 11:18:58 GMT",
      "origin": "creditor_system",
      "type": "capital",
      "description_locale_tag": "creditor_payment.payment_settled",
      "amount": -2000,
      "payment_method": "creditor_payment",
      "creditor_payment": "68b82422d6fd1d378f18d2e9"
    },
    {
      "bank_transaction_date": "Wed, 03 Sep 2025 11:18:59 GMT",
      "registration_date": "Wed, 03 Sep 2025 11:18:59 GMT",
      "origin": "solicitor_system",
      "type": "interest",
      "description_locale_tag": "api.transaction.depreciated",
      "amount": -14.0
    }
  ],
  "reference_number": "48640",
  "original_invoice": {
    "id": "95cd1aa42c0f491499d3bc5bc70dbf50",
    "filename": "original_invoice.pdf",
    "content_type": "application/pdf",
    "size": 12937
  },
  "debt_collection": "68b803a6131658107a9919fa",
  "services": [
    {
      "service": "debt_collection",
      "service_date": "Wed, 03 Sep 2025 09:00:23 GMT"
    }
  ],
  "limitation": {
    "break_date": "Wed, 03 Sep 2025 09:10:17 GMT",
    "limitation_date": "Mon, 03 Sep 2035 09:10:17 GMT",
    "locale_annotation": "api.log_messages.letter_sent_debt_collection"
  },
  "closed": {
    "close_date": "Wed, 03 Sep 2025 11:18:59 GMT",
    "reason": "fully_paid_depreciation"
  },
  "next_flow_item_on_close": {
    "item": "case--debt-collections__debt_statement",
    "schedule_to_execute": "Fri, 19 Sep 2025 00:00:00 GMT",
    "flow_config": "665e138e8dd7c7b8996f2a7e",
    "is_failed": false,
    "waiting_for": "api.wait.waiting_for_debt_collection_payment",
    "moved_to_next_state": true,
    "flow_config_name_locale": "api.flow_config.default"
  }
}