Spektr Orchestration API API

openapi: 3.2.0
info:
  title: Spektr Action Orchestration 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:
    InputAttributeObject:
      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
        type:
          type: string
          description: Type of the input
          example: text
        placeholder:
          type: string
          description: Placeholder text for the field
          example: Acme Inc.
        internalId:
          type: string
          description: Internal ID for the field
          example: ''
        maxLength:
          type: number
          description: Max length of the input value (characters)
          example: 100
      required:
      - label
      - name
      - type
      - placeholder
      - internalId
      - maxLength
    StringField:
      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: regex
            value: ^[a-zA-Z0-9 ]+$
            message: Only alphanumeric characters and spaces 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: text
            placeholder: Acme Inc.
            internalId: ''
            label: Company name
            name: Company name
            maxLength: 100
          allOf:
          - $ref: '#/components/schemas/InputAttributeObject'
        dataType:
          type: string
          description: The data type of the field
          example: string
          enum:
          - string
        config:
          description: The field configuration including the value
          example:
            spektrDataField: company_name
            value: Test APS
          allOf:
          - $ref: '#/components/schemas/StringFieldConfig'
      required:
      - type
      - validation
      - attributes
      - dataType
      - config
    SubmitV3CompletedResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - completed
          description: Submission completed immediately (no files to upload)
      required:
      - status
    SubmitBankId:
      type: object
      properties:
        params:
          type: string
          description: The results parameters
      required:
      - params
    AgeValidation:
      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: age
          enum:
          - age
        minimumAge:
          type: number
          description: Minimum age required
          example: 18
        maximumAge:
          type: number
          description: Maximum age allowed
          example: 65
      required:
      - message
      - type
    ExternalDataExpectedFieldSchema:
      type: object
      properties:
        spektrDataField:
          type: string
          description: The Spektr data field that will be populated from the submitted payload
          example: company_name
        type:
          type: string
          description: The expected data type for the submitted value
          enum:
          - string
          - number
          - date
          - country
          - boolean
          - stringList
          - countryList
          - currencyList
          - object
          example: string
        required:
          type: boolean
          description: Whether this field must be included in the submit payload
          example: true
      required:
      - spektrDataField
      - type
      - required
    DataValidationError:
      type: object
      properties:
        message:
          type: string
          description: The error message
        errorCode:
          type: string
          enum:
          - invalid_request_body
          description: The error code
      required:
      - message
      - errorCode
    MitIDVendor:
      type: object
      properties:
        type:
          type: string
          description: The step type
          example: mitId
        params:
          type: string
          description: The parameters required to run a mitId session
      required:
      - type
      - params
    ConfirmCompletedResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - completed
          description: All files verified, execution resumed
      required:
      - status
    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
    SubmitHitHorizon:
      type: object
      properties:
        searchTerm:
          type: string
          description: The search term for company search
          example: spektr
        searchIdentifier:
          type: string
          description: The identifier of the company that is chosen
          example: H-DK02xxxxxxx
      required:
      - searchTerm
      - searchIdentifier
    SubmitMitId:
      type: object
      properties:
        params:
          type: string
          description: The results parameters
      required:
      - params
    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
    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
    DateAttributeObject:
      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
        type:
          type: string
          description: Type of the input
          example: text
        placeholder:
          type: string
          description: Placeholder text for the field
          example: Acme Inc.
        internalId:
          type: string
          description: Internal ID for the field
          example: ''
        maxLength:
          type: number
          description: Max length of the input value (characters)
          example: 100
        minDate:
          type: string
          description: Minimum allowed date for date fields
          example: '1900-01-01'
        maxDate:
          type: string
          description: Maximum allowed date for date fields
          example: '2100-12-31'
        maxDaysInPast:
          type: number
          description: Maximum number of days in the past allowed for date fields
          example: 3650
        maxDaysInFuture:
          type: number
          description: Maximum number of days in the future allowed for date fields
          example: 30
      req

# --- 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