Workflow API

SEON's Workflow API enables you to initialize and manage verification workflows that combine document verification, selfie checks, fraud detection, and AML screening in a single orchestrated flow. Use this endpoint to start a workflow session and receive a token for the frontend SDK.

Good to know

• The workflowId must be a valid UUID of an active workflow created in the Admin Panel (Admin Panel / Workflows).
• The user_id field is always required in the inputs object to identify the end user.
• Additional required inputs depend on your workflow configuration (e.g., email if Email check is enabled, phone_number if Phone check is enabled).
• All SEON API requests are case-sensitive. Please follow the formatting below to avoid errors.
• IP address is auto-captured from the end user's browser if not provided in the request.
• Device fingerprinting is handled automatically by the SDK when Device check is enabled.
• All Fraud API input fields are accepted. The Workflow API supports the complete set of fields from the Fraud API, plus additional orchestration-specific fields (e.g., reference_image, eKYC identifiers). See the Fraud API documentation for the full list of available fields.

Warning: Security - Never expose your API key in frontend code. Always initialize workflows from your backend server.

If you are using our US or APAC Transaction Processing Environment please contact SEON for access and use the correct endpoint:

US
https://api.us-east-1-main.seon.io/orchestration-api/v1/init-workflow

APAC
https://api.ap-southeast-1-main.seon.io/orchestration-api/v1/init-workflow

The endpoint returns JSON structured response.

JSON Attributes		Type	Expand all
executionId		string (UUID)
token		string

The workflow-link endpoint provides an alternative to the standard Workflow API, allowing you to initiate workflow executions by generating shareable verification links instead of integrating with the SDK. This approach is ideal when you want to send verification URLs directly to end users via email, SMS, or other channels without the need of a frontend SDK integration.

Good to know

• This endpoint returns error responses identical to the Workflow API, and shares its request schema with three additional optional attributes specific to workflow links — expiresIn, completedUrl and incompleteUrl (see Request below).
• Webhook notifications and callbacks work in the same way as with the standard Workflow API endpoint.
• The returned redirectUrl can be shared directly with end users — no frontend SDK integration required.
• Workflow links are valid for 7 days by default. If the user does not complete the verification within this period, the execution status becomes EXPIRED.
• Each API call creates a new workflow execution. To send verification links to multiple users, make separate API calls for each user.
• You can return users to your own application when the flow ends by supplying completedUrl and incompleteUrl — see Redirecting users back to your application.

If you are using our US or APAC Transaction Processing Environment please contact SEON for access and use the correct endpoint:

US
https://api.us-east-1-main.seon.io/orchestration-api/v1/workflow-link

APAC
https://api.ap-southeast-1-main.seon.io/orchestration-api/v1/workflow-link

Request

The headers and all input fields are identical to the Workflow API — refer to that section for the complete schema. Workflow links additionally accept the following optional attributes:

Your request should look the following when using redirect URLs:

{
  "workflowId": "3f8c1e42-9b7a-4c25-8d61-0a2f5e7b9c14",
  "inputs": {
    "user_id": "user-12345",
    "email": "user@example.com"
  },
  "expiresIn": 172800,
  "completedUrl": "https://app.example.com/verification/complete",
  "incompleteUrl": "https://app.example.com/verification/incomplete"
}

Use Cases

The Workflow Link endpoint is ideal for scenarios where you want to send verification links directly to end users without requiring frontend SDK integration:

Comparison with the init-workflow endpoint

SEON Hosted Verification Flow

When using the Workflow Link endpoint, the redirectUrl directs end users to a SEON-hosted Orchestration SDK frontend. This means:

• No SDK integration required: You don't need to embed or configure the SEON SDK in your application.
• Fully managed user experience: SEON hosts and maintains the verification UI, ensuring it's always up-to-date with the latest features and security updates.
• Cross-platform compatibility: The hosted verification flow works on any desktop, mobile or tablet device with a modern web browser.

This approach is ideal when you want to offload the verification experience entirely to SEON, rather than embedding the SDK directly into your own web or mobile application.

Redirecting users back to your application

By default, users remain on the SEON-hosted result screen when the verification journey ends. If you supply redirect URLs when creating the link, users are returned to your application automatically instead.

Both attributes are optional and independent — you can supply either, both, or neither. Each must be a valid absolute URL, and we recommend HTTPS.

Landing pages must not infer the verification outcome. There is a single completedUrl for all finished results, so Approve, Review and Reject all return the user to the same page. This is deliberate: the decision is never exposed to the browser, where it could be read or manipulated by the end user. Design your landing page as a neutral confirmation — for example "Thanks, we're reviewing your submission" — and reflect the actual status only after you receive the workflow_execution_finished webhook.

The endpoint returns a JSON structured response.

