External Data

The External Step lets a Spektr process wait for data from your own system before continuing. Use it when a workflow step depends on information collected outside Spektr.

The node works as a simple contract between Spektr and your integration:

Spektr pauses the process and tells your integration which fields are expected.
Your integration sends a JSON payload for those fields.
Spektr validates the payload, stores the accepted values, and continues the process.

How It Works

When the process reaches an External Step, the execution becomes pending until the required data is submitted or the optional timeout is reached. Your application can use the execution token to check whether the current step is an External Step and retrieve the expected payload schema.

Configure The Step

In the External Step configuration, define the fields your integration must provide. Each expected field maps one value from the submitted JSON payload to one Spektr workspace field. A JSON sample schema is generated in the step UI.

Expected Field Properties

Property	Required	Description
`spektrDataField`	Yes	The Spektr field key that receives the validated value.
`type`	Yes	The expected value type. See `Supported Field Types`.
`required`	Yes	Whether the payload must include a non-empty value for this field.

The API reads each submitted value from the top-level key matching spektrDataField.

For example, if the node expects:

[
  {
    "spektrDataField": "company_name",
    "type": "string",
    "required": true
  },
  {
    "spektrDataField": "country_of_incorporation",
    "type": "country",
    "required": true
  }
]

your integration should submit:

{
  "company_name": "External Company Ltd",
  "country_of_incorporation": "RO"
}

API Flow

Use this flow when your application starts the onboarding process and controls the integration lifecycle. All requests require your Spektr API key.

1. Start The Onboarding Process

curl -X POST "https://<api-host>/v2/public/actions/processId/<processId>/workspaceId/<workspaceId>" \
  -H "x-api-key: <api-key>" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: <uuid>" \
  -d '{
    "data": {
      "reference": "customer-123"
    }
  }'

The response includes an execution token. Store this token; it is used to check the current step and submit data.

{
  "token": "<execution-token>",
  "availableLanguages": ["en-GB"],
  "spektrId": "<customer-id>"
}

2. Check The Current Step

curl -X GET "https://<api-host>/v2/public/actions/<execution-token>" \
  -H "x-api-key: <api-key>"

When the process is waiting for external data, the response contains node.type: "externalData".

{
  "node": {
    "type": "externalData",
    "nodeId": "<node-id>",
    "submitUrl": "public/actions/<execution-token>",
    "expectedFields": [
      {
        "spektrDataField": "company_name",
        "type": "string",
        "required": true
      },
      {
        "spektrDataField": "country_of_incorporation",
        "type": "country",
        "required": true
      }
    ],
    "expiresAt": 1767225600000
  },
  "execution": {
    "id": "<execution-id>",
    "status": "pending",
    "token": "<execution-token>",
    "currentStep": 1
  }
}

Use expectedFields as the contract for the payload you submit. The platform also shows a generated example payload in the node configuration dialog.

3. Submit External Data

Use the submitUrl from the current-step response. The v3 endpoint is recommended for new integrations.

curl -X POST "https://<api-host>/v3/public/actions/<execution-token>" \
  -H "x-api-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "External Company Ltd",
    "country_of_incorporation": "RO"
  }'

A successful submission returns:

{
  "status": "completed"
}

After Spektr accepts the payload, the process continues with the submitted values available as Spektr data fields. Spektr also sets external_data_failure to false, so downstream steps can distinguish a successful submission from a timeout.

Hosted Frontend Flow

If you use Spektr's hosted frontend, the end user may move through the process without your application polling the current step. In this setup, your application should listen for Spektr activity events and react when the process reaches an External Step.

When Spektr starts waiting for external data, it emits an external_data_waiting event. Treat this event as the trigger to collect or calculate the required data, then submit the payload to the public action endpoint.

sequenceDiagram
  participant User as End user
  participant Frontend as Spektr hosted frontend
  participant API as Spektr API
  participant App as Your application

  User->>Frontend: Completes hosted steps
  Frontend->>API: Process reaches External Step
  API-->>App: external_data_waiting event
  App->>App: Prepare required data
  App->>API: Submit external data
  API-->>Frontend: Process can continue
  Frontend-->>User: Continue hosted journey

