Creditor & User Management

Some integrations need to programmatically create creditors and manage users through the API. This is relevant for partner platforms that onboard multiple creditors, or organizations that need automated provisioning of creditor accounts and users.

When a creditor is created, Amili automatically generates access groups for that creditor. These access groups are then used to assign roles when creating users.

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.

Table of Contents

Create a Creditor — Onboard a new creditor with activation details
Retrieve Access Groups — Find available roles for user assignment
Create Users — Provision admin and regular users

Create a Creditor

To onboard a new creditor, use the Creditor endpoint. A creditor must be activated before any cases can be registered against it.

Activation Requirements

The following fields are required to activate a creditor: payout_details, sender_address, invoice_address, and standard_debt_description. You can create a creditor with is_active: true if all required fields are provided, or create it first and activate it later.

TypeScriptPython

typescript

const creditorData = {
  account: '6662fb1df4d1eaf404cb08de',
  name: 'Acme Inc',
  organization_no: '1122334455',
  is_active: true,
  standard_debt_description: 'Standard skuldbeskrivning på Konto',
  description: 'Testing',
  sender_address: {
    address_line_1: 'Redaregatan 50',
    zip_code: '25236',
    city: 'Helsingborg',
    country: 'SE',
  },
  invoice_address: {
    address_line_1: 'Redaregatan 50',
    zip_code: '25236',
    city: 'Helsingborg',
    country: 'SE',
  },
  payout_details: {
    sek: {
      bankgiro: '12312312',
    },
  },
}

const token = await auth.getValidToken()
const response = await axios.post(
  'https://api-sandbox.amili.se/creditors',
  creditorData,
  {
    headers: {
      'X-API-Key': token,
      'Content-Type': 'application/json',
    },
  }
)

python

creditor_data = {
    "account": "6662fb1df4d1eaf404cb08de",
    "name": "Acme Inc",
    "organization_no": "1122334455",
    "is_active": True,
    "standard_debt_description": "Standard skuldbeskrivning på Konto",
    "description": "Testing",
    "sender_address": {
        "address_line_1": "Redaregatan 50",
        "zip_code": "25236",
        "city": "Helsingborg",
        "country": "SE"
    },
    "invoice_address": {
        "address_line_1": "Redaregatan 50",
        "zip_code": "25236",
        "city": "Helsingborg",
        "country": "SE"
    },
    "payout_details": {
        "sek": {
            "bankgiro": "12312312"
        }
    }
}

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

Example response:

json

{
  "_id": "69132a8bc9ea54f691cc407c",
  "_created": "Tue, 11 Nov 2025 12:22:34 GMT",
  "_updated": "Tue, 11 Nov 2025 12:22:34 GMT",
  "_etag": "2646bc714fe277d4e317cfaddaeb450a34f28053",
  "_status": "OK"
}

Save the _id — this is the creditor ID you'll need when creating users and registering cases.

Non-Swedish Organizations

The vat_area field defaults to "sweden". For non-Swedish creditors, set it explicitly (e.g., "norway", "denmark", "eu") and use non_swedish_organization_no instead of organization_no. These fields are mutually exclusive. See the Creditor endpoint documentation for all available values.

Retrieve Access Groups

Before creating users, you need to know which access groups are available. When a creditor is created, Amili automatically generates creditor-level access groups (admin and user). Account-level groups (account_admin and api_user) are set up when the account is created.

Type	Scope	Description
`account_admin`	Account	Full access across all creditors on the account
`api_user`	Account	Programmatic API access — used by integration services
`admin`	Creditor	Can manage users and settings for a specific creditor
`user`	Creditor	Can handle cases and day-to-day operations for a specific creditor

Query the access groups for your account to find the group IDs you need:

TypeScriptPython

typescript

const token = await auth.getValidToken()
const where = encodeURIComponent(
  JSON.stringify({ account: '6662fb1df4d1eaf404cb08de' })
)

const response = await axios.get(
  `https://api-sandbox.amili.se/access--groups?where=${where}`,
  {
    headers: {
      'X-API-Key': token,
    },
  }
)

python

import json

token = auth.get_valid_token()
where = json.dumps({"account": "6662fb1df4d1eaf404cb08de"})

response = requests.get(
    'https://api-sandbox.amili.se/access--groups',
    params={'where': where},
    headers={'X-API-Key': token}
)
response.raise_for_status()
access_groups = response.json()['_items']

Example response (abbreviated):

json

