Start an origination process using the API

This guide shows how to create an origination process using Akkuro Lending APIs. You can use this guide for integration scenarios such as automatically starting a process in Akkuro Lending after a loan application is submitted from your system (for example, a self-service portal).

Prerequisites

Before you begin, make sure that:

You are familiar with the API Schemas. See Use API schema browser.
You have your base URL and understand how to use API versioning.
You have API credentials for your tenant and can obtain an access token for authentication and authorization.

Step 1: Find the process definition

Retrieve the process definition reference ID for the loan origination type you want to start. Send a GET request to /process-orchestration/process-definitions. For full schema details, see Definition API.

(Optional) Use query parameters to narrow down results to specific records:

Parameter	Description
`types`	Use `LoanOrigination` for this use case.
`codes`	The code of process definition in Akkuro Lending, which also corresponds to the message type.

Request example:

curl --request GET \
  'https://api.eu.lending.akkuro.io/process-orchestration/process-definitions?types=LoanOrigination&codes={messageType}' \
  --header 'Accept: application/json;api-version=2026.1.0' \
  --header 'Authorization: Bearer {your_JWT_token}'

A successful request returns a 200 OK status code with the process definition reference ID that you'll use to create a new process in step 2.

{
  // The process definition reference ID
  "referenceId": "f89864db-8be6-46b8-bea1-ab77008b9b7c",
  "type": "LoanOrigination",
  "code": "string",
  "name": {
    "nl-NL": "Een nederlandse versie",
    "en-GB": "An english version"
  },
  "isActive": true,
  "statuses": [
    {
      "referenceId": "c91d6964-70e0-4307-b96a-12e76319c2e6",
      "code": "string",
      "name": "string",
      "isActive": true
    }
  ],
  "updatedOn": "2019-08-24T14:15:22Z"
}

Step 2: Create a new process

To create an origination process, send a POST request to the /process-orchestration/processes endpoint. For full schema details, see Processes Management API.

The request body must specify the following information:

processDefinitionReferenceId: The process definition reference ID that you got in Step 1.
externalReferences: Information from your external system.
- origin: The source system (for example, a self-service portal).
- referenceId: The identifier of the reference in the source system.

Request example:

curl --request POST 'https://api.eu.lending.akkuro.io/process-orchestration/processes' \
  --header 'Accept: application/json;api-version=2026.1.0' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {your_JWT_token}' \
  --data '{
    "processDefinitionReferenceId": "f89864db-8be6-46b8-bea1-ab77008b9b7c",
    "externalReferences": [
      {
        "referenceId": "string",
        "origin": "Portal"
      }
    ]
  }'

A successful request returns a 201 Created status code with the process reference ID that you'll use to create a new message in step 3.

{
  // The process reference ID
  "referenceId": "35f2900d-73de-4850-9485-02c60d60dea8"
}

Step 3: Create a message for a process

Create a message for the loan application by sending a PUT request to /lodging/processes/{process-reference-id}/messages/{message-reference-id}. The request creates a draft message that acts as a container for your loan application submission. After you create the message, you can upload attachments to it and then dispatch it to start processing.

For full schema details, see Messages API.

Path parameters:

Parameter	Type	Description	Required
`process-reference-id`	string	The process reference ID returned in step 2.	Yes
`message-reference-id`	string	Specify a unique message reference ID that you generate in UUID format.	Yes

Include the following fields in the request body sent from your portal:

Field	Type	Description
`messageType`	string	The type of request being sent. Determines how the system processes the request.
`stakeholder`	object	The primary entity associated with the loan application.
`recipient`	object	The organization that receives and processes the application (for example, your tenant organization).
`sender`	object	The entity that submits the application (for example, a customer or a broker acting on behalf of a customer).

Request example:

curl --request PUT 'https://api.eu.lending.akkuro.io/lodging/processes/35f2900d-73de-4850-9485-02c60d60dea8/messages/5c320347-b559-46f5-bfff-0fc58c4f3d0b' \
  --header 'Accept: application/json;api-version=2022.1.0' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {your_JWT_token}' \
  --data '{
    "messageType": "{messageType}",
    "stakeholder": {"id": "12345678", "type": "Kvk"},
    "recipient": {"id": "{tenantId}", "type": "broker"},
    "sender": {"id": "12345678", "type": "Kvk"}
  }'

A successful request returns a 201 Created status code with the details of the created message.

{
  "referenceId": "5c320347-b559-46f5-bfff-0fc58c4f3d0b",
  "messageType": "string",
  "status": "Draft",
  "createdOn": "2022-01-01T12:30:00.252Z",
  "sentOn": "2022-01-01T12:30:00.252Z"
}

Step 4: Upload attachments

To upload the loan application attachments (XML files and supporting documents), send a PUT request to /lodging/processes/{process-reference-id}/messages/{message-reference-id}/attachments/{file-name} as multipart/form-data. Upload one attachment per request, which means you need to make multiple requests for multiple attachments.

For full schema details, see Attachments API.

Send the request as multipart/form-data with the following form fields:

Field	Type	Description
`content`	binary	The file content, such as an XML file or a PDF. For example, `<my-xml-file.xml>`.
`mimeType`	string	The MIME type of the file you wish to upload must match the file format. For example, `application/xml`, `application/pdf`.

Path parameters:

Parameter	Type	Description	Required
`process-reference-id`	string	The process reference ID you get in step 2.	Yes
`message-reference-id`	string	The message reference ID you get in step 3.	Yes
`file-name`	string	A unique file name (including extension) within the message.	Yes

The following are some examples of XML files and supporting documents:

(Required) Main loan request details: CleanOrderFinancingRequest.xml
Property and asset information: CleanOrderCollaterals.xml
(Required) Borrower and guarantor details: CleanOrderCounterparties.xml
Insurance and coverage/security information: CleanOrderCovers.xml
Notary and legal documentation: CleanOrderDeedPassing.xml
Completed application questionnaire: AnsweredQuestionnaire.xml
Document metadata: DocumentManagementFileDocuments.xml
Supporting files such as pdf, png, docx, and other {attachment}.extension.

Important

CleanOrderFinancingRequest.xml and CleanOrderCounterparties.xml are required and must be uploaded. Otherwise, the process does not start and no data is created in the process. All other attachments are optional.
The uploaded XML files must comply with the Akkuro Lending XML Schema Definition (XSD). Contact your Customer Service representative to request the XSDs and sample XML files.

The request example below uploads the XML files of the main loan request details from the loan application:

curl --request PUT \
  'https://api.eu.lending.akkuro.io/lodging/processes/35f2900d-73de-4850-9485-02c60d60dea8/messages/5c320347-b559-46f5-bfff-0fc58c4f3d0b/attachments/CleanOrderFinancingRequest.xml' \
  --header 'Accept: application/json;api-version=2022.1.0' \
  --header 'Authorization: Bearer {your_JWT_token}' \
  --form 'mimeType=application/xml' \
  --form 'content=@./CleanOrderFinancingRequest.xml'

The request example below uploads the PDF files of a payslip from the loan application:

curl --request PUT \
  'https://api.eu.lending.akkuro.io/lodging/processes/35f2900d-73de-4850-9485-02c60d60dea8/messages/5c320347-b559-46f5-bfff-0fc58c4f3d0b/attachments/payslip.pdf' \
  --header 'Accept: application/json;api-version=2022.1.0' \
  --header 'Authorization: Bearer {your_JWT_token}' \
  --form 'mimeType=application/pdf' \
  --form 'content=@./payslip.pdf'

When you upload an attachment, it is validated against the XML Schema Definition (XSD) to ensure that it’s correctly formatted. The API returns an error for uploads that fail.

The API returns a 204 No Content status code for the successful request. After uploading all required attachments, dispatch the message to start the process.

Step 5: Dispatch the message

Submit the complete message with all attachments by calling a PUT request to /lodging/processes/{process-reference-id}/messages/{message-reference-id}/send. This request sends the message to the lodging service, starts the process, and makes the application available for processing.

For full schema details, see Messages API.

tip

If you want to receive message handling result notifications, subscribe to the lodging.message.handling_succeeded and lodging.message.handling_failed events using the Lodging Events API.

To learn more about webhooks, see About webhooks.

Request example:

curl --request PUT 'https://api.eu.lending.akkuro.io/lodging/processes/35f2900d-73de-4850-9485-02c60d60dea8/messages/5c320347-b559-46f5-bfff-0fc58c4f3d0b/send' \
  --header 'Authorization: Bearer {your_JWT_token}' \
  --header 'Accept: application/json;api-version=2022.1.0' \
  --header 'Content-Type: application/json'

If the request succeeds, the API returns 200 OK and the message status changes to Sent. For example:

{
  "referenceId": "string",
  "messageType": "string",
  "status": "Sent",
  "createdOn": "2022-01-01T12:30:00.252Z",
  "sentOn": "2022-01-01T12:30:00.252Z",
  "stakeholder": {
    "id": "string",
    "type": "Broker key, Kvk (ChamberOfCommerce)"
  },
  "recipient": {
    "id": "string",
    "type": "Broker key, Kvk (ChamberOfCommerce)"
  },
  "sender": {
    "id": "string",
    "type": "Broker key, Kvk (ChamberOfCommerce)"
  },
  "updatedOn": "2022-01-01T12:30:00.252Z",
  "attachments": [
    {
      "fileName": "string",
      "mimeType": "application/pdf",
      "size": 0,
      "createdOn": "2022-01-01T12:30:00.252Z",
      "updatedOn": "2022-01-01T12:30:00.252Z"
    }
  ]
}

Results

Once successful, the origination process is started and becomes available in the Akkuro Lending platform.

Receive process status updates using webhooks

To receive notifications when a process changes status, subscribe to the process.status-changed event using the Process events API.

Refer to About webhooks if you want to learn more about webhook concepts and how to use them.

Prerequisites​

Step 1: Find the process definition​

Step 2: Create a new process​

Step 3: Create a message for a process​

Step 4: Upload attachments​

Step 5: Dispatch the message​

Results​

Receive process status updates using webhooks​

Prerequisites

Step 1: Find the process definition

Step 2: Create a new process

Step 3: Create a message for a process

Step 4: Upload attachments

Step 5: Dispatch the message

Results

Receive process status updates using webhooks