JSON Attributes	Type	Required	Expand all
executionId	string (UUID)	yes
redirectUrl	string	yes

Overview

The Workflow Execution API returns the result of one identity verification workflow execution on demand. A single request gives you the outcome of the execution and every check it performed. It also returns the data read off the submitted documents, and download links for the captured media.

Use it when the completion webhook is not enough. You can request the same execution as many times as you need, for as long as the data sits inside your data retention period.

Note: Prerequisites: a SEON license key with access to the Orchestration API, and the workflow execution ID of the execution you want to read.

How it works

Results become available once an execution reaches a final status. Four rules govern what a request returns:

• While the execution is in progress, status is PENDING and checks is null.
• Each entry in checks is one check performed by the workflow. Only the result object matching checkType is populated, and every other result field is null.
• Media download links are presigned and expire 1 hour after you request them. Download the file, or call the endpoint again for fresh links.
• Results stay available for the length of your data retention period. After a purge, the execution and its check statuses are still returned, and every result object, extracted data field and media link is null.

The webhook SEON sends when an execution finishes carries the same data object as this endpoint, so one parser handles both.

Choosing between the webhook and this API

The webhook remains the way to learn that an execution finished. This API covers four cases after that moment:

• A webhook was missed, or your service was down when it arrived.
• A media link expired and you need the image again.
• An agent opens a case days later and wants the document data on screen.
• You reconcile your own records against the execution as SEON holds it.

Regional endpoints

Call the region your account is provisioned in. An execution created in one region is not readable from another.

To use the US or APAC Transaction Processing Environment, contact SEON for access.

Authentication

Send your license key in the X-Api-Key header, the same key you use for init-workflow. No other authentication is required.

X-Api-Key: YOUR_LICENSE_KEY
Content-Type: application/json

Every request is scoped to the account behind the key. Requesting an execution ID that belongs to another account returns 404 rather than 403, so a wrong ID and someone else's ID are indistinguishable.

Getting the execution ID

Every request is keyed on the workflow execution ID, a UUID generated when a verification flow starts. You get it two ways:

• Synchronously, in the response to POST /v1/init-workflow, as data.executionId.
• Asynchronously, in the completion webhook, as data.id.

An id that is not a valid UUID returns 400.

Get workflow execution details

GET /v1/workflow-execution/{id}

The endpoint returns everything SEON holds about the execution: the outcome, every check performed, all sub-check results, the extracted document data, and the media links.

Get captured media only

GET /v1/workflow-execution/{id}?mediaOnly=true

Setting mediaOnly to true returns a reduced payload. Each entry in checks carries only checkType and capturedMedia, with no check results and no extracted data.

This is the fastest way to pull images and video. Use it where the media is all you need. FRAUD_API entries are excluded from the response, because that check captures no media.

Response envelope

Every response, success or failure, uses the same three keys. success is the boolean outcome of the request, and data carries the execution. On a failed request, error carries a code and a message, and data is an empty object. Check success before reading data, so a failed request does not read as an execution with no checks.

{ "success": true,  "error": {}, "data": { } }{ "success": false, "error": { "code": "...", "message": "..." }, "data": {} }

Top-level fields

The data object describes the execution itself, with the per-check detail nested under checks.

Execution status

status reports where the execution ended. Nothing under checks is populated until it reaches a final value.

React to the webhook where you can, and poll a PENDING execution where you cannot.

Level of Identity Proofing result

The loip object is present only when Level of Identity Proofing (LoIP) was evaluated for the execution.

LoIP flag has a limited availability across eIDAS customers. Contact your implementation team for more information

Check entries

checks holds one object per check, sorted oldest first by startedAt. Which result object is populated depends on checkType.

Check entry status fields

Every check entry carries the same status and timing fields, whatever its type.

Check entry identifiers

Each check entry also carries the identifiers of the session and of the user you verified.

Result objects per check type

Each check type populates one result object and, for document and address checks, one extracted-data object.

Sub-check fields share one set of values: PASS, FAIL, REVIEW or NOT_PERFORMED. Each result object also carries an overallResult of APPROVED, REJECTED, FAIL, REVIEW, ABANDONED or RETRY_REQUIRED.

Extracted document data

documentCheckExtractedData is what SEON read off the identity document. A field appears only where it exists on that document type, so treat every one as optional. The personal details it carries are printed below.

Extracted document details

The same object carries the document's own identifiers and dates, and the chip data where a chip was read. Country and state codes follow the International Organization for Standardization (ISO) standards named in the table.

Document chip data

Where both are present, the chip data in rfidData is the stronger source. It is signed by the issuing authority, while the top-level fields are read optically from the printed surface.

The object carries its own fullName, givenNames, surname, dateOfBirth, documentNumber, expiryDate, nationality, issuingCountry, gender, placeOfBirth and address.

Extracted address data

