Partner Onboarding
This guide covers how a partner platform provisions a new creditor account on behalf of a client. The partner creates the account, an initial creditor, and related users via the API.
This guide uses the AuthTokenProvider for authentication in examples — see the Authentication guide for setup details.
Overview
There are two ways to onboard a new creditor, depending on whether the partner collects the required data upfront or delegates that step to the client user via the Amili App.
Option A — Activate via Amili App: The partner creates the account with an inactive creditor and directs the client user to complete setup in the Amili App. Fields required for activation — such as payout details and sender address — do not need to be provided at this stage, as the client user will supply them during the onboarding flow in the Amili App.
Option B — Direct activation: The partner collects all required data upfront and creates the account with an already-active creditor. The account follows the standard agreement as defined for partner.
For Option A, the partner's API responsibility ends after creating the account and user — all remaining steps happen inside the Amili App.
Step 1: Create the Account
Use the Account endpoint to create the account and its initial creditor in a single call. The initial_creditor_data field is a write-only object that is processed server-side to create the creditor — it is not stored on the account document.
Option A: Creating account with partial data
The creditor is created in an inactive state. Fields required for activation — standard_debt_description, sender_address, invoice_address, and payout_details — are omitted here and collected from the client user during the Amili App onboarding flow.
Onboarding flags
When a partner has configuration.force_creditor_onboarding enabled (configured by Amili), new accounts automatically receive the enable_creditor_onboarding flag. This tells the Amili App to show the onboarding flow in the UI when the client user logs in for the first time.
If your partner account is not configured with force_creditor_onboarding, you can set enable_creditor_onboarding: true explicitly on the account.
const accountData = {
partner: '674dbeab08847b9501cc9130',
name: 'Exempel Företag AB',
organization_no: '556123-4567',
agreement_address: {
address_line_1: 'Storgatan 1',
zip_code: '11122',
city: 'Stockholm',
country: 'SE',
},
initial_creditor_data: {
is_active: false,
},
}
const token = await auth.getValidToken()
const response = await axios.post(
'https://api-sandbox.amili.se/accounts',
accountData,
{
headers: {
'X-API-Key': token,
'Content-Type': 'application/json',
},
}
)account_data = {
"partner": "674dbeab08847b9501cc9130",
"name": "Exempel Företag AB",
"organization_no": "556123-4567",
"agreement_address": {
"address_line_1": "Storgatan 1",
"zip_code": "11122",
"city": "Stockholm",
"country": "SE",
},
"initial_creditor_data": {
"is_active": False,
},
}
token = auth.get_valid_token()
response = requests.post(
"https://api-sandbox.amili.se/accounts",
json=account_data,
headers={
"X-API-Key": token,
"Content-Type": "application/json",
},
)
response.raise_for_status()
result = response.json()Option B: Creating account with complete data
The creditor is created in an active state. All fields required for activation must be provided upfront: standard_debt_description, sender_address, invoice_address, and payout_details (with at least one currency and account type).
const accountData = {
partner: '674dbeab08847b9501cc9130',
name: 'Exempel Företag AB',
organization_no: '556123-4567',
agreement_address: {
address_line_1: 'Storgatan 1',
zip_code: '11122',
city: 'Stockholm',
country: 'SE',
},
initial_creditor_data: {
is_active: true,
standard_debt_description: 'Obetalda fakturor',
sender_address: {
address_line_1: 'Storgatan 1',
zip_code: '11122',
city: 'Stockholm',
country: 'SE',
},
invoice_address: {
address_line_1: 'Storgatan 1',
zip_code: '11122',
city: 'Stockholm',
country: 'SE',
},
payout_details: {
sek: {
bankgiro: '12312312',
},
},
},
}
const token = await auth.getValidToken()
const response = await axios.post(
'https://api-sandbox.amili.se/accounts',
accountData,
{
headers: {
'X-API-Key': token,
'Content-Type': 'application/json',
},
}
)account_data = {
"partner": "674dbeab08847b9501cc9130",
"name": "Exempel Företag AB",
"organization_no": "556123-4567",
"agreement_address": {
"address_line_1": "Storgatan 1",
"zip_code": "11122",
"city": "Stockholm",
"country": "SE",
},
"initial_creditor_data": {
"is_active": True,
"standard_debt_description": "Obetalda fakturor",
"sender_address": {
"address_line_1": "Storgatan 1",
"zip_code": "11122",
"city": "Stockholm",
"country": "SE",
},
"invoice_address": {
"address_line_1": "Storgatan 1",
"zip_code": "11122",
"city": "Stockholm",
"country": "SE",
},
"payout_details": {
"sek": {
"bankgiro": "12312312",
},
},
},
}
token = auth.get_valid_token()
response = requests.post(
"https://api-sandbox.amili.se/accounts",
json=account_data,
headers={
"X-API-Key": token,
"Content-Type": "application/json",
},
)
response.raise_for_status()
result = response.json()Response
Both options return the same response structure, including the new account ID and the ID of the initial creditor:
{
"_id": "674dbeaf08847b9501cc9132",
"_creditor": "674dbeb208847b9501cc9138",
"_status": "OK",
"_created": "Tue, 07 Oct 2025 08:00:00 GMT",
"_updated": "Tue, 07 Oct 2025 08:00:00 GMT",
"_etag": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
}Key IDs in the response
_id— The account ID. Store this for future API calls that require anaccountreference._creditor— The initial creditor ID. Store this to track onboarding status and register cases once the creditor is active.
Store both IDs. The creditor ID in particular is needed for all subsequent case and invoice registrations.
Step 2: Create Client Users
Create at least one account admin user to give the client access to the account.
const accountId = '674dbeaf08847b9501cc9132'
const token = await auth.getValidToken()
// Find the account_admin access group for the new account
const where = encodeURIComponent(
JSON.stringify({ account: accountId, type: 'account_admin' })
)
const groupsResponse = await axios.get(
`https://api-sandbox.amili.se/access--groups?where=${where}`,
{ headers: { 'X-API-Key': token } }
)
const accountAdminGroupId = groupsResponse.data._items[0]._id
// Create the client user
const userResponse = await axios.post(
'https://api-sandbox.amili.se/users',
{
account: accountId,
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: accountAdminGroupId }],
},
{ headers: { 'X-API-Key': token, 'Content-Type': 'application/json' } }
)import json
account_id = '674dbeaf08847b9501cc9132'
token = auth.get_valid_token()
headers = {'X-API-Key': token, 'Content-Type': 'application/json'}
# Find the account_admin access group for the new account
where = json.dumps({'account': account_id, 'type': 'account_admin'})
groups_response = requests.get(
'https://api-sandbox.amili.se/access--groups',
params={'where': where},
headers=headers,
)
groups_response.raise_for_status()
account_admin_group_id = groups_response.json()['_items'][0]['_id']
# Create the client user
user_response = requests.post(
'https://api-sandbox.amili.se/users',
json={
'account': account_id,
'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': account_admin_group_id}],
},
headers=headers,
)
user_response.raise_for_status()See User Management for more details on access group types and creating creditor-level users after onboarding is complete.
Step 3: Onboarding completion via Amili App
Option A only
This step applies when using Option A (activate via Amili App). For Option B, the creditor is already active after Step 1 and no further action is required.
Direct the Client User to the Amili App
Once the account and user are created, direct the client user to the Amili App (e.g. https://app-sandbox.amili.se for sandbox). When they log in, the app automatically detects the pending onboarding state and guides them through the process, which includes:
- Confirming company details and configuring payout information (bank account, sender address, invoice address)
- Reviewing and signing the legal agreement using Swedish BankID or Visma e-sign
Once the client user completes these steps, the creditor is activated and the partner can begin registering invoices and cases against it via the API.
App URLs
For the correct app URL for your environment, refer to the Environments page.
Checking Activation Status
The creditor created in Step 1 has is_active: false until onboarding is complete. Attempting to register invoices or cases against an inactive creditor will be rejected by the API.
A good pattern is to check the creditor's activation status at the start of a client user session — or lazily, at the point where the client user tries to perform an action that requires an active creditor. Retrieve the creditor using its ID and inspect the is_active field:
GET /creditors/{creditor_id}If is_active is false, surface a message to the client user explaining that setup is not yet complete and direct them back to the Amili App to finish onboarding.
This is a one-time check per session rather than a recurring poll.