{
  "_items": [
    {
      "_id": "6662fb1df4d1eaf404cb08e0",
      "account": "6662fb1df4d1eaf404cb08de",
      "name": "account_admin",
      "type": "account_admin"
    },
    {
      "_id": "6662fb1df4d1eaf404cb08e1",
      "account": "6662fb1df4d1eaf404cb08de",
      "name": "api_user",
      "type": "api_user"
    },
    {
      "_id": "69132a8bc9ea54f691cc407e",
      "account": "6662fb1df4d1eaf404cb08de",
      "creditor": "69132a8bc9ea54f691cc407c",
      "name": "admin",
      "type": "admin",
      "creditor_name": "Acme Inc"
    },
    {
      "_id": "69132a8bc9ea54f691cc407f",
      "account": "6662fb1df4d1eaf404cb08de",
      "creditor": "69132a8bc9ea54f691cc407c",
      "name": "user",
      "type": "user",
      "creditor_name": "Acme Inc"
    }
  ]
}

Use the _id of the relevant access group when creating users in the next step. For creditor-level users, use the groups where type is admin or user and creditor matches your creditor ID.

Create Users

Create users using the Users endpoint. The only difference between an admin and a regular user is which access group you assign. The oauth_type and email_oauth fields determine how the user authenticates to the Amili UI.

Creditor Admin

A creditor admin can manage users and settings for the creditor. Use the admin access group ID from the previous step:

TypeScriptPython

typescript

const adminUserData = {
  account: '6662fb1df4d1eaf404cb08de',
  name: 'Anna Andersson',
  email_data: {
    email: 'anna.andersson@example.com',
  },
  is_enabled: true,
  oauth_type: 'google',
  email_oauth: 'anna.andersson@example.com',
  data_access: [
    {
      access_group: '69132a8bc9ea54f691cc407e', // type: "admin"
    },
  ],
}

const token = await auth.getValidToken()
const response = await axios.post(
  'https://api-sandbox.amili.se/users',
  adminUserData,
  {
    headers: {
      'X-API-Key': token,
      'Content-Type': 'application/json',
    },
  }
)

python

admin_user_data = {
    "account": "6662fb1df4d1eaf404cb08de",
    "name": "Anna Andersson",
    "email_data": {
        "email": "anna.andersson@example.com",
    },
    "is_enabled": True,
    "oauth_type": "google",
    "email_oauth": "anna.andersson@example.com",
    "data_access": [{
        "access_group": "69132a8bc9ea54f691cc407e"  # type: "admin"
    }],
}

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

Regular Creditor User

A regular user can handle cases and perform day-to-day operations. The request is identical — only the access group changes to the user type:

TypeScriptPython

typescript

const userData = {
  account: '6662fb1df4d1eaf404cb08de',
  name: 'Erik Eriksson',
  email_data: {
    email: 'erik.eriksson@example.com',
  },
  is_enabled: true,
  oauth_type: 'google',
  email_oauth: 'erik.eriksson@example.com',
  data_access: [
    {
      access_group: '69132a8bc9ea54f691cc407f', // type: "user"
    },
  ],
}

const token = await auth.getValidToken()
const response = await axios.post(
  'https://api-sandbox.amili.se/users',
  userData,
  {
    headers: {
      'X-API-Key': token,
      'Content-Type': 'application/json',
    },
  }
)

python

user_data = {
    "account": "6662fb1df4d1eaf404cb08de",
    "name": "Erik Eriksson",
    "email_data": {
        "email": "erik.eriksson@example.com",
    },
    "is_enabled": True,
    "oauth_type": "google",
    "email_oauth": "erik.eriksson@example.com",
    "data_access": [{
        "access_group": "69132a8bc9ea54f691cc407f"  # type: "user"
    }],
}

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

Example response (same structure for both user types):

json

{
  "_id": "691332f4f22afe6587de55ea",
  "_created": "Tue, 11 Nov 2025 12:58:28 GMT",
  "_updated": "Tue, 11 Nov 2025 12:58:28 GMT",
  "_etag": "8f24ed684144a3572083739483e0c3bf05571f8b",
  "_status": "OK"
}

Multiple Access Groups

A user can be assigned to multiple access groups by adding more entries to the data_access array. For example, a user could have access to multiple creditors under the same account.

Next Steps

Case Flow Examples — Register cases against the newly created creditor
Invoice Flow Examples — Register invoices for the creditor
Creditor Endpoint — Complete API reference for creditor management
Users Endpoint — Complete API reference for user management

Creditor & User Management ​

Create a Creditor ​

Retrieve Access Groups ​

Create Users ​

Creditor Admin ​

Regular Creditor User ​

Next Steps ​

Creditor & User Management

Create a Creditor

Retrieve Access Groups

Create Users

Creditor Admin

Regular Creditor User

Next Steps