proofOfAddressExtractedData covers the address document submitted to a proof of address check.

extractedAddress also appears, as a deprecated alias of address. Read address.

Document check sub-checks

documentCheckResult reports the authenticity and consistency of the identity document. Alongside overallResult it carries the authenticity sub-checks:

• matchCheckResult, logicCheckResult, formatCheckResult and mrzCheckResult.
• barcodeAnomalyCheckResult, suspiciousDataCheckResult and dataIntegrityCheckResult.
• screenCheckResult, photocopyCheckResult, handPresenceCheckResult and photoForgeryCheckResult.
• securityFeaturesCheckResult, documentValidityCheckResult and imageQualityCheckResult.
• iadCheckResult for injection attack detection, with reason codes in iadRejectionReason.

It also carries the comparisons against data you supplied: ageVerificationCheckResult, nameMatchCheckResult, dateOfBirthCheckResult, postalCodeCheckResult and stateCheckResult.

verificationMethod is OCR or EID. On an electronic identity (eID) check, eidProvider, eidLevelOfAssurance and missingClaims are populated, and are null otherwise. Where NFC ran, nfcVerificationResult holds the chip authentication outcome.

Selfie check sub-checks

selfieVerificationResult reports the liveness and face match outcome of a selfie check. Alongside overallResult it carries:

• livenessCheckResult and faceMatchingResult.
• iadCheckResult, with reason codes in iadRejectionReason.
• dfdCheckResult for deep fake detection, with detail in dfdStatusDetail.
• mfdCheckResult for multiple face detection, with detail in mfdStatusDetail.

Proof of address sub-checks

proofOfAddressCheckResult reports the outcome of the address document checks. Alongside overallResult it always carries five sub-checks:

• addressDocumentCheckResult, on the document itself.
• addressDocumentMustNotBeExpiredCheckResult, on the document age.
• addressValidationCheckResult and fullAddressCheckResult, on the address.
• nameMatchCheckResult, against the name you supplied.

Where they are configured on the workflow, it also carries tamperValidationCheckResult and contentValidationCheckResult.

Credit card check sub-checks

creditCardVerificationResult reports the card data and the card checks. The full card number and the card verification value (CVV) never reach SEON, so they are never returned.

Alongside overallResult it carries:

• The card data maskedPan, bin, lastFour, cardholderName, expiryDate, issuingNetwork and iban.
• The checks luhnCheckResult, nameMatchCheckResult and expiryDateCheckResult.
• The image checks screenCheckResultFront, photocopyCheckResultFront, handPresenceCheckResultFront and their Back counterparts.
• A nameVerification object with inputName, extractedName, matchScore and matchResult.

Evidence collection sub-checks

evidenceCollectionCheckResult reports the outcome of a custom evidence collection step. Alongside overallResult it carries selectedDocumentType and a files array.

Each entry in files has tamperingCheckResult, nameMatchCheckResult, documentType, captureMethod and an extractedFields object. The shape of extractedFields depends on the document, and covers transactions, daily balances, vehicle categories, key information and usage details.

Captured media fields

Each capturedMedia object holds presigned download links. Only the fields relevant to that check type, and to media actually captured, are present. A single-sided document has documentFront and no documentBack.

Note: Links expire 1 hour after you request them. Do not cache or store a link. Store the execution ID instead, and call the endpoint again for fresh links.

Responses after data is purged

Once an execution falls outside your data retention period, dataPurgedAt is set and the response changes shape rather than failing. You can still prove that an execution happened and what it decided, without SEON holding the personal data behind it.

A full request returns id, status, workflow, createdAt, dataPurgedAt and loip. Each check entry keeps only checkType, status, sessionId, startedAt and finishedAt, and every result object, extracted data field and media link is null.

With mediaOnly set to true, checks is an empty array.

Error responses

A failed request returns the code and message in error.

A 503 is worth retrying. It usually means the verification data could not be assembled in time, not that the execution is gone.

Rate limits

Requests count against the queries-per-second limit of your account, the same budget as the rest of the SEON API. Exceeding it returns HTTP 429. Back off and retry rather than looping.

Requests are cheap and repeatable. For a high-volume flow, react to the webhook, then call this endpoint when you need the detail or fresh media. Do not poll every execution on a timer.

You can integrate SEON's Orchestration module directly into a web app by using our JavaScript SDK. Please use our npm-hosted package to ensure you always load the latest available version.

Visit the SEON Orchestration SDK npm page to see the latest version and its changelog.

Tip: The Orchestration SDK handles document verification, selfie checks, device fingerprinting, and more in a single orchestrated flow. Initialize workflows from your backend, then pass the token to this frontend SDK.

