Migrate data to Akkuro Lending using APIs

Overview

The Migration Assistance API allows you to migrate your data from other systems into the Akkuro Lending platform. This guide walks you through each migration step with detailed instructions and examples.

For an overview details of the Migration Assistance API, see About the Migration Assistance API.

Prerequisites

Before migrating data using the migration API, you need to make sure:

You have prepared your loan data in JSONL or JSON-seq format. See Migrated data format.
You must have valid API credentials for authentication. Contact your Customer Service representative for further assistance.

Step 1. Register migration

Initiate a new migration process by calling the endpoint below. The response returns a unique migration reference ID, which you can use to identify and track the entire migration workflow. In this step, specify the domains (also known as components in the API schema) where the data should be migrated.

Currently, the following domains are available for data migration:

Counterparties
Collaterals
Financing Execution
Financing Solution
Administrate

Request

Use the Create a migration endpoint to start a new migration. Specify the domain to which you want to migrate your data in the request body.

HTTP request: POST /migration-assistance/migrations

Request body:

{
  "components": ["Counterparties", "Collaterals", "FinancingSolutions", "FinancingExecutions", "Administrate"]
}

Response

The request returns the HTTP 201 status code showing the status of the migration.

{
  "referenceId": "f2469ee6-6f28-4bc1-8e13-2a5b97b162d6", // Migration reference ID
  "stagingStatus": "Pending",
  "importStatus": "Pending",
  "numberOfStagedEntities": 0,
  "numberOfImportedEntities": 0,
  "components": [
    {
      "component": "Counterparties",
      "stagingStatus": "Pending",
      "importStatus": "Pending",
      "numberOfStagedEntities": 0,
      "numberOfImportedEntities": 0
    },
    {
      "component": "Collaterals",
      "stagingStatus": "Pending",
      "importStatus": "Pending",
      "numberOfStagedEntities": 0,
      "numberOfImportedEntities": 0
    }
  ]
}

Note

The referenceId is the migration reference ID that will be used throughout the entire workflow to track and manage the migration process.

Step 2. Load data to the staging area

Stream your data to the isolated staging areas. The staging area serves as a temporary and secure workspace where data is stored and validated before being imported into the target environment. Using the streaming method allows you to safely upload large volumes of data without impacting target environment or risking data corruption. You have the ability to review, modify, or delete staged data before final import.

To learn how to stream your data to the Akkuro Lending domains, go to the Load data to the staging area page.

Step 3. Validate data in the staging area

Start a validation job after all data is loaded, or at intermediate stages to verify parts of the staged data. The system then performs automated validation checks on staged data. These checks verify data integrity, enforce business rules, and check cross-references between entities. It also ensures that all required fields are correctly formatted.

Each domain performs its own set of validation checks on its staged data. Cross-references between domains (for example, a collateral referencing a counterparty) are validated asynchronously through cross-component calls.

Validation must complete successfully before the import can proceed. You can run validation as many times as needed. If validation fails, the response will include detailed error messages indicating which fields are invalid and why. You can return to the staging area and correct any identified issues by updating the staged data. For further details, refer to Staging issues.

Request

To start a job that validates the staged data, use this endpoint.

HTTP request: PUT /migration-assistance/migrations/{migration-reference-id}/jobs/validate-staging

Response

If the job starts successfully, the API returns a 200 status code and a validation job ID.

"35f2900d-73de-4850-9485-02c60d60dea8"

You can check the migration and the job’s progress once your data is validated. See Monitor migration and manage jobs.

Step 4. Import data into target environment

Prerequisite

To proceed with the import, the staging status must be Completed, meaning all validation checks have passed and all issues have been resolved.

Importing the data from the staging area into the target environment makes the data officially available in the live environment on the Akkuro Lending platform.

The system coordinates the import of validated data across multiple domains in parallel and provides real-time progress updates. The process supports partial completion and automatic retries to ensure resilience.

Request

To start an import for a migration by the migration reference ID, use this endpoint.

HTTP request: PUT /migration-assistance/migrations/{migration-reference-id}/jobs/import

Response

If the job starts successfully, the API returns a 200 status code and an import job ID.

"35f2900d-73de-4850-9485-02c60d60dea8"

You can now track the migration and the job’s progress or review logs. See Monitor migration and manage jobs.

Step 5. Verify data counts

Prerequisite

To start a counts job, the import status must be Completed. Verification counts can only be run after a successful import.

After importing, start a verification counts job to compare the number of staged records against the number of imported entities. This comparison helps confirm that all data was transferred accurately and nothing was lost during the import process. See Verify migration data counts.

Monitor migration and manage jobs

During steps 2–5, you can track the migration and the job's progress or review logs. Monitoring helps ensure data integrity and provides visibility into any errors or warnings that may occur.

Monitor migration status and progress

Track the overall progress of your migration across all domains, including staging and import status for each domain type.

To get the migration status, use this endpoint.

HTTP request: GET /migration-assistance/migrations/{migration-reference-id}

Response example:

{
  "referenceId": "f2469ee6-6f28-4bc1-8e13-2a5b97b162d6",
  "stagingStatus": "Completed",
  "importStatus": "InProgress",
  "numberOfStagedEntities": 2500,
  "numberOfImportedEntities": 1200,
  "components": [
    {
      "component": "Counterparties",
      "stagingStatus": "Completed",
      "importStatus": "Completed",
      "numberOfStagedEntities": 1500,
      "numberOfImportedEntities": 1500
    },
    {
      "component": "Collaterals",
      "stagingStatus": "Completed",
      "importStatus": "InProgress",
      "numberOfStagedEntities": 1000,
      "numberOfImportedEntities": 700
    }
  ]
}

To learn more details about the status meaning, see Migration statuses.

Stream migration logs

Check the migration logs to confirm that the import completed successfully and no errors occurred. Stream logs from the migration by using Stream migration logs endpoint. See Streaming data to learn about streaming method.

HTTP request : GET /migration-assistance/migrations/{migration-reference-id}/logs/stream

(Optional) Use the following query parameters to filter log results:

Name	Description
`EntityReferenceIds`	Filters logs by entity reference IDs within the specified domains.
`Components`	Specifies the name of the domain.
`Actions`	Filters logs by action names within the migration flow.
`LogLevels`	Filters logs by severity level: `DEBUG`, `INFO`, `WARN`, or `ERROR`.
`After`	Returns logs generated after the specified timestamp. See Dates and times for format details.
`Before`	Returns logs generated before the specified timestamp. See Dates and times for format details.
`continue-from`	The index number of the first object to return in the stream. Use this parameter to resume from a specific index.

Response example:

[
    {
        "component": "Counterparties",
        "entityReferenceIds": [
            "ee61b850-5240-4978-9660-7b210f2bf70f"
        ],
        "action": "StagedEntities",
        "timestamp": "2025-10-06T08:33:33.948Z",
        "message": "Invalid StagingCounterparty with validation results: Failed to deserialize JSON to type StagingCounterparty: Required property 'surname' not found in JSON. Path '', line 1, position 1.",
        "logLevel": "WARN"
    },
    {
        "component": "Collaterals",
        "entityReferenceIds": [],
        "action": "ImportedEntities",
        "timestamp": "2025-10-07T12:50:55.075Z",
        "message": "Import for migration reference id [f2867630-31c6-46d6-9f09-a7012234eebb] and job [8cf7ad46-cca5-40cc-9ea7-25e1492af88e] has started",
        "logLevel": "INFO"
    }
]

Monitor job result and progress

Monitor the detailed results and progress of specific validation, import, and counts jobs, including error details and completion status.

To get the job result, use this endpoint.

HTTP request: GET /migration-assistance/jobs/{job-reference-id}

It requires one path parameter:

Name	Description
`job-reference-id`	The ID of a job, which can be a validation job ID, an import job ID, or a counts job ID.

Response

