Data import

Create a dataset, load your existing customers into it, and keep them up to date, so that spektr processes can screen, score and monitor them.

At a glance

Before you start

• An API key. Every call sends a workspace-scoped x-api-key header. Each environment has its own API host.
• Your customer identifier. Each record needs a stable, unique reference, such as your own customer ID. It is how spektr matches a record when you import it again.
• The fields you hold. Decide which fields you send and their types before you create the dataset.

Onboarding processes create their own dataset, so you don't need this guide to onboard new customers. Use this guide to bring an existing book of customers into spektr. See your datasets.

How it works

A dataset is a schema: a name and a type for each field. Records you import into it become customer records, each with a spektrId that spektr generates and the reference you supply (optional). Importing a record whose reference already exists updates that record; anything else creates a new one.

An import stores records and nothing more. It runs no screening or scoring. To process the records, attach a monitoring process to the dataset, start a process with POST /v3/execution, or let an event orchestration process react to customer_created.

Integrate

The example imports two individual customers into a dataset called Retail customers: Anna Lind (c_2001) and Erik Berg (c_2002).

1. Create the dataset

Server-side

Send a name and a dataType map from field name to type. The types are string, number, boolean, date, country, stringList and file.

POST https://ingest.spektr.com/v1/data
x-api-key: <key>
idempotency-key: 0b7a4c1e-2f3d-4e5a-9b8c-7d6e5f4a3b2c

{
  "name": "Retail customers",
  "dataType": {
    "reference": "string",
    "first_name": "string",
    "last_name": "string",
    "date_of_birth": "date",
    "nationality": "country",
    "email": "string",
    "risk_level": "string",
    "passport": "file"
  }
}

The 201 response returns the dataset ID, a 24-character hexadecimal string:

{ "datasetId": "686660b573833dea357e8701" }

reference, if you declare it, must be a string. spektr also creates a companion dataset named Retail customers - child, which holds related people and companies.

Reference: create a dataset

2. Import the records

Server-side

Send up to 5,000 records per call in data, and say how existing records are updated with upsertMethod.

PUT https://ingest.spektr.com/v1/data/686660b573833dea357e8701
x-api-key: <key>
idempotency-key: 4d3c2b1a-0f9e-4d8c-8b7a-6f5e4d3c2b1a

{
  "upsertMethod": "merge",
  "data": [
    {
      "reference": "c_2001",
      "first_name": "Anna",
      "last_name": "Lind",
      "date_of_birth": "1985-03-14",
      "nationality": "SE",
      "email": "[email protected]",
      "risk_level": "LOW",
      "passport": "anna-lind-passport.pdf"
    },
    {
      "reference": "c_2002",
      "first_name": "Erik",
      "last_name": "Berg",
      "date_of_birth": "1979-11-02",
      "nationality": "SE",
      "risk_level": "MEDIUM"
    }
  ]
}

The response lists one entry per record, in the order you sent them. Store each spektrId next to your reference.

{
  "data": [
    {
      "spektrId": "6867b8db50ffa326d667ac71",
      "files": [
        {
          "file": "passport",
          "url": "https://…",
          "fields": { "key": "…", "Policy": "…" }
        }
      ]
    },
    { "spektrId": "6867b8db50ffa326d667ac72", "files": [] }
  ]
}

New records start with status pending. A record imported again keeps its spektrId and its status. Records with first_name, last_name, full_name or date_of_birth are typed as individuals, and records with fields such as company_name or company_number as companies.

Reference: import records

3. Upload files

Server-side

Only for records with a file field.

Each entry in files has a presigned url and fields. POST the file to url as multipart/form-data, with every entry in fields before the file itself. The URL expires after one hour; import the record again to get a new one.

The file is stored as a document on the record, under the filename you sent.

Reference: Submitting files

4. Check a record

GET https://ingest.spektr.com/v1/record/reference/c_2001
x-api-key: <key>

Or by spektrId:

GET https://ingest.spektr.com/v1/record/6867b8db50ffa326d667ac72
x-api-key: <key>

The record also appears in the dashboard, under the dataset.

Reference: fetch a record by spektrId or fetch a record by reference

5. Run processes on the records

Dashboard or server-side

• On a schedule. Attach a monitoring process to the dataset. See Customer monitoring.
• Once, now. Call POST /v3/execution with a published processId and the records' references or spektrIds.
• On every new record. Build an event orchestration process triggered by customer_created.

Reference: run a process, event orchestration processes

6. Keep the records current

Import changed records again with the same reference, using "upsertMethod": "merge" to send only the fields that changed. A new record emits customer_created, and a changed one emits customer_record_changed with each changed field in changes[]. These events are not bound to a process, so subscribe to them with an event-only delivery rule. See Webhooks.

To change one record's status, for example to archived when a customer leaves, use PATCH /v2/record/{id}?type=reference.

Reference: update a record

Rules that prevent rework

• A reference is unique across the workspace, cannot be root, and a repeat within one batch or a clash with another record fails the request with 409 duplicate_reference.
• Send upsertMethod every time. The default, overwrite, replaces the record with the fields you send and removes any you leave out. merge changes only the fields you send.
• Send only known fields. A field that is neither in the dataset schema nor a workspace field fails the whole request with 400. One invalid record rejects the batch, and nothing is stored.
• Match the types. A number field needs a JSON number, and a number sent to any other type is rejected. Send dates as strings, stringList values as arrays of strings, and countries as ISO 3166-1 alpha-2 codes.
• Retry safely. Send an idempotency-key with each call. A repeat with the same key and body replays the first response instead of importing again.
• Delete with care. DELETE /v1/data/{datasetId} only deletes an empty dataset that no process uses. It fails with 400 while the dataset holds customer records, and with 409 while a process uses it. The API cannot delete records.

Test it

Sandbox and Test environments in the workspace clone processes, fields and dataset schemas from Live, but never records. Create a dataset with Sandbox keys and endpoint, import a handful of records, and check them with GET /v1/record/reference/{reference}. Import the same records again with one changed field, and check that the spektrId stays the same and that customer_record_changed arrives. Imported records cannot be deleted through the API, so keep test imports in Sandbox or Test.

Go-live checklist

• Every record carries a stable, unique reference (optional).
• Every import sends upsertMethod and an idempotency-key.
• Batches stay at or under 5,000 records.
• You store each spektrId next to its reference.
• Records with files upload every file to its presigned URL.
• A process is attached or started for the records you want screened.
• Live keys are configured separately from Sandbox.

Next steps

• Monitor the customers you imported. See Customer monitoring.
• Get results into your systems. Every event and its payload is in the webhook events reference.
• Full API. Every call above is in the API reference.

Behaviour described here reflects the platform on 5 October 2026.