1. Install the SDK via npm or yarn and import it into your application.
2. Initialize a workflow from your backend using the Workflow API described above to get a token.
3. Call SeonOrchestration.start(config) with the token to launch the verification flow.
4. Listen to events (completed, error, cancelled) to handle the verification result.
5. Use webhooks or the Admin Panel to access detailed verification results and captured media.

Note: The Orchestration SDK combines document verification, selfie verification, device fingerprinting, and fraud checks into a unified flow. The specific checks performed depend on your workflow configuration in the Admin Panel.

Installation

npm / yarn

npm install @seontechnologies/seon-orchestration
# or
yarn add @seontechnologies/seon-orchestration

Import

import { SeonOrchestration } from '@seontechnologies/seon-orchestration';

Prerequisites

• Node.js >=20.0.0, npm >=7.0.0
• SEON account with workflow access
• API key (obtain from Admin Panel / Settings / API Keys)
• At least one workflow created (Admin Panel / Workflows)

Browser Compatibility

Configuration parameters

To configure the Orchestration SDK, you need to create a config object and pass it to SeonOrchestration.start(config).

JSON Attributes	Type	Required	Expand all
token	string	yes
language	string	no
theme	object	no
renderingMode	string	no
containerId	string	conditional

Core Methods

Events

Completion Types: success, pending, failed, unknown
 

Error Codes

Error codes received via the error event:

SDK Exceptions

Exceptions thrown by SeonOrchestration.start() (catch via try/catch):

Example: Minimal Integration

javascript
import { SeonOrchestration } from '@seontechnologies/seon-orchestration';
// 1. Get token from YOUR backend (keeps API keys secure)
const { token } = await fetch('/api/init-verification', { method: 'POST' })
 .then(r => r.json());
// 2. Start verification
await SeonOrchestration.start({ token, language: 'en' });

Example: Full Configuration

// On page load: Set up event listeners
SeonOrchestration.on('completed', (status) => {
 console.log('Verification completed:', status);
});
SeonOrchestration.on('error', (errorCode) => {
 console.error('Verification error:', errorCode);
});
const config = {
 token: 'eyJhbGciOiJIUzI1NiIs...',  // From your backend
 language: 'en',
 renderingMode: 'fullscreen',
 theme: {
   light: {
     baseTextOnLight: '#1a1a1a',
     baseTextOnDark: '#ffffff',
     baseAccent: '#0066cc',
     baseOnAccent: '#ffffff',
     logoUrl: 'https://example.com/logo-dark.svg'
   },
   dark: {
     baseTextOnLight: '#e5e5e5',
     baseTextOnDark: '#1a1a1a',
     baseAccent: '#4d9fff',
     baseOnAccent: '#000000',
     logoUrl: 'https://example.com/logo-light.svg'
   },
   fontFamily: 'Inter',
   fontUrl: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap',
   fontWeight: '500'
 }
};
await SeonOrchestration.start(config);

Example: Inline Rendering

<!-- In your HTML -->
<div id="verification-container" style="width: 100%; min-height: 600px;"></div>

await SeonOrchestration.start({
 token,
 renderingMode: 'inline',
 containerId: 'verification-container'
});

Example: React Integration

import React, { useEffect, useState } from 'react';
import { SeonOrchestration, CompletionTypes, ErrorCodes } from '@seontechnologies/seon-orchestration';
export function VerificationComponent({ userId, onComplete, onError }) {
 const [isLoading, setIsLoading] = useState(false);
 const [error, setError] = useState(null);
 useEffect(() => {
   const handleCompleted = (status: CompletionTypes) => {
     onComplete(status);
   };
   const handleError = (errorCode: ErrorCodes) => {
     setError(`Error: ${errorCode}`);
     onError(errorCode);
   };
   const handleClosed = () => setIsLoading(false);
   SeonOrchestration.on('completed', handleCompleted);
   SeonOrchestration.on('error', handleError);
   SeonOrchestration.on('closed', handleClosed);
   return () => {
     SeonOrchestration.off('completed', handleCompleted);
     SeonOrchestration.off('error', handleError);
     SeonOrchestration.off('closed', handleClosed);
   };
 }, [onComplete, onError]);
 const startVerification = async () => {
   setIsLoading(true);
   setError(null);
   try {
     const response = await fetch('/api/init-verification', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
       body: JSON.stringify({ userId }),
     });
     const { token } = await response.json();
     await SeonOrchestration.start({ token, language: 'en' });
   } catch (err) {
     setError(err.message);
   } finally {
     setIsLoading(false);
   }
 };
 return (
   <div>
     {error && <div style={{ color: 'red' }}>{error}</div>}
     <button onClick={startVerification} disabled={isLoading}>
       {isLoading ? 'Starting...' : 'Start Verification'}
     </button>
   </div>
 );
}

Warning: Security - Never expose your API key in frontend code. Always initialize workflows from your backend server using the Workflow API, then pass the returned token to this SDK.