# spektr Documentation

> spektr API

## Guides
- [Spektr SDK](https://spektr.readme.io/docs/getting-started.md)
- [Environments](https://spektr.readme.io/docs/environments.md)
- [Submitting Data](https://spektr.readme.io/docs/submitting-files.md)
- [Idempotent requests](https://spektr.readme.io/docs/idempotent-requests.md)
- [External Data](https://spektr.readme.io/docs/external-data.md)
- [Webhook HMAC Signature Verification](https://spektr.readme.io/docs/webhook-hmac-signature-verification.md): To help you verify that webhook events are genuine and unaltered, our platform supports **HMAC-based signing**.

## API Reference
- [Authorization overview](https://spektr.readme.io/reference/welcome-to-spektr-api-documentation.md)
- [Integration overview](https://spektr.readme.io/reference/integration-overview.md)
- [Create dataset](https://spektr.readme.io/reference/dataimportcontroller_create_v1.md): Create a new dataset with a specified schema that allows to be used in processes. The schema defines the structure of data entries. Once created, the dataset becomes available in the platform and can be connected to spektr processes. Optionally, provide a "parentDatasetId" to create the dataset as a child of an existing dataset, used for related entities.
- [Import records](https://spektr.readme.io/reference/dataimportcontroller_update_v1.md): This endpoint allows clients to submit data entries for a dataset, including fields that require file uploads. When a data entry includes a file field (e.g., "passport": "file.jpg"), the API responds with a unique id for the entry and a presigned URL for uploading the file directly to AWS S3.  Upsert by "reference": records are matched to existing client records only by their "reference". If a data entry includes a "reference" that already exists in the workspace, that record is updated in place and keeps its original "spektrId"; otherwise a new record is created with a newly generated "spektrId". A "reference" must be a non-empty string, cannot be the literal value "root", and must be unique across the workspace — duplicate references (repeated within the same batch or already assigned to another record) are rejected with 409 Conflict. Entries sent without a "reference" are always created as new.
- [Delete dataset](https://spektr.readme.io/reference/dataimportcontroller_delete_v1.md): Delete a dataset from the platform.
- [Get pending process runs](https://spektr.readme.io/reference/recordcontroller_listopenloops_v1.md): Get process pending runs for a given list of spektr IDs and/or reference IDs.
- [Fetch customer record](https://spektr.readme.io/reference/recordcontroller_fetchrecord_v1.md): Fetch a customer record by its spektr ID
- [Update customer record](https://spektr.readme.io/reference/recordcontroller_updaterecord_v1.md): Update a customer record by its spektr ID
- [Update customer record v2](https://spektr.readme.io/reference/recordcontroller_updaterecordv2_v2.md): Update a customer record by its spektr ID. The ID can be a spektr ID or a reference ID. The type of the ID is specified in the type query parameter. Provide at least one of a non-empty data object, status, or a timestamp field (createdAt / updatedAt in Unix ms).
- [Fetch customer record by reference](https://spektr.readme.io/reference/recordcontroller_fetchrecordbyreference_v1.md): Fetch a customer record by a client reference.   Usage:   - on the first onboarding init request, pass the reference in the data  - whenever the spektrId is needed, use this endpoint to fetch the     record using your reference
- [Get form submits for a given record](https://spektr.readme.io/reference/recordcontroller_getclientrecordformsubmits_v1.md): Get form submits for a given record by its ID. If the ID is not found, an empty array is returned.
- [Fetch records in bulk via API](https://spektr.readme.io/reference/recordcontroller_fetchrecordsapi_v1.md): Fetch multiple customer records and return them directly in the API response. Optimized for smaller datasets. Max 5000 records at a time
- [Fetch records in bulk via S3](https://spektr.readme.io/reference/recordcontroller_fetchrecordss3_v1.md): Fetch multiple customer records and return signed URLs to download them from S3. Handles large datasets by chunking data into multiple files. Max 300,000 records at a time. Data will be split into files of max 10,000 records.
- [Create client record relations](https://spektr.readme.io/reference/recordcontroller_createclientrecordrelations_v1.md): Links two or more client records together (e.g. a company and its beneficial owners). Pass an array of relation items where each side (`from`, `to`) is identified by `spektrId` or `reference`. Each item must specify `relationRole` (one of the supported role keys such as `beneficial_owners`, `shareholders`, `ultimate_beneficial_owners`, `senior_management`, `board_of_directors`, `controlling_entities`, `subsidiaries`, `authorized_signatories`, `signatories`, `contact_info`, `person_with_significant_control`) and may include optional `data` metadata, `positions`, and a `direct` boolean. The legacy `roles` array is no longer accepted - send `relationRole` directly instead. The request is atomic: all relations are created together or none are, if any validation fails. Validation rules: both records must exist, `from` and `to` cannot be the same record, duplicate relations are rejected, and the resulting graph must remain acyclic.
- [Update client record relations](https://spektr.readme.io/reference/recordcontroller_updateclientrecordrelations_v1.md): Updates mutable fields on existing v2 client record relations identified by `(from, to, relationRole)`. Only `direct`, `positions`, and `data` may be modified; `from`, `to`, `relationRole`, `createdAt`, and `updatedAt` are immutable. The `data` field is shallow-merged with the stored value (provided keys overwrite, existing unspecified keys are preserved). Each item must include at least one of `direct`, `positions`, or `data`. All relations in the batch are verified to exist before any updates are applied; if any relation is missing, the entire request is rejected without persisting changes. Updates then run sequentially (best-effort after verification).
- [Fetch a vendor search](https://spektr.readme.io/reference/recordcontroller_getvendorsearch_v1.md): Fetch the raw, unmodified response of a single vendor search (e.g. a Kyckr lookup) by its ID. The `vendorSearchId` is the reference carried on the customer's timeline service-run events and outbound webhook payloads.
- [Execute process](https://spektr.readme.io/reference/executioncontroller_triggerprocess_v1.md): Excute a process for a list of spektr IDs. The processId can be found in the spektr platform. The spektr IDs are generated through the Import API.
- [Execute process v2](https://spektr.readme.io/reference/executioncontroller_executionv2_v2.md): Execute a process for spektr IDs and/or reference IDs. Optionally provide email input and enable token refresh on version mismatch to ensure execution uses the latest process version.
- [Execute process v3](https://spektr.readme.io/reference/executioncontroller_executionv3_v3.md): Execute a process for spektr IDs and/or reference IDs. Optionally provide email input and enable token refresh on version mismatch to ensure execution uses the latest process version.
- [Start Onboarding](https://spektr.readme.io/reference/actionticketcontroller_createonboarding_v1.md): 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.
- [List events](https://spektr.readme.io/reference/eventscontroller_list_v1.md): List all events
- [Import events](https://spektr.readme.io/reference/eventscontroller_import_v1.md): Imports a list of events
- [paymentMade schema definition](https://spektr.readme.io/reference/paymentmade-schema-definition.md): Here find the expected payload for the **paymentMade** event type.
- [Start Onboarding](https://spektr.readme.io/reference/orchestrationcontroller_createonboarding_v2.md): 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.
- [Fetch current step](https://spektr.readme.io/reference/orchestrationcontroller_get_v2.md): This endpoint is the second step in the onboarding process (and is continually used thereafter using polling mechanism)  1. After a session is created using the InitOnboarding endpoint and a `token` is generated. 2. Clients poll this endpoint with the `token` to retrieve the current step. 3. Depending on the response, the client may need to collect specific data or perform certain actions    before calling `Submit` with that data.    When the node type is `externalData`, inspect `expectedFields` to know exactly which payload fields must be submitted to `submitUrl`. 4. The client can then poll again to see if new steps are required or if the process has finished. Possible 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.
- [Submit data](https://spektr.readme.io/reference/orchestrationcontroller_submit_v2.md): **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)).
- [Go back](https://spektr.readme.io/reference/orchestrationcontroller_goback_v2.md): Enables the process to move one step backward, if applicable.      Use the query parameter 'reset=true' to reset the entire process to the beginning instead of going back one step.      After calling this, the client should poll `FetchCurrentStep` to get the newly-updated step.
- [Generate Presigned URLs](https://spektr.readme.io/reference/orchestrationcontroller_submitfiles_v2.md): **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)).
- [Submit form data (V3)](https://spektr.readme.io/reference/orchestrationcontroller_submitv3_v3.md): 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
- [Confirm submission](https://spektr.readme.io/reference/orchestrationcontroller_confirmsubmission_v3.md): 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.
- [Create workspace field](https://spektr.readme.io/reference/workspacefieldscontroller_create_v1.md): Create a new workspace field definition. Field names must be unique within the workspace.  **Flat fields** (e.g. `input`, `select`, `checkbox`, `file`) store a single scalar value per customer record (string, number, boolean, date, etc.). They do not use the `subFields` property.  **Object fields** (`type: "object"`) store structured, nested data as a JSON array of objects. They **must** include a non-empty `subFields` array defining the schema for each entry. Sub-fields can themselves be of type `object`, enabling recursive nesting.
- [List workspace fields](https://spektr.readme.io/reference/workspacefieldscontroller_getall_v1.md): Retrieve all workspace field definitions. The response includes both flat fields (scalar values) and object fields (nested structures with sub-fields).
- [Get workspace field by ID](https://spektr.readme.io/reference/workspacefieldscontroller_getbyid_v1.md): Retrieve a single workspace field definition by its ID
- [Update workspace field](https://spektr.readme.io/reference/workspacefieldscontroller_update_v1.md): Update an existing workspace field definition by its ID.
- [Delete workspace field](https://spektr.readme.io/reference/workspacefieldscontroller_delete_v1.md): Delete a workspace field definition by its ID. Protected fields cannot be deleted.
- [About webhooks](https://spektr.readme.io/reference/about-webhooks.md): Webhooks provide a way for notifications to be delivered to an external medium (e.g. HTTPS push, slack) whenever certain events occur on spektr.
- [Webhooks events and payloads](https://spektr.readme.io/reference/process-execution-webhooks.md): Process execution webhooks are used during the execution of processes you run on spektr's platform.
- [Create transaction definition](https://spektr.readme.io/reference/transactiondefinitioncontroller_create_v1-1.md): Create a new transaction definition with a nested field schema, customer link declarations, and optional non-client-scoped partitions. Leaf field values must be one of: "string", "number", "ipAddress", "date", "array". Array fields accept only primitive elements (string, number, boolean, null). Each link txPath and partition txPath must resolve to a declared leaf field (link and partition paths may not target array fields). Partition types must not collide with link types.
- [Delete transaction definition](https://spektr.readme.io/reference/transactiondefinitioncontroller_delete_v1-1.md): Delete a transaction definition by ID.
- [Ingest transaction batch](https://spektr.readme.io/reference/transactionscontroller_ingestbatch_v1-1.md): Ingests a batch of up to 1,000 transactions. Each transaction is validated against the workspace Transaction Definition for its type, linked to the relevant customer, persisted, and forwarded for transaction monitoring. Returns HTTP 200 regardless of per item outcome. Check the failed count and errors array in the response body.
- [Data Types](https://spektr.readme.io/reference/data-types.md)