Data import

What is the Data Import?

Data Import allows you to ingest external data into DatAscend by uploading files (Excel/CSV) through a REST API. This is useful for bulk data loading, migrating from other systems, or integrating with external data sources. The API provides endpoints to start import jobs, track their progress, and handle validation errors.

Structure of a Data Import request

Headers

Field	Type	Description	Required
Authorization	string	Bearer token for authentication.	Yes
Content-Type	string	Must be multipart/form-data.	Yes
domain	string	Target domain for imported records.	Yes

Path parameters

Field	Type	Description	Required
version	string	Current application version.	Yes
entity	string	Name or ID of the entity to import.	Yes

Endpoints for managing Data Import

Create a data import from a file

Request body

Follows the multipart/form-data format with the following fields:

Field	Type	Required	Description
type	string	Yes	The type of the file, either csv or xlsx
file	string($binary)	Yes	The file to upload, sent as binary data
mapping	object	Yes	Map of file column indexes (starting from 1) to entity property names
locale	string	No	User locale used to parse dates
timezoneOffset	number	No	Timezone offset in minutes from UTC

POST /api/v1/entities/:entity/import

Response example:

{
  "status": 200,
  "error": false,
  "message": "string",
  "errors": [
    {}
  ],
  "data": {
    // Unique identifiers for the import job
    "id": "A0123456-7890-ABCD-EF00-00000000000",
    "entity": "E0123456-7890-ABCD-EF00-00000000000",

    // Status of the import job.
    "duration": "10 seconds",
    "status": "QUEUED",
    "type": "IMPORT",
    "progress": 100,
    "payload": {},
    "output": {},

    // Timestamps for job lifecycle events.
    "jobEnd": "2020-01-01T00:00:10.000Z",
    "jobStart": "2020-01-01T00:00:00.000Z",
    "createdAt": "2022-01-01T00:00:00.000Z",
    "updatedAt": "2022-01-01T00:00:00.000Z",
    "lastHeartbeat": "2022-01-01T00:00:05.000Z",
  },
  "pagination": { <Pagination> }
}

Monitoring and behavior

• The import is processed asynchronously; use the background job status endpoint /api/v1/job/:id to check progress.
• On successful completion, jobStatus may become completed, with importedCount and failedCount values.
• Validation errors and failed rows are reported in job details.

Get a single Job by ID

This endpoint allows you to retrieve the status and details of a specific import job.

GET /api/v1/job/{id}

Path parameters

Name	Type	Description	Required
id	string	The Job ID value (e.g., 24a55348-e5c9-48b7-b377-07db2f1df368)	Yes

Response

Returns a Job object with details about the import process.

Response example:

{
  "errors": [],
  "status": 200,
  "error": false,
  "message": "string",
  "data": {
    "id": "132e4567-e89b-12d3-a456-426614174000",
    "entity": "132e4567-e89b-12d3-a456-426614174000",
    "duration": "10 seconds",
    "status": "QUEUED",
    "type": "IMPORT",
    "progress": 100,
    "payload": {},
    "output": {},
    "jobEnd": "2022-01-05T16:27:16.560Z",
    "jobStart": "2022-01-05T16:27:16.560Z",
    "createdAt": "2022-01-05T16:27:16.560Z",
    "updatedAt": "2022-01-05T16:27:16.560Z",
    "lastHeartbeat": "2022-01-05T16:27:16.560Z"
  }
}