Load collateral data

Overview

Upload collateral data to the staging area as a JSON stream. Each record must include references to related counterparties and agreements through counterpartyReferenceIds and agreementReferenceIds.

The API provides separate endpoints for collateral and collateral object. Use the appropriate endpoint based on the type of data you are uploading.

Refer to the Migrate Collaterals API for detailed schemas.

Load data to staging

Collateral

Collateral refers to an asset or item that has been accepted by the lender as security in a loan agreement with the borrower. Refer to Collaterals for further details.

To upload collateral data, use the following endpoint.

Request

PUT /collateral-management/migrations/{migration-reference-id}/staging/collaterals

Request headers:

Name	Description	Required
Content-Type	Specifies the request body format. Two supported values are application/jsonl and application/json-seq.	Yes
Accept	Specifies 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:

Name	Description	Required
migration-reference-id	The migration reference ID obtained from Step 1.	Yes

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

{
  "referenceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "mortgage",
  "collateralDefinitionCode": "DUMMY",
  "isPerfect": true,
  "agreementReferenceIds": ["a1b2c3d4-e5f6-1234-5678-9abcdef01234"],
  "counterpartyReferenceIds": ["b2c3d4e5-f6a1-2345-6789-abcdef012345"],
  "registeredMortgageEntries": [
    {
      "isAlreadyPledged": false,
      "rank": 1,
      "collateralObjectReferenceId": "7c694f16-f240-42e8-9f27-0bc463d3df97"
    }
  ]
}

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.

Collateral object

A collateral object represents one or more real assets currently owned by the borrower. These assets are used to verify ownership and legal status, and to assess their value for loan approval and risk evaluation. Refer to Collateral objects for further details.

To upload collateral data, use the following endpoint:

Request

PUT /collateral-management/migrations/{migration-reference-id}/staging/collateral-objects

Request headers:

Name	Description	Required
Content-Type	Specifies the request body format. Two supported values are application/jsonl and application/json-seq.	Yes
Accept	Specifies 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:

Name	Description	Required
migration-reference-id	The migration reference ID obtained from Step 1.	Yes

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

{
    "type": "landObject",
    "referenceId": "b5090c25-cbbc-4770-912a-1b1588a1b902",
    "tenantFormattedReferenceId": "tenantId",
    "definitionCode": "code",
    "address": {
        "referenceId": "1f4d3d62-680f-4d4b-935e-74f27386fffb",
        "type": "Main",
        "countryCode": "XX",
        "administrativeAreaCode": "AU-TAS",
        "locality": "Deventer",
        "dependentLocality": null,
        "postalCode": "7411 HW",
        "sortingCode": null,
        "addressLine1": "Singel 25 A",
        "addressLine2": null
    },
    "valuations": [        
        {
            "referenceId": "0e117a20-ddf0-4cdc-b080-f2affbe71471",
            "valuationDate": "2025-01-01",
            "marketValues": [
            ],
            "valuer": {
                "referenceId": "fee678fb-df39-45b5-8802-7cdacf0a9faf",
                "address": {
                    "referenceId": "1f4d3d62-680f-4d4b-935e-74f27386fffb",
                    "type": "Main",
                    "countryCode": "NL",
                    "administrativeAreaCode": null,
                    "locality": "Deventer",
                    "dependentLocality": null,
                    "postalCode": "7411 HW",
                    "sortingCode": null,
                    "addressLine1": "Singel 25 A",
                    "addressLine2": null
                }
            }
        }
    ]
}

Response

The response format is the same as described in Collateral.

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 to staging, you can check the migration status and progress. Refer to Monitor migration and manage jobs.
• Proceed to Step 3. Validate data in the staging area to verify your staged data.