If the job is still running, you'll receive a 202 HTTP code with the following information:

{
  "referenceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "componentsCompleted": ["Counterparties"]
}

If validation is complete, you'll receive a 200 HTTP code with detailed validation results:

{
  "referenceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "jobType": "ValidateStaging",
  "isValid": false,
  "errors": [
    {
      "component": "Counterparties",
      "referenceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "field": "addresses[0].countryCode",
      "message": "Invalid country code: 'XX' does not exist in configuration"
    },
    {
      "component": "Collaterals",
      "referenceId": "c3d4e5f6-a1b2-3456-789a-bcdef0123456",
      "field": "counterpartyReferenceIds[0]",
      "message": "Referenced counterparty does not exist in staging or live data"
    }
  ]
}

If import is complete, you'll receive a 200 HTTP code with import statistics and any errors:

{
  "referenceId": "b2c3d4e5-f6a1-2345-6789-abcdef012345",
  "jobType": "Import",
  "status": "Completed",
  "numberOfStagedEntities": 2500,
  "numberOfImportedEntities": 2450,
  "errors": [
    {
      "component": "Collaterals",
      "message": "IMPORT_FAILED: 50 entities failed due to external service timeout"
    }
  ]
}

If a counts job is complete, you'll receive a 200 HTTP code with count results comparing staged and imported entities:

{
  "referenceId": "c4d5e6f7-a1b2-3456-789a-bcdef0123456",
  "jobType": "Counts",
  "counts": [
    {
      "type": "TotalEntity",
      "headers": ["EntityType", "Count"],
      "stagedRows": [
        ["Agreement", "1500"],
        ["Counterparty", "800"],
        ["Collateral", "600"]
      ],
      "importedRows": [
        ["Agreement", "1500"],
        ["Counterparty", "800"],
        ["Collateral", "600"]
      ]
    }
  ]
}

For a detailed description of each count type and how to interpret the results, see Verify migration data counts.

Manage the migration

Get active migration

You can check for the current active migration of your tenant without a migration reference ID. To get current active migration status, use the following request:

GET /migration-assistance/migrations/current

You will receive the following response:

{
  "stagingStatus": "Pending",
  "importStatus": "Pending",
  "numberOfStagedEntities": 1200,
  "numberOfImportedEntities": 950,
  "referenceId": "35f2900d-73de-4850-9485-02c60d60dea8",  // Migration reference ID
  "activity": "Active",
  "components": [
    {
      "stagingStatus": "Pending",
      "importStatus": "Pending",
      "numberOfStagedEntities": 1200,
      "numberOfImportedEntities": 950,
      "component": "Collaterals"
    }
  ]
}

Cancel migration

You can create a new migration only if the existing migration is in the Completed or Canceled state. If your tenant has an active migration, you must cancel it before starting a new one. To cancel an active migration, use the following request:

PUT /migration-assistance/migrations/{migration-reference-id}/cancel

Important

A canceled migration cannot be reactivated.
After a migration is canceled, you can no longer run Validate, Import, or Counts jobs for that migration.

Error handling

Refer to the Troubleshooting page for more detailed information.

Overview​

Prerequisites​

Step 1. Register migration​

Request​

Response​

Step 2. Load data to the staging area​

Step 3. Validate data in the staging area​

Request​

Response​

Step 4. Import data into target environment​

Request​

Response​

Step 5. Verify data counts​

Monitor migration and manage jobs​

Monitor migration status and progress​

Stream migration logs​

Monitor job result and progress​

Response​

Manage the migration​

Get active migration​

Cancel migration​

Error handling​

Overview

Prerequisites

Step 1. Register migration

Request

Response

Step 2. Load data to the staging area

Step 3. Validate data in the staging area

Request

Response

Step 4. Import data into target environment

Request

Response

Step 5. Verify data counts

Monitor migration and manage jobs

Monitor migration status and progress

Stream migration logs

Monitor job result and progress

Response

Manage the migration

Get active migration

Cancel migration

Error handling