Data Import

Initiate a data import

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.

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

Request body

agencyIdstring uuid

Agency to import into. Optional; defaults to the caller's agency and, when given, must be the caller's agency.

providerstring uuid required

ID of the import provider, from getDataImportProviders. Must exist and be enabled.

paramsobject

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).

multiSetboolean

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.

archiveEntriesobject

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.

Example request

{
  "agencyId": "8d0f6a52-1c3e-4b7a-9f25-6e4d3c2b1a90",
  "provider": "5a7c9e21-4b3d-4f8a-8e6c-2d1b0a9f8e74",
  "params": {
    "subProvider": "c4e2a7b9-0d1f-4a6e-b8c3-9f7e5d3b1a26",
    "validityMonth": "2026-09"
  }
}

Response

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

uploadUrlstring

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.

Example response

{
  "record": {
    "agencyId": "8d0f6a52-1c3e-4b7a-9f25-6e4d3c2b1a90",
    "id": "3f2b8c1e-7d4a-4e9b-9c61-0a5d2e8f4b17",
    "provider": "5a7c9e21-4b3d-4f8a-8e6c-2d1b0a9f8e74",
    "subProvider": "c4e2a7b9-0d1f-4a6e-b8c3-9f7e5d3b1a26",
    "status": "PROCESSED",
    "revertedBy": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "revertedAt": "2026-10-12T08:45:00Z"
  },
  "uploadUrl": "https://surense.data-import.files.s3.eu-west-1.amazonaws.com/0b7e4c2a-5f1d-4e8b-a3c9-6d2f1e0b9a47/3f2b8c1e-7d4a-4e9b-9c61-0a5d2e8f4b17?X-Amz-Expires=900&X-Amz-Signature=...",
  "records": [
    {
      "record": {
        "agencyId": "8d0f6a52-1c3e-4b7a-9f25-6e4d3c2b1a90",
        "id": "3f2b8c1e-7d4a-4e9b-9c61-0a5d2e8f4b17",
        "provider": "5a7c9e21-4b3d-4f8a-8e6c-2d1b0a9f8e74",
        "subProvider": "c4e2a7b9-0d1f-4a6e-b8c3-9f7e5d3b1a26",
        "status": "PROCESSED",
        "revertedBy": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
        "revertedAt": "2026-10-12T08:45:00Z"
      },
      "uploadUrl": "https://surense.data-import.files.s3.eu-west-1.amazonaws.com/0b7e4c2a-5f1d-4e8b-a3c9-6d2f1e0b9a47/3f2b8c1e-7d4a-4e9b-9c61-0a5d2e8f4b17?X-Amz-Expires=900&X-Amz-Signature=..."
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.