An external_data_waiting event includes the External Step schema and identifiers that help you correlate the event with your customer or case.

{
  "type": "external_data_waiting",
  "workspaceId": "<workspace-id>",
  "spektrId": "<customer-id>",
  "createdAt": 1767225600000,
  "eventData": {
    "stepType": "externalData",
    "stepId": "<node-id>",
    "stepTitle": "Wait for company payload",
    "contextId": "<execution-id>",
    "processId": "<process-id>",
    "processName": "KYB onboarding",
    "processType": "onboarding",
    "reference": "customer-123",
    "expectedFields": [
      {
        "spektrDataField": "company_name",
        "type": "string",
        "required": true
      },
      {
        "spektrDataField": "country_of_incorporation",
        "type": "country",
        "required": true
      }
    ],
    "expiresAt": 1767227400000
  }
}

Use eventData.expectedFields as the payload contract, just like the current-step API response. Use eventData.reference or spektrId to match the event to your own customer record.

After receiving the event, submit the external data:

curl -X POST "https://<api-host>/v3/public/actions/<execution-token>" \
  -H "x-api-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "External Company Ltd",
    "country_of_incorporation": "DK"
  }'

If your integration starts the process, store the returned execution token and correlate it with the reference or
spektrId. If the hosted journey is started another way, make sure your integration has a reliable way to resolve the
pending execution before using the event-driven flow.

Supported Field Types

Type	Accepted value
`string`	Non-empty string. Leading and trailing whitespace is trimmed.
`number`	Number.
`date`	ISO string date.
`country`	ISO Alpha-2 country code, for example `DK`.
`boolean`	JSON boolean.
`stringList`	Array of non-empty strings.
`country`	Array of valid ISO Alpha-2 country codes.
`currency`	Array of valid ISO 4217 currency codes`[ "DKK", "SEK", "EUR"] or an array of non-empty strings.
`object`	JSON object. Arrays are not accepted.

Required list fields must contain at least one item. Optional fields may be omitted or sent as null; omitted optional fields are ignored.

Validation Errors

If the payload does not match the node configuration, the API returns 400 Bad Request.

{
  "errorCode": "BAD_REQUEST_ERROR",
  "message": "External data payload validation failed",
  "details": {
    "missingRequiredFields": ["company_name"],
    "typeErrors": [
      "Field 'country_of_incorporation' expected a valid ISO Alpha-2 country code. Received: \"Denmark\""
    ]
  }
}

Common causes:

the process is not currently waiting on an External Step
a required field is missing, null, or an empty list
a value exists but does not match the configured type
the External Step timeout has already elapsed

Timeout Behavior

Timeouts are optional. When a timeout is configured, the current-step response includes expiresAt as a Unix timestamp in milliseconds.

If no valid payload is submitted before the timeout, Spektr continues the process and sets external_data_failure to true. Use this field in downstream routing, scoring, or review steps to decide what should happen next.

Generated Events

Spektr records events for each important External Step state change. These events appear in the activity history and can also be used by integrations when event delivery is configured.

Event	When it is generated	How to use it
`external_data_waiting`	The process reaches the External Step and starts waiting for data.	Trigger your integration to prepare and submit the required payload.
`external_data_received`	Spektr accepts a valid external data payload.	Confirm that the process received the expected data.
`external_data_timed_out`	The External Step reaches its configured timeout before valid data is submitted.	Audit the timeout and route downstream using `external_data_failure`.

Activity History

Spektr records activity when:

the process starts waiting for external data
valid external data is received
the External Step times out

Integration Checklist

Add the External Step to an onboarding process.
Configure at least one expected field.
For API-driven journeys, start an onboarding execution and store the returned token.
For hosted frontend journeys, listen for the external_data_waiting event.
Use the expected fields from the current-step response or event payload as the submission contract.
Submit a JSON payload to POST /v3/public/actions/:token.
Use external_data_failure downstream to handle timeout or missing-data scenarios.