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. In this example, the case includes an invoice fee (50 SEK) that is included in the capital amount and a reminder fee (60 SEK) that has already been charged to the customer. As recommended, the original invoice document is uploaded in connection to this. The flow then describes how to register a creditor payment if the customer pays directly to the creditor.


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: 2050.0, // 2000 + 50 invoice fee
      invoice_due_days_after_invoice_date: 31,
      fees_included_in_capital_to_claim: {
        invoice_fee: 50.0,
      },
      fees_already_claimed: {
        reminder: {
          amount: 60.0,
          fee_registration_date: 'Mon, 11 Aug 2025 00:00:00 GMT',
        },
      },
    },
  ],
}

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": 2050.0,  # 2000 + 50 invoice fee
        "invoice_due_days_after_invoice_date": 31,
        "fees_included_in_capital_to_claim": {
            "invoice_fee": 50.0
        },
        "fees_already_claimed": {
            "reminder": {
                "amount": 60.0,
                "fee_registration_date": "Mon, 11 Aug 2025 00:00:00 GMT"
            }
        }
    }]
}

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. 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: 2110.0,
  bank_transaction_date: 'Thu, 04 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": 2110.0,
    "bank_transaction_date": "Thu, 04 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"
}

Check Payout Specifications ​

After payment settlement, we recommended to track case payouts through the finance payout specifications. This endpoint provides a detailed breakdown of amounts that will be paid out to the creditor, including references to the related cases.

For detailed examples of how to query payout specifications, see the Finance Payout Specification Example.

For complete endpoint documentation, see the Finance Payout Specification endpoint.

Note on Case Status

You can also retrieve individual case status or list cases using the GET /cases endpoint if needed.