Example Workflow

This guide covers the end-to-end workflow for submitting invoices to Amili Collection API: authenticating with Identiverse, creating an invoice batch, and polling the batch result.

Flow Overview

1. Authenticate  →  POST {identiverse_base_url}/token
2. Create invoices  →  POST /collection/v1/orgs/{orgId}/invoices
3. Poll result  →  GET /collection/v1/batches/{batchId}

Invoice creation is asynchronous. The API accepts the request immediately and returns a batch reference. Poll the batch endpoint until the status changes from QUEUED to a terminal state (SUCCESS, PARTIAL, or FAILED).

Step 1 — Authenticate (POST /token)

Obtain a Bearer token from Identiverse using the OAuth 2.0 client credentials flow. Check out our Getting started section for how to get your ClientId and ClientSecret.

Environments

Environment	Base URL
Staging	`https://auth.staging.amili.no`
Production	`https://auth.amili.no`

Endpoint

Method: POST

URL: {identiverse_base_url}/token

Content-Type: application/x-www-form-urlencoded

Request body

Field	Value
`grant_type`	`client_credentials`
`client_id`	Your assigned client ID
`client_secret`	Your assigned client secret

Example

POST https://auth.amili.no/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=my-integration&client_secret=s3cr3t

Response

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "token_type": "Bearer",
  "not_before": 1709300000,
  "expires_in": 3600,
  "expires_on": 1709303600,
  "resource": "04468334-ec11-4ef8-9e7c-e124bacbd5c1"
}

Field	Description
`access_token`	Include as `Authorization: Bearer {access_token}` on all subsequent requests
`expires_in`	Lifetime in seconds (typically 3600 s / 1 hour)
`expires_on`	Unix timestamp when the token expires

Cache the token and reuse it until expires_on. Requesting a new token on every call will result in unnecessary latency.

Step 2 — Create Invoices (POST /orgs/{orgId}/invoices)

Submit one or more invoices for processing. The request is queued asynchronously and a batch reference is returned immediately.

Endpoint

Method: POST

URL: /collection/v1/orgs/{orgId}/invoices

Authorization: Bearer {access_token}

Required permission: write:collection.case

Content-Type: application/json

Path parameters

Parameter	Type	Description
`orgId`	UUID	The organization identifier issued by Amili

Request body

{
  "invoices": [ <Invoice>, ... ]
}

Example request

POST https://api.staging.amili.no/collection/v1/orgs/3fa85f64-5717-4562-b3fc-2c963f66afa6/invoices
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
Content-Type: application/json

{
  "invoices": [
    {
      "type": "NOTICE",
      "invoiceNumber": "INV-2024-00123",
      "originalInvoiceAmount": 4500.00,
      "currency": "NOK",
      "invoiceDate": "2024-01-15T00:00:00Z",
      "dueDate": "2024-02-15T00:00:00Z",
      "uniqueSourceInvoiceId": "erp-order-9981",
      "description": "Consulting services January 2024",
      "ocrReferenceNumber": "123456789",
      "debtors": [
        {
          "type": "PRIVATE",
          "firstname": "Kari",
          "lastname": "Nordmann",
          "customerNumber": "CUST-001",
          "identificationNumber": "12345678901",
          "emails": [
            { "value": "kari.nordmann@example.com" }
          ],
          "phoneNumbers": [
            { "value": "+4798765432", "countryCode": "NO" }
          ],
          "addresses": [
            {
              "street": "Storgata 1",
              "city": "Oslo",
              "zipCode": "0155",
              "countryCode": "NO"
            }
          ]
        }
      ],
      "claims": [
        {
          "type": "PRINCIPAL",
          "remainingAmount": 4500.00,
          "description": "Main invoice amount"
        }
      ]
    }
  ]
}

Response — 202 Accepted

{
  "data": {
    "batchId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "batchUrl": "https://api.staging.amili.no/collection/v1/batches/d290f1ee-6c54-4b01-90e6-d701748f0851"
  }
}

