openapi: 3.0.0
info:
title: Spektr Action API Orchestration API API
description: Spektr is an AI-powered compliance automation platform for financial institutions. The API manages datasets and customer record imports, process execution and onboarding orchestration, event and transaction ingestion, workspace field definitions, and webhooks for KYB/KYC onboarding, monitoring, and transaction-monitoring workflows.
version: v2.23
servers:
- url: https://ingest.spektr.com
tags:
- name: Orchestration API
paths:
/v2/public/actions/processId/{processId}/workspaceId/{workspaceId}:
post:
description: 'Creates a new onboarding session for your client. You can optionally prefill client data by submitting a payload in the request body. The response includes a session token that you can append to the onboarding URL: https://actions.spektr.com/form?token={token} to direct your client to the onboarding flow. If using a custom domain, replace actions.spektr.com with your domain.'
operationId: OrchestrationController_createOnboarding_v2
parameters:
- name: processId
required: true
in: path
description: The ID of the onboarding process template
schema:
type: string
- name: workspaceId
required: true
in: path
description: The ID of your workspace
schema:
type: string
- name: x-spektr-block-until-ready
required: false
in: header
description: Set to 'true' to have the server wait until the onboarding session is ready to accept a submission before responding, so the returned token can be submitted immediately without client-side polling. Defaults to false.
schema:
type: string
- name: idempotency-key
in: header
description: 'Optional unique key (1–255 chars) to ensure the request is processed only once. If a duplicate key is sent with the same request parameters, the original response is replayed. Replayed responses include the `idempotent-replayed: true` header.'
required: false
schema:
type: string
- name: reference
required: false
in: query
description: Your custom reference ID to track this onboarding session or it can be included in the data payload
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: Client information to prefill in the onboarding forms (optional)
properties:
first_name:
type: string
example: John
last_name:
type: string
example: Doe
email:
type: string
example: john.doe@example.com
phone_number:
type: string
example: '+1234567890'
reference:
type: string
example: '1234567890'
description: Your custom reference ID to track this onboarding session
responses:
'201':
description: Onboarding session created successfully
content:
application/json:
schema:
type: object
properties:
token:
type: string
description: Session token to be used in the onboarding URL. This token is required for all subsequent API calls related to this onboarding session.
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
availableLanguages:
type: array
description: Available translations
example:
- en-GB
- da-DK
- sv-SE
spektrId:
type: string
description: Unique ID of the customer going through the onboarding process
example: 68876fa58281009be64b58f7
'400':
description: Invalid input parameters
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Error message
example: Invalid input parameters
error:
type: string
description: Error type
example: Bad Request
statusCode:
type: number
description: HTTP status code
example: 400
'409':
description: A request with this idempotency-key is currently being processed
'422':
description: idempotency-key has already been used with different request parameters
security:
- x-api-key: []
summary: Start Onboarding
tags:
- Orchestration API
/v2/public/actions/{token}:
get:
description: "This endpoint is the second step in the onboarding process (and is continually used thereafter using polling mechanism)\n\n1. After a session is created using the InitOnboarding endpoint and a `token` is generated.\n2. Clients poll this endpoint with the `token` to retrieve the current step.\n3. Depending on the response, the client may need to collect specific data or perform certain actions\n before calling `Submit` with that data.\n When the node type is `externalData`, inspect `expectedFields` to know exactly which payload fields must be submitted to `submitUrl`.\n4. The client can then poll again to see if new steps are required or if the process has finished.\nPossible values are `running`, `pending`, `failed` or `completed`. Whenever `pending` is returned, the client should stop polling and submit the required payload according to the step type."
operationId: OrchestrationController_get_v2
parameters:
- name: token
required: true
in: path
description: Session token generated from InitOnboarding endpoint
schema:
type: string
- name: content-language
required: false
in: header
description: Language code for localized content (e.g., en-US, da-DK)
schema:
type: string
responses:
'200':
description: Process initiated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CurrentStepResponse'
'401':
description: Parameters are invalid or the Token is invalid or expired
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'500':
description: Internal error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
security:
- x-api-key: []
summary: Fetch current step
tags:
- Orchestration API
post:
deprecated: true
description: '**Deprecated.** Use `POST /v3/public/actions/{token}` instead, which supports file uploads via presigned S3 URLs and role-entity submissions in a single request (see the [guide](https://spektr.readme.io/docs/submitting-files)).'
operationId: OrchestrationController_submit_v2
parameters:
- name: token
required: true
in: path
schema:
type: string
requestBody:
required: true
description: Details needed to execute the process
content:
application/json:
schema:
oneOf:
- type: object
title: Form
description: 'A flat object where each key is a field name and each value can be one of the following types:
- string: Text values
- number: Numeric values
- boolean: true/false values
- date: Unix timestamp (milliseconds since epoch)
- stringList: Multiple string values
- entity: Array of objects representing ownership relations
**NOTE:** The UI in this documentation may only show "string" as the value type, but all types listed above are accepted. Check the examples.
The fields from the conditional type should be included in the root of the object.'
additionalProperties:
oneOf:
- type: string
description: String value
- type: number
description: Number value
- type: number
format: unix-timestamp
description: Date value as Unix timestamp (milliseconds since epoch)
title: date
- type: boolean
description: Boolean value (true/false)
- type: array
items:
type: string
description: Array of strings (for stringList fields)
- type: array
items:
type: object
properties:
first_name:
type: string
last_name:
type: string
required:
- first_name
- last_name
description: Array of objects representing entities
description: Array of objects (for ownership relations)
example:
company_name: Example Company
country_of_incorporation: SE
annual_revenue: 5000000
marketing_consent: true
incorporation_date: 1622505600
multi_select_field:
- reading
- sports
entity:
- first_name: John
last_name: Doe
- first_name: Jane
last_name: Doe
- $ref: '#/components/schemas/SubmitHitHorizon'
title: HitHorizon
- $ref: '#/components/schemas/SubmitVeriff'
title: Veriff
- $ref: '#/components/schemas/SubmitMitId'
title: MitId
- $ref: '#/components/schemas/SubmitBankId'
title: BankId
responses:
'200':
description: Data submitted successfully
'400':
description: Payload validation
content:
application/json:
schema:
$ref: '#/components/schemas/DataValidationError'
'401':
description: Parameters are invalid or the Token is invalid or expired
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'500':
description: Internal error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
security:
- x-api-key: []
summary: Submit data
tags:
- Orchestration API
/v2/public/actions/{token}/go-back:
post:
description: "Enables the process to move one step backward, if applicable.\n Use the query parameter 'reset=true' to reset the entire process to the beginning instead of going back one step.\n After calling this, the client should poll `FetchCurrentStep` to get the newly-updated step."
operationId: OrchestrationController_goBack_v2
parameters:
- name: token
required: true
in: path
description: Session token for the process
schema:
example: '1234567890'
type: string
- name: reset
required: false
in: query
description: Set to "true" to reset the entire process to the beginning instead of going back one step
schema:
example: 'true'
type: string
responses:
'201':
description: Backward step operation successful
'401':
description: Parameters are invalid or the Token is invalid or expired
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'500':
description: Internal error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
security:
- x-api-key: []
summary: Go back
tags:
- Orchestration API
/v2/public/actions/{token}/submit-files:
post:
deprecated: true
description: '**Deprecated.** Use `POST /v3/public/actions/{token}` instead, which handles file uploads as part of the standard submission via presigned S3 URLs returned in the response, followed by `POST /v3/public/actions/{token}/confirm` to finalize (see the [guide](https://spektr.readme.io/docs/submitting-files)).'
operationId: OrchestrationController_submitFiles_v2
parameters:
- name: token
required: true
in: path
schema:
type: string
requestBody:
required: true
description: List of files to generate presigned URLs for
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GeneratePresignedUrlRequest'
responses:
'201':
description: Presigned URLs generated successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/GeneratePresignedUrlResponse'
'401':
description: Parameters are invalid or the Token is invalid or expired
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'500':
description: Internal error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
security:
- x-api-key: []
summary: Generate Presigned URLs
tags:
- Orchestration API
/v3/public/actions/{token}:
post:
description: 'Submits form data with support for deferred file uploads.
**Integration Flow:**
1. Submit form data including file names for any file fields
2. If files need uploading, response includes presigned S3 URLs (status: `accepted`)
3. Upload files to S3 using the presigned URLs (multipart form POST)
4. Call `POST /:token/confirm` to verify uploads and complete submission
**Response Status:**
- `completed`: No files to upload, submission processed immediately
- `accepted`: Files need uploading, use provided presigned URLs then call /confirm
**File Upload:**
When uploading to S3, send a multipart form POST to the `url` with:
- All fields from the `fields` object as form fields
- The file content as `file` field'
operationId: OrchestrationController_submitV3_v3
parameters:
- name: token
required: true
in: path
description: Session token
schema:
type: string
- name: filledBy
required: true
in: query
description: The name of the entity that filled the form
schema:
example: John Doe
type: string
requestBody:
required: true
description: Form submission data
content:
application/json:
schema:
oneOf:
- type: object
title: Form
description: 'A flat object where each key is a field name and each value can be one of the following types:
- string: Text values
- number: Numeric values
- boolean: true/false values
- date: Unix timestamp (milliseconds since epoch)
- stringList: Multiple string values
- entity: Array of objects representing ownership relations
- file: Filename as a string (file content uploaded separately via presigned URL)
**NOTE:** The UI in this documentation may only show "string" as the value type, but all types listed above are accepted. Check the examples.
The fields from the conditional type should be included in the root of the object.'
additionalProperties:
oneOf:
- type: string
- type: number
- type: boolean
- type: array
items:
type: string
example:
company_name: Acme Corp
incorporation_date: 1622505600
document: company_registration.pdf
- $ref: '#/components/schemas/SubmitHitHorizon'
title: HitHorizon
- $ref: '#/components/schemas/SubmitVeriff'
title: Veriff
- $ref: '#/components/schemas/SubmitMitId'
title: MitId
- $ref: '#/components/schemas/SubmitBankId'
title: BankId
responses:
'200':
description: Submission completed or accepted
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/SubmitV3CompletedResponse'
title: Completed
- $ref: '#/components/schemas/SubmitV3AcceptedResponse'
title: Accepted
'400':
description: Validation error (invalid data or file type not allowed)
content:
application/json:
schema:
$ref: '#/components/schemas/DataValidationError'
'401':
description: Token is invalid or expired
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
security:
- x-api-key: []
summary: Submit form data (V3)
tags:
- Orchestration API
/v3/public/actions/{token}/confirm:
post:
description: 'Confirms that all file uploads are complete and triggers execution to resume.
**Integration Flow:**
1. Call after uploading all files from the `submitV3` response to S3
2. If all files are present in S3, returns `completed` and resumes process execution
3. If files are missing, throws 409 Conflict with new presigned URLs for retry
**Response Status:**
- `completed`: All files verified, execution resumed
- `pending` (409 Conflict): Files missing, presigned URLs provided for retry
**Retry Flow:**
If 409 is returned, upload the missing files using the new presigned URLs and call confirm again.'
operationId: OrchestrationController_confirmSubmission_v3
parameters:
- name: token
required: true
in: path
description: Session token from InitOnboarding endpoint
schema:
type: string
- name: filledBy
required: true
in: query
description: The name of the entity that filled the form
schema:
example: John Doe
type: string
responses:
'200':
description: All files verified, execution resumed
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmCompletedResponse'
'400':
description: Context status is not pending
content:
application/json:
schema:
$ref: '#/components/schemas/DataValidationError'
'401':
description: Token is invalid or expired
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'409':
description: Files missing - presigned URLs provided for retry upload
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmPendingResponse'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerError'
security:
- x-api-key: []
summary: Confirm submission
tags:
- Orchestration API
components:
schemas:
BooleanField:
type: object
properties:
type:
type: string
description: The field type (e.g., input, select, checkbox)
example: input
validation:
description: The field validation rules
example:
- type: required
value: true
message: This field is required
type: array
items:
oneOf:
- $ref: '#/components/schemas/RequiredValidation'
title: required
attributes:
description: The field attributes
example:
label: Is Active
name: Is Active
allOf:
- $ref: '#/components/schemas/BooleanAttributeObject'
dataType:
type: string
description: The data type of the field
example: boolean
enum:
- boolean
config:
description: The field configuration including the value
example:
spektrDataField: is_active
value: true
allOf:
- $ref: '#/components/schemas/BooleanFieldConfig'
required:
- type
- validation
- attributes
- dataType
- config
FileAttributeObject:
type: object
properties:
label:
type: string
description: Label for the field
example: Company name
name:
type: string
description: Name for the field
example: Company name
internalId:
type: string
description: Internal ID for the field
example: ''
accept:
type: string
description: Allowed file types
example: .pdf,.jpg,.png
maxLength:
type: number
description: Max file name length (characters)
example: 120
required:
- label
- name
- internalId
- accept
- maxLength
BankIDVendor:
type: object
properties:
type:
type: string
description: The step type
example: bankId
params:
type: string
description: The parameters required to run a bankId session
required:
- type
- params
NumberField:
type: object
properties:
type:
type: string
description: The field type (e.g., input, select, checkbox)
example: input
validation:
description: The field validation rules
example:
- type: required
value: true
message: Age is required
- type: regex
value: ^[0-9]+$
message: Only numbers are allowed
type: array
items:
oneOf:
- $ref: '#/components/schemas/RequiredValidation'
title: required
- $ref: '#/components/schemas/RegexValidation'
title: regex
attributes:
description: The field attributes
example:
type: number
placeholder: Enter your age
label: Age
name: Age
allOf:
- $ref: '#/components/schemas/InputAttributeObject'
dataType:
type: string
description: The data type of the field
example: number
enum:
- number
config:
description: The field configuration including the value
example:
spektrDataField: age
value: 30
allOf:
- $ref: '#/components/schemas/NumberFieldConfig'
required:
- type
- validation
- attributes
- dataType
- config
NumberFieldConfig:
type: object
properties:
spektrDataField:
type: string
description: The Spektr field identifier
example: company_name
value:
type: number
description: The default value of the field either prefilled or submitted previously
example: 123
required:
- spektrDataField
StringFieldConfig:
type: object
properties:
spektrDataField:
type: string
description: The Spektr field identifier
example: company_name
value:
type: string
description: The default value of the field either prefilled or submitted previously
example: Test APS
required:
- spektrDataField
CurrentStepResponse:
type: object
properties:
node:
oneOf:
- $ref: '#/components/schemas/FormResponse'
title: form
- $ref: '#/components/schemas/EndStep'
title: endStep
- $ref: '#/components/schemas/HitHorizonVendor'
title: hitHorizon
- $ref: '#/components/schemas/VeriffVendor'
title: veriff
- $ref: '#/components/schemas/MitIDVendor'
title: mitId
- $ref: '#/components/schemas/BankIDVendor'
title: bankId
- $ref: '#/components/schemas/ExternalDataPayloadSchema'
title: externalData
description: The current step of the process, determined by the session state
execution:
description: Metadata for the execution
allOf:
- $ref: '#/components/schemas/Execution'
required:
- node
- execution
UiAttributeObject:
type: object
properties:
label:
type: string
description: Label for the field
example: Company name
name:
type: string
description: Name for the field
example: Company name
content:
type: string
description: Plain text content for the UI element (HTML tags stripped)
example: This is a paragraph
contentHtml:
type: string
description: HTML content for the UI element (contains HTML tags)
example: <p>This is a <strong>paragraph</strong></p>
labelHtml:
type: string
description: HTML label for the UI element (contains HTML tags)
example: <p>This is a <strong>paragraph</strong></p>
path:
type: string
description: Image path or URL for the External Media Field
example: /images/onboarding/welcome.png or https://example.com/image.png
componentType:
type: string
description: Component type for the Call to Action Field
example: popup
enum:
- popup
- accordion
required:
- label
- name
- content
- contentHtml
- labelHtml
- path
- componentType
BooleanFieldConfig:
type: object
properties:
spektrDataField:
type: string
description: The Spektr field identifier
example: company_name
value:
type: boolean
description: The default value of the field either prefilled or submitted previously
example: true
required:
- spektrDataField
StringListField:
type: object
properties:
type:
type: string
description: The field type (e.g., input, select, checkbox)
example: input
validation:
description: The field validation rules
example:
- type: required
value: true
message: This field is required
type: array
items:
oneOf:
- $ref: '#/components/schemas/RequiredValidation'
attributes:
description: The field attributes
example:
type: select
placeholder: Select categories
label: Categories
name: Categories
allOf:
- $ref: '#/components/schemas/InputAttributeObject'
dataType:
type: string
description: The data type of the field
example: stringList
enum:
- stringList
config:
description: The field configuration including the value
example:
spektrDataField: categories
value: category1,category2
allOf:
- $ref: '#/components/schemas/StringFieldConfig'
required:
- type
- validation
- attributes
- dataType
- config
UiField:
type: object
properties:
type:
type: string
description: The field type (e.g., heading, paragraph, divider)
example: heading
dataType:
type: string
description: The data type of the field
example: ui
enum:
- ui
attributes:
description: The field attributes
example:
label: Section Title
name: section_title
content: This is a section heading
allOf:
- $ref: '#/components/schemas/UiAttributeObject'
required:
- type
- dataType
- attributes
ConditionalField:
type: object
properties:
type:
type: string
description: The field type (e.g., input, select, checkbox)
example: conditional
dataType:
type: string
description: The data type of the field
example: conditional
enum:
- conditional
config:
description: The field configuration including the value
example:
spektrDataField: condition_field
value: condition_value
allOf:
- $ref: '#/components/schemas/StringFieldConfig'
segment:
type: object
description: The segment configuration for the conditional field
output:
type: string
description: The output mode, either "show" or "hide"
enum:
- show
- hide
default: hide
form:
type: object
description: The form definition containing fields and their order
example:
fields:
field-id-1: {}
field-id-2: {}
order:
- field-id-1
- field-id-2
required:
- type
- dataType
- config
- segment
- output
- form
RequiredValidation:
type: object
properties:
message:
type: string
description: Error message for validation failure
example: This field is required
type:
type: string
description: Type of validation rule
example: required
enum:
- required
value:
type: boolean
description: Whether the field is required
example: true
required:
- message
- type
- value
SubmitV3CompletedResponse:
type: object
properties:
status:
type: string
enum:
- completed
description: Submission completed immediately (no files to upload)
required:
- status
HitHorizonVendor:
type: object
properties:
type:
# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/spektr/refs/heads/main/openapi/spektr-orchestration-api-api-openapi.yml