---
title: "Receivables API"
canonical: https://documentation.maventa.com/api-specification/rest-api/receivables-api/
---

The Receivables API provides a shared set of endpoints for tracking assignments and events across all of Maventa's debt collection and reminder services. Regardless of which service is used — Ropo, Amili Kassavirta, or Amili Perintä — the same API is used to list assignments, follow collection status, and report payments or credit notes.

Service-specific operations such as activation, configuration, and invoice transfers use dedicated endpoints in the AutoXChange API. See each integration guide for details:

- [Ropo's reminder and collection service](https://documentation.maventa.com/integration-guide/accounts-receivable/ropo-debt-collection/) — available in Finland, Sweden, and Norway
- [Amili Kassavirta](https://documentation.maventa.com/integration-guide/accounts-receivable/amili-kassavirta/) — available in Finland
- [Amili Perintä](https://documentation.maventa.com/integration-guide/accounts-receivable/amili-perinta/) — available in Finland

Detailed technical information in Swagger: [Receivables API technical documentation](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/)

For using the Receivables API, the authentication scope `receivables:assignments` is required.

## Assignments and events **All services**

These endpoints are shared across all services. Each invoice that enters the collection process creates an assignment. Events on assignments track status changes, payments, reminders, and other collection activities.

* [`GET /v1/assignments`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/assignments/getV1Assignments) — list assignments with filtering (debtor name, creation date, closing date, etc.)
* [`GET /v1/assignments/{assignment_id}`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/assignments/getV1AssignmentsAssignmentId) — fetch a specific assignment and its events
* [`GET /v1/assignments/{assignment_id}/events`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/assignments/getV1AssignmentsAssignmentIdEvents) — fetch only the events for an assignment
* [`GET /v1/assignments/overview`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/assignments/getV1AssignmentsOverview) — fetch an overview of assignments (open, soon to due, overdue)
* [`POST /v1/assignments/{assignment_id}/events`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/assignments/postV1AssignmentsAssignmentIdEvents) — add an event to an assignment (direct payment, credit note, due date change, cancellation, etc.)
* [`POST /v1/assignments/{assignment_id}/events/{event_id}/seen`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/assignments/postV1AssignmentsAssignmentIdEventsEventIdSeen) — mark an event as seen
* [`GET /v1/events`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/events/getV1Events) — list assignment events across all assignments

## Service levels **Amili Kassavirta only**

Service levels allow you to set different collection behaviours per customer. Only applicable to Amili Kassavirta.

* [`GET /v1/service_levels`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/service_levels/getV1ServiceLevels) — list customers with a non-default service level (premium, vip, or service_bypass). Customers with the default service level are not returned.
* [`GET /v1/service_levels/{customer_bid}`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/service_levels/getV1ServiceLevelsCustomerBid) — get the service level for a specific customer
* [`PATCH /v1/service_levels/{customer_bid}`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/service_levels/patchV1ServiceLevelsCustomerBid) — set the service level for a specific customer

## Messaging **Amili Kassavirta and Amili Perintä only**

Messaging enables communication between the sender and Visma Amili. Adding messaging support to the integration is highly recommended to ensure important messages are not missed.

* [`GET /v1/message_threads`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/message_threads/getV1MessageThreads) — list all message threads (shows the latest message from each thread)
* [`PATCH /v1/message_threads/{thread_id}`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/message_threads/patchV1MessageThreadsThreadId) — flag a message thread
* [`GET /v1/message_threads/{thread_id}`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/message_threads/getV1MessageThreadsThreadId) — show message thread information (latest message only)
* [`GET /v1/message_threads/{thread_id}/messages`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/message_threads/getV1MessageThreadsThreadIdMessages) — show all messages in a thread
* [`POST /v1/message_threads/{thread_id}/messages`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/message_threads/postV1MessageThreadsThreadIdMessages) — add a message to a thread
* [`POST /v1/assignments/{assignment_id}/messages`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/assignments/postV1AssignmentsAssignmentIdMessages) — add a message for an assignment (creates a thread if none exists)
* [`GET /v1/assignments/{assignment_id}/messages`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/assignments/getV1AssignmentsAssignmentIdMessages) — show all messages for an assignment
* [`PUT /v1/messages/{message_id}/seen`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/messages/putV1MessagesMessageIdSeen) — mark a message as seen

## API endpoints

### GET /v2/services/amili/receivables

Current state of the Amili collection services

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Current state of the Amili collection services | `ReceivablesService` |

### PUT /v2/services/amili/receivables

Start the Amili collection services onboarding

**Request body**

Schema: `putV2ServicesAmiliReceivables`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| iban | `string` | yes | IBAN |
| bic | `string` | yes | Bank identifier code |
| bank | `string` | yes | Bank |
| contact_person | `string` | yes | Contact person |
| contact_email | `string` | yes | Contact email |
| customer_service_email | `string` | yes | Customer service email |
| customer_service_phone_number | `string` | no | Customer service phone number |
| contact_phone_number | `string` | yes | Contact Phone Number |
| authorization_email | `string` | no | Authorization email, if this is not provided you will not get an email and the authorization process will proceed by accessing the activation_url from the GET method. |
| accountable_party | `string` | no | Party who is responsible for monitoring the payments and adding them to assignments. The value "vfs" means using VFS account number, reference number and PDF image. The value "company" means using senders own account number, reference number and PDF image. |
| service_type | `string` | no | Choose full collection services (Amili Kassavirta, default) or Amili Perintä |
| billing_address | `object` | yes |  |
| postal_address | `object` | no | Postal address if different than the company address |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Start the Amili collection services onboarding | `ReceivablesService` |

### PATCH /v2/services/amili/receivables

Update the Amili collection services

**Request body**

Schema: `patchV2ServicesAmiliReceivables`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| accountable_party | `string` | no | Party who is responsible for monitoring the payments and adding them to assignments. The value "vfs" means using VFS account number, reference number and PDF image. The value "company" means using senders own account number, reference number and PDF image. |
| service_type | `string` | no | Choose full collection services (Amili Kassavirta, default) or Amili Perintä |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | Update successful |  |

### DELETE /v2/services/amili/receivables

Disable the Amili collection services

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | Service disabled |  |

### GET /v2/services/intrum/receivables

Current state of the Intrum collection services

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Current state of the Intrum collection services | `API_Entities_CompanyServices_Intrum` |

### PUT /v2/services/intrum/receivables

Start the Intrum collection services onboarding

**Request body**

Schema: `putV2ServicesIntrumReceivables`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| agreement_contact_phone | `string` | yes | Contact phone number for agreement purposes |
| agreement_contact_name | `string` | yes | Contact name for agreement purposes |
| agreement_contact_email | `string` | yes | Contact email for agreement purposes |
| details | `object` | no |  |
| existing_agreement | `boolean` | no | Company already has an agreement with Intrum, skipping the activation process.Default is false. |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 201 | Start the Intrum collection services onboarding | `API_Entities_CompanyServices_Intrum` |

### PATCH /v2/services/intrum/receivables

Update the Intrum collection services

**Request body**

Schema: `patchV2ServicesIntrumReceivables`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| client_code | `string` | no | Client code. This is used to activate a pending service after contract has been signed and the agency has given a client_code to the customer. |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | Update successful |  |

### DELETE /v2/services/intrum/receivables

Disable the Intrum collection services

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | Service disabled |  |

### PUT /v2/services/ropo/receivables

Start the Ropo collection services onboarding [EXPERIMENTAL]

**Request body**

Schema: `putV2ServicesRopoReceivables`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| agreement_contact_email | `string` | yes | Contact email for agreement purposes |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 201 | Start the Ropo collection services onboarding | `API_Entities_CompanyServices_Ropo` |

### GET /v2/services/receivables

Current state of the collection services

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Current state of the collection services | `API_Entities_CompanyServices_ReceivablesDetails` |

### GET /v1/services/receivables

Current state of the collection services

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Current state of the collection services | `ReceivablesService` |

### PUT /v1/services/receivables

Start the collection services onboarding

**Request body**

Schema: `putV1ServicesReceivables`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| iban | `string` | yes | IBAN |
| bic | `string` | yes | Bank identifier code |
| bank | `string` | yes | Bank |
| contact_person | `string` | yes | Contact person |
| contact_email | `string` | yes | Contact email |
| customer_service_email | `string` | yes | Customer service email |
| customer_service_phone_number | `string` | no | Customer service phone number |
| contact_phone_number | `string` | yes | Contact Phone Number |
| authorization_email | `string` | no | Authorization email, if this is not provided you will not get an email and the authorization process will proceed by accessing the activation_url from the GET method. |
| accountable_party | `string` | no | Party who is responsible for monitoring the payments and adding them to assignments. The value "vfs" means using VFS account number, reference number and PDF image. The value "company" means using senders own account number, reference number and PDF image. |
| service_type | `string` | no | Choose full collection services (Amili Kassavirta, default) or Amili Perintä |
| billing_address | `object` | yes |  |
| postal_address | `object` | no | Postal address if different than the company address |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Start the collection services onboarding | `ReceivablesService` |

### PATCH /v1/services/receivables

Update the collection services

**Request body**

Schema: `patchV1ServicesReceivables`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| accountable_party | `string` | no | Party who is responsible for monitoring the payments and adding them to assignments. The value "vfs" means using VFS account number, reference number and PDF image. The value "company" means using senders own account number, reference number and PDF image. |
| service_type | `string` | no | Choose full collection services (Amili Kassavirta, default) or Amili Perintä |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | Update successful |  |

### DELETE /v1/services/receivables

Disable the collection services

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | Service disabled |  |

### GET /v1/invoices/{id}/assignment


Get assignment for invoice

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Invoice ID |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Return only the assignment status and error reason when in pending or error. Ok status returns the link to the assignment in the collection services API when the assignment request has been completed. | `Invoices_HttpApi_Entities_InvoiceAssignment` |
| 404 | - **not_found**: Requested resource not found or you don't have access to it | `API_Entities_Error` |

### POST /v1/invoices/{id}/assignment


Post assignment for invoice

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Invoice ID |

**Request body**

Schema: `postV1InvoicesIdAssignment`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| collection_type | `string` | yes | Collection type |
| collectable_amount | `number` | no | Total collectable amount, needs to be a positive number (for example 100.50). Cannot be used in combination with amounts. |
| amounts | `object` | no | Detailed breakdown of amounts. Cannot be used in combination with collectable_amount. |
| payer_identifiers | `array[string]` | no | List of payer customer IDs, used for joining assignments when the payers are the same |
| payer_ssns | `array[string]` | no | List of payer customer social security numbers, used for the legal collection process |
| industry_specific_options | `object` | no | Industry specific optional parameters |
| assignment_summary | `string` | no | Summary of the assignment, will be included in the reminder and collection letters. Length 2-64 characters. |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 202 | Assignment request has been accepted for processing |  |
| 404 | - **not_found**: Requested resource not found or you don't have access to it | `API_Entities_Error` |
| 400 | - **invalid_parameters**: Request parameters are invalid | `API_Entities_Error` |
| 403 | - **forbidden**: Requested operation for resource is not allowed | `API_Entities_Error` |

### GET /v2/invoices/{id}/assignment


Get assignment for invoice

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Invoice ID |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Return only the assignment status and error reason when in pending or error. Ok status returns the link to the assignment in the Receivables API when the assignment request has been completed. | `Invoices_HttpApi_Entities_InvoiceAssignmentV2` |
| 404 | - **not_found**: Requested resource not found or you don't have access to it | `API_Entities_Error` |

### POST /v2/invoices/{id}/assignment/ropo


Post assignment for invoice

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Invoice ID |

**Request body**

Schema: `postV2InvoicesIdAssignmentRopo`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| collection_type | `string` | yes | Collection type |
| receivables_type | `string` | yes | Collection services type |
| amounts | `object` | no | Detailed breakdown of amounts. Cannot be used in combination with collectable_amount. |
| payers | `array[object]` | yes | List of payers for the invoice |
| assignment_summary | `string` | no | Free text summary of the assignment, sent to the collection agency. |
| reminder_date | `string` | no | Date of the original reminder sent to the customer. Format: YYYY-MM-DD. Required when sending to collection directly (collection_type=collection). |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 202 | Assignment request has been accepted for processing |  |
| 404 | - **not_found**: Requested resource not found or you don't have access to it | `API_Entities_Error` |
| 400 | - **invalid_parameters**: Request parameters are invalid | `API_Entities_Error` |
| 403 | - **forbidden**: Requested operation for resource is not allowed | `API_Entities_Error` |

### POST /v2/invoices/{id}/assignment/intrum


Post assignment for invoice

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Invoice ID |

**Request body**

Schema: `postV2InvoicesIdAssignmentIntrum`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| collection_type | `string` | yes | Collection type |
| receivables_type | `string` | yes | Collection services type |
| amounts | `object` | no | Detailed breakdown of amounts. Cannot be used in combination with collectable_amount. |
| payers | `array[object]` | yes | List of payers for the invoice |
| rental | `object` | no | Only for collectibles regarding rental business. Cannot be used in combination with housing_charge. Currently only supported with the Intrum collection agency. |
| housing_charge | `object` | no | Only for collectibles regarding housing charges. Cannot be used in combination with rental. Currently only supported with the Intrum collection agency. |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 202 | Assignment request has been accepted for processing |  |
| 404 | - **not_found**: Requested resource not found or you don't have access to it | `API_Entities_Error` |
| 400 | - **invalid_parameters**: Request parameters are invalid | `API_Entities_Error` |
| 403 | - **forbidden**: Requested operation for resource is not allowed | `API_Entities_Error` |

### POST /v2/invoices/{id}/assignment/amili


Post assignment for invoice

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Invoice ID |

**Request body**

Schema: `postV2InvoicesIdAssignmentAmili`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| collection_type | `string` | yes | Collection type |
| receivables_type | `string` | yes | Collection services type |
| amounts | `object` | no | Detailed breakdown of amounts. Cannot be used in combination with collectable_amount. |
| payers | `array[object]` | yes | List of payers for the invoice |
| assignment_summary | `string` | no | Free text summary of the assignment, sent to the collection agency. |
| reminder_date | `string` | no | Date of the original reminder sent to the customer. Format: YYYY-MM-DD. Required when sending to collection directly (collection_type=collection). |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 202 | Assignment request has been accepted for processing |  |
| 404 | - **not_found**: Requested resource not found or you don't have access to it | `API_Entities_Error` |
| 400 | - **invalid_parameters**: Request parameters are invalid | `API_Entities_Error` |
| 403 | - **forbidden**: Requested operation for resource is not allowed | `API_Entities_Error` |


_OpenAPI spec snapshot: 2026-05-06_