Asynchronous Bulk Import API

Introduction

The Bulk Import API allows you to create a large number of objects in a single, asynchronous job.

It follows a "partial success" model: the system will attempt to process every object in your request, creating valid ones and logging errors for invalid ones.

When the job is complete, you will receive a summary and a link to a detailed report outlining the status of each individual object.

Import Workflow

Step 1: Initialize an Import Job

You start the process by making a POST request containing the array of objects you wish to import. The server will validate the request format, queue a background job, and respond immediately.

• Endpoint: POST /api/v1/idm/{firm-id}/[objects]/import

• Request Body

  The request body must be a JSON array of objects, where each object represents a record to be created.

  The array can contain a maximum of 1000 objects per request.

• Example Request

  JSON

  [
    {
      "name": "Object A (Valid)",
      "value": 123
    },
    {
      "name": "Object B (Invalid)",
      "value": null
    },
    {
      "name": "Object C (Valid)",
      "value": 789
    }
  ]

• Response (200 Success): The server responds instantly with a requestId that you will use to track the import's progress.

  {
    "requestId": "import-8f7g6h5e-4d3c-2b1a-9098-f7e6d5c4b3a2"
  }

Step 2: Check Job Status

Periodically poll the status endpoint using the requestId from the previous step. We recommend polling at a reasonable interval (e.g., every 15-30 seconds).

• Endpoint: GET /api/v1/request/{request-id}

• Possible Statuses:

  • Pending: the request is received but the execution is not yet started
  • InProgress: the request is executing
  • Completed: the request is completed
  • Failed: the request is failed

• Example InProgressing Response

  JSON

  {
    "requestId": "import-8f7g6h5e-4d3c-2b1a-9098-f7e6d5c4b3a2",
    "status": "InProgress",
    "progress": {
      "total": 3,
      "processed": 2
    }
  }

• Example Completed Response:

  JSON

  {
    "requestId": "import-8f7g6h5e-4d3c-2b1a-9098-f7e6d5c4b3a2",
    "status": "Completed",
    "result": {
      "summary": {
        "total": 3,
        "created": 2,
        "failed": 1
      },
      "reportUrl": "..."
    }
  }

Step 3: Download the Import Report

Use the reportUrl from the completed job status response to download a detailed CSV report. This is a secure, pre-signed URL that will expire automatically after 7 days.

The report will contain the status of each object from your original request.

inputIndex,status,objectId,failureReason,inputPreview
1,created,obj_1A2b3C,,{"name":"Object A (Valid)",...}
2,failed,,"The 'value' field cannot be null.",{"name":"Object B (Invalid)",...}
3,created,obj_4D5e6F,,{"name":"Object C (Valid)",...}

Limits