English

Svenska

English

Svenska

Appearance

Case Flow Examples ​

This guide covers the key API actions for registering a case and uploading supporting documents. A case registration is used when the creditor has already invoiced the customer and wants Amili to handle the next step — either sending a reminder or initiating debt collection.

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.

Case Registration ​

Register a new case using the Case Registration endpoint. The response returns a registration ID and, more importantly, one or more case IDs (_cases). The case ID is used for all subsequent actions on this case.

The first_action field determines where the case enters the flow. The most common values are:

  • reminder — Amili sends a reminder to the customer before escalating to debt collection.
  • debt_collection — The case goes directly to debt collection.

A case registration includes the customer information and one or more debts. Each debt becomes a separate case. After registering the case, the original invoice should be uploaded to enable an efficient collection process.

The example below uses debt_collection as the first action and demonstrates how to include fees that have already been invoiced or charged to the customer.

Step 1: Register the Case ​

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()

About fees in the example

  • fees_included_in_capital_to_claim — Fees (e.g. invoice fee) that are already included in the capital_to_claim amount. The values inform Amili how much of the capital is fees vs. the original debt.
  • fees_already_claimed — Fees (e.g. reminder fee) that the creditor has already charged separately. These are not included in capital_to_claim but are registered so Amili can account for them in the collection process.

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"]
}

Key IDs in the response

  • _id — The case registration ID (the record of this request)
  • _cases — Array of case IDs — use these for all subsequent actions (crediting, cancellation, payment). One case is created per debt in the request.
  • _ocr_numbers — Array of OCR number resource IDs (one per case)
  • _ocr_numbers_ocr — Array of OCR number strings for payment reference

Step 2: Upload the Original Invoice ​

Using the case ID from the registration response, upload the original invoice document via 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"
}

Next Steps ​

Once a case has been created from a case registration, you can perform actions such as registering payments, crediting amounts, cancelling the case, or requesting a respite. These actions are common to all cases regardless of how they were created.

See the Creditor Case Actions guide for detailed examples of:

  • Creditor Payment — Register a payment received directly from the debtor
  • Creditor Crediting — Credit part of the capital on a case
  • Creditor Cancellation — Cancel a case entirely
  • Case Respite — Postpone a case by a number of days

You can also track the lifecycle and financial outcome of your cases: