Skip to main content

Load financing execution data

Overview​

Upload Financing Execution data to the staging area using a JSON stream. The API provides separate endpoints for the following data types:

Use the appropriate endpoint based on the type of data you are uploading.

Refer to the Migrate Financing Executions API for detailed schemas.

Load financing execution data to staging​

Additional repayments​

Additional repayments are payments made outside the regular repayment schedule. They are used to reduce the outstanding loan balance faster when extra funds become available. For example, if a deposit account is closed with a positive balance, that amount can be applied as an additional repayment to the loan. Refer to Additional repayments for further details.

In Akkuro Lending, they include the following types:

  • Repayments from construction deposits
  • Early repayments
  • Full repayments

To upload the additional repayments data, use the following endpoint:

Request​

PUT /financing-execution/migrations/{migration-reference-id}/staging/additional-repayments

Request headers:

NameDescriptionRequired
Content-TypeSpecifies the request body format. Two supported values are application/jsonl and application/json-seq.Yes
AcceptSpecifies the API version. It’s recommended to include an API version in this header to prevent breaking changes. See API versioning for details.No

It requires one path parameter:

NameDescriptionRequired
migration-reference-idThe migration reference ID obtained from Step 1.Yes

Provide the data you want to upload in the request body. For example:

{
  "agreementReferenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
  "processReferenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
  "status": "Draft",
  "effectiveDate": "2019-08-24",
  "administrationFee": {
    "amount": 99.95,
    "currency": "string"
  },
  "requestReceivedDate": "2019-08-24",
  "type": "repayment-from-construction-deposit",
  "referenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
  "facilities": [
    {
      "targetFacilityReferenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
      "charge": {
        "amount": {
          "amount": 99.95,
          "currency": "string"
        },
        "comparativeNominalRate": 0
      },
      "referenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
      "type": "facility-repayment-from-construction-deposit"
    }
  ]
}

Response​

The API returns a per-record result for each record submitted in the request body. Each result corresponds to a record, identified by its referenceId, and indicates whether the record was processed successfully.

  • If a record is valid, it is staged, and the API returns the following response:

    {
      "referenceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "isSuccessful": true,
      "errors": []
    }

  • If a record is invalid, it is not staged. The API returns an error response that describes the issue:

    {
      "referenceId": "a1b2c3d4-e5f6-1234-5678-9abcdef01234",
      "isSuccessful": false,
      "errors": [
        {
          "field": "initials",
          "message": "MISSING_REQUIRED_FIELD"
        }
      ]
    }

    You need to correct these records and re-stage them.

Debit mandates​

A debit mandate is an authorization that allows the lender to automatically collect payments from the borrower’s bank account. Refer to Debit mandates for further details.

Request​

PUT /financing-execution/migrations/{migration-reference-id}/staging/debit-mandates

Request headers and path parameters are the same as described in Additional repayments.

Provide the data you want to upload in the request body. For example:

{
  "agreementReferenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
  "mandateType": "SEPA",
  "mandateRelationType": "BTB",
  "description": "string",
  "issuedOn": "2019-08-24T14:15:22Z",
  "creditorId": "NL97ZZZ123456780001",
  "mandateReference": "02c193eb5ecf4814967492519b94cb3b",
  "mandateFormFileDocumentReferenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
  "mandateConfirmationFileDocumentReferenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
  "referenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
  "process": {
    "isClosed": true,
    "closedOn": "2019-08-24T14:15:22Z",
    "isSuccessful": true,
    "referenceId": "35f2900d-73de-4850-9485-02c60d60dea8"
  },
  "debtor": {
    "bankAccount": {
      "ascription": "string",
      "iban": "string",
      "bic": "string"
    },
    "counterparty": {
      "type": "person",
      "referenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
      "emailAddress": "-@a(\\a)*",
      "phoneNumber": {
        "type": "landLine",
        "isPrivate": true,
        "number": "string"
      },
      "communicationLanguage": "nl-NL",
      "address": {
        "countryCode": "NL",
        "administrativeAreaCode": "ES-VI",
        "locality": "string",
        "dependentLocality": "string",
        "postalCode": "string",
        "addressLine1": "string",
        "addressLine2": "string",
        "sortingCode": "string"
      }
    },
    "referenceId": "35f2900d-73de-4850-9485-02c60d60dea8"
  }
}

Response​

The response format is the same as described in Additional repayments.

Financial states​

The financial state represents the overall financial status of a loan agreement at a specific point in time. It includes all relevant financial data, such as the agreement’s current state and last update timestamp. Refer to Financial states for further details.

Request​

PUT /financing-execution/migrations/{migration-reference-id}/staging/financial-states

Request headers and path parameters are the same as described in Additional repayments.

Provide the financial state data in the request body. For a complete request example, see the Stage financial states endpoint in the API Schemas.

Response​

The response format is the same as described in Additional repayments.

Invoices​

An invoice represents a payment obligation for a loan agreement, including the total amount due and individual transaction line items such as principal, interest, and fees.

Request​

PUT /financing-execution/migrations/{migration-reference-id}/staging/invoices

Request headers and path parameters are the same as described in Additional repayments.

Provide the data you want to upload in the request body. For example:

{
  "referenceId": "c3f4f2b3-7fed-4fed-b529-183482d775a5",
  "tenantFormattedReferenceId": "INV-2026-000123",
  "agreementReferenceId": "35f2900d-73de-4850-9485-02c60d60dea8",
  "paymentDueDate": "2026-03-15",
  "invoiceDate": "2026-02-15",
  "totalInvoiceAmount": {
    "amount": 1547.85,
    "currency": "EUR"
  },
  "transactions": [
    {
      "referenceId": "TXN-2026-001-001",
      "amount": { "amount": 1200.00, "currency": "EUR" },
      "interestDate": "2026-01-01",
      "description": "Monthly loan repayment - Principal"
    },
    {
      "referenceId": "TXN-2026-001-002",
      "amount": { "amount": 89.50, "currency": "EUR" },
      "interestDate": "2026-01-01",
      "description": "Monthly loan repayment - Interest"
    },
    {
      "referenceId": "TXN-2026-001-003",
      "amount": { "amount": 258.35, "currency": "EUR" },
      "interestDate": "2026-01-15",
      "description": "Administrative fee"
    }
  ]
}

Response​

The response format is the same as described in Additional repayments.

Manage staged data​

You can retrieve staged migration data and delete specific staged records by reference ID. For more information, see Manage staged migration data.

Next steps​

Once you've loaded your data into the staging area, you can do the following: