---
title: "Initiate a data import"
method: POST
path: "/data-import/initiate"
tags: ["Data Import"]
---

# Initiate a data import

`POST /data-import/initiate`

## Request

- Base URL: `https://api.surense.com/api/v1`
- URL: `https://api.surense.com/api/v1/data-import/initiate`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://api.surense.com/oauth/token`

First step of an import. Validates the declared files against the selected provider (enabled provider/sub-provider, accepted extensions, single vs multiple files, required files, required `customerManager` / `validityMonth` parameters), creates a data import record in status `INITIATED` and returns a pre-signed S3 `uploadUrl`, valid for **15 minutes**. The client must then `PUT` all the declared files as a single ZIP archive (`Content-Type: application/zip`) to that URL and call `startDataImport`.

**Single set (default, `multiSet` absent or false):** all files must form one set; the response holds `record` and `uploadUrl`. Validation errors are returned immediately (400). The request is rejected with 403 if an import uploaded by the same user is still running and was created less than 60 minutes ago.

**Multi set (`multiSet: true`):** for providers that auto-detect their sub-provider, files are split into sets (e.g. one per agent or file type) and one record is created per set; the response holds `records`, each with its own `uploadUrl`. A set that fails validation does not fail the request: its record is saved directly as `FAILED` with a `failureReason`, has no `uploadUrl`, and a data-import-record-failed event is published.

**Authorization:** any authenticated user. Imports are always created for the caller's own agency: `agencyId`, when given, must be the caller's agency. The `customerManager` parameter must be a user of that agency unless the import targets a specific customer (`customerId`).

**Errors:** 400 for an unknown/disabled provider or sub-provider, empty or unnamed files, files the provider does not accept, missing or invalid parameters (a `validityMonth` must be a past month, format `YYYY-MM`, year 2000 or later); 403 for another agency or a still-running import.

## Request body

- InitiateRequest: Request to initiate a data import: the provider, the files that will be uploaded as one ZIP archive, and provider-specific parameters.
  - `agencyId` string, uuid: Agency to import into. Optional; defaults to the caller's agency and, when given, must be the caller's agency.
  - `provider` string, uuid, required: ID of the import provider, from `getDataImportProviders`. Must exist and be enabled.
  - `files` DataImportFile[], required: The files that will be uploaded (at least one). Each needs a non-blank `fileName` (its extension must be accepted by the provider) and optionally its `fileSize` in bytes.
    - `fileName` string, required
    - `fileSize` integer
  - `flattenFiles` DataImportFile[]: Optional flattened list of the files contained in the uploaded archives, used to check the files required by the sub-provider. Ignored for files listed in `archiveEntries`.
    - `fileName` string, required
    - `fileSize` integer
  - `params` object: Provider-specific parameters. Known keys: `subProvider` (sub-provider UUID; required when the provider has sub-providers and does not auto-detect them), `validityMonth` (`YYYY-MM`, a past month from 2000 on; required when the provider has `validityMonthRequired`), `customerManager` (UUID of a user of the import agency; required when the provider has `managerRequired`), `customerId` (customer UUID, for a customer-specific import), `password` (password of protected files).
  - `multiSet` boolean: When `true`, files are split into sets (for providers that auto-detect their sub-provider) and one record is created per set, returned in `records`. Absent or `false`: a single record.
  - `archiveEntries` object: Content of the uploaded archive files, keyed by the archive's `fileName` in `files`; used to detect the sub-provider and check the required files of each set.

## Response `200`

The created record(s) and the pre-signed upload URL(s)

- InitiateResponse: Result of an initiate request: `record` and `uploadUrl` for a single-set import, or `records` for a multi-set import.
  - `record` DataImportRecordValue: A data import: one set of files imported with a provider into an agency, with its status and results.
    - `tenantId` string, uuid
    - `agencyId` string, uuid: Agency the data is imported into.
    - `createdDate` string, date-time
    - `createdBy` string, uuid
    - `creatorName` string
    - `lastModifiedDate` string, date-time
    - `lastModifiedBy` string, uuid
    - `version` integer
    - `id` string, uuid: Data import record ID.
    - `provider` string, uuid: ID of the import provider.
    - `subProvider` string, uuid: ID of the resolved sub-provider, when the provider has sub-providers.
    - `files` DataImportFile[]: The files of the import (names and sizes).
      - `fileName` string, required
      - `fileSize` integer
    - `params` object: The provider-specific parameters given at initiation (e.g. `subProvider`, `validityMonth`, `customerManager`).
    - `status` 'INITIATED' | 'UPLOADED' | 'PROCESSING' | 'PROCESSED' | 'FAILED': Import status: `INITIATED` (waiting for upload), `UPLOADED` (queued), `PROCESSING`, `PROCESSED` or `FAILED`.
    - `results` DataImportResults[]: Processing results per file group: counters in `params` (e.g. `customerCount`, `productCount`) and info/warning/error messages.
      - `files` DataImportFile[]
        - `fileName` string, required
        - `fileSize` integer
      - `params` object
      - `infos` string[]
      - `warnings` string[]
      - `errors` string[]
    - `failureReason` string: Why the import failed, when `status` is `FAILED`.
    - `revertedBy` string, uuid: ID of the user who reverted the import, if reverted.
    - `revertedAt` string, date-time: When the import was reverted, if reverted.
  - `uploadUrl` string: Pre-signed S3 URL, valid for 15 minutes, to `PUT` the files to as a single ZIP archive (`Content-Type: application/zip`). Single-set import only.
  - `records` InitiatedRecord[]: One entry per detected file set (multi-set import only; null for a single-set import).
    - `record` DataImportRecordValue: A data import: one set of files imported with a provider into an agency, with its status and results.
      - `tenantId` string, uuid
      - `agencyId` string, uuid: Agency the data is imported into.
      - `createdDate` string, date-time
      - `createdBy` string, uuid
      - `creatorName` string
      - `lastModifiedDate` string, date-time
      - `lastModifiedBy` string, uuid
      - `version` integer
      - `id` string, uuid: Data import record ID.
      - `provider` string, uuid: ID of the import provider.
      - `subProvider` string, uuid: ID of the resolved sub-provider, when the provider has sub-providers.
      - `files` DataImportFile[]: The files of the import (names and sizes).
        - `fileName` string, required
        - `fileSize` integer
      - `params` object: The provider-specific parameters given at initiation (e.g. `subProvider`, `validityMonth`, `customerManager`).
      - `status` 'INITIATED' | 'UPLOADED' | 'PROCESSING' | 'PROCESSED' | 'FAILED': Import status: `INITIATED` (waiting for upload), `UPLOADED` (queued), `PROCESSING`, `PROCESSED` or `FAILED`.
      - `results` DataImportResults[]: Processing results per file group: counters in `params` (e.g. `customerCount`, `productCount`) and info/warning/error messages.
        - `files` DataImportFile[]
          - `fileName` string, required
          - `fileSize` integer
        - `params` object
        - `infos` string[]
        - `warnings` string[]
        - `errors` string[]
      - `failureReason` string: Why the import failed, when `status` is `FAILED`.
      - `revertedBy` string, uuid: ID of the user who reverted the import, if reverted.
      - `revertedAt` string, date-time: When the import was reverted, if reverted.
    - `uploadUrl` string: Pre-signed S3 URL, valid for 15 minutes, to `PUT` the set's files to as a single ZIP archive (`Content-Type: application/zip`). Null when the record was rejected (`FAILED`).

## Other responses

- `400`: Invalid request: unknown or disabled provider, unaccepted or unrecognized files, missing or invalid parameters
- `403`: `agencyId` is not the caller's agency, or a previous import of the caller is still running

---

[API](https://skmtc.dev/surense/apis/data-import-api.md) - [All operations](https://skmtc.dev/surense/apis/data-import-api/llms.txt) - [OpenAPI document](https://skmtc.dev/surense/apis/data-import-api/revisions/cf169afb2d5b?raw)