Field	Description
`batchId`	UUID of the created batch. Use this to poll the result
`batchUrl`	Absolute URL to the batch resource

Step 3 — Get Batch Result (GET /batches/{batchId})

Poll this endpoint after creating an invoice batch to check processing status and retrieve per-invoice results.

Endpoint

Method: GET

URL: /collection/v1/batches/{batchId}

Authorization: Bearer {access_token}

Path parameters

Parameter	Type	Description
`batchId`	UUID	The batch ID returned from the invoice creation response

Example request

GET https://api.staging.amili.no/collection/v1/batches/d290f1ee-6c54-4b01-90e6-d701748f0851
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...

Response — 200 OK

{
  "data": {
    "batchId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "type": "INVOICE",
    "status": "PARTIAL",
    "createdAt": "2024-01-15T10:30:00Z",
    "finishedAt": "2024-01-15T10:30:05Z",
    "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "createdBy": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "succeeded": [
      {
        "type": "INVOICE",
        "invoiceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "invoiceNumber": "INV-2024-00123",
        "caseId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "caseNumber": "CASE-2024-00456"
      }
    ],
    "failed": [
      {
        "type": "INVOICE",
        "invoiceNumber": "INV-2024-00124",
        "errors": ["Debtor identification number is invalid"]
      }
    ]
  }
}

Batch status values

Status	Terminal	Description
`QUEUED`	❌	Batch received and waiting to be processed. Keep polling
`SUCCESS`	✅	All invoices in the batch were processed successfully
`PARTIAL`	✅	Some invoices succeeded, some failed. Check `succeeded` and `failed` arrays
`FAILED`	✅	All invoices in the batch failed

Batch response fields

Field	Type	Description
`batchId`	UUID	Identifies the batch
`type`	string	Always `INVOICE` for invoice batches
`status`	string	See status table above
`createdAt`	datetime	When the batch was queued
`finishedAt`	datetime \| null	When processing completed. `null` while still `QUEUED`
`organizationId`	UUID	Organization that owns this batch
`createdBy`	UUID	Identity that submitted the batch
`succeeded`	array	Per-invoice success results
`failed`	array	Per-invoice failure results

Succeeded item fields

Field	Description
`invoiceId`	UUID of the created invoice in the collection system
`invoiceNumber`	The invoice number from your request
`caseId`	UUID of the collection case created for this invoice
`caseNumber`	Human-readable case reference

Failed item fields

Field	Description
`invoiceNumber`	The invoice number from your request
`errors`	List of error messages explaining why processing failed

Recommended Polling Strategy

Since the batch is processed asynchronously, poll with exponential backoff to avoid hammering the API:

Attempt 1: wait 1 s
Attempt 2: wait 2 s
Attempt 3: wait 4 s
Attempt 4: wait 8 s
...
Max interval: 30 s
Timeout after: 5 min

Stop polling when status is SUCCESS, PARTIAL, or FAILED.

Flow Overview#

Step 1 — Authenticate (POST /token)#

Endpoint#

Request body#

Example#

Response#

Step 2 — Create Invoices (POST /orgs/{orgId}/invoices)#

Endpoint#

Path parameters#

Request body#

Example request#

Response — 202 Accepted#

Step 3 — Get Batch Result (GET /batches/{batchId})#

Endpoint#

Path parameters#

Example request#

Response — 200 OK#

Batch status values#

Batch response fields#

Succeeded item fields#

Failed item fields#

Recommended Polling Strategy#

Flow Overview

Step 1 — Authenticate (POST /token)

Endpoint

Request body

Example

Response

Step 2 — Create Invoices (POST /orgs/{orgId}/invoices)

Endpoint

Path parameters

Request body

Example request

Response — 202 Accepted

Step 3 — Get Batch Result (GET /batches/{batchId})

Endpoint

Path parameters

Example request

Response — 200 OK

Batch status values

Batch response fields

Succeeded item fields

Failed item fields

Recommended Polling Strategy