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 it to start a workflow session and receive a token for the frontend SDK, to read the results of an execution on demand, and to record your own decision on it.

For more context on how to begin your API integration check the Introduction section or the Integration Guide.

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.

Common Workflow Scenarios

Request

Request attributes

Code samples

curl -X POST "https://api.seon.io/orchestration-api/v1/init-workflow" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SEON_API_KEY" \
  -d '{
    "workflowId": "550e8400-e29b-41d4-a716-446655440000",
    "inputs": {
      "user_id": "user-12345",
      "email": "john.doe@example.com",
      "phone_number": "+14155551234"
    }
  }'

import os
import requests

response = requests.post(
    "https://api.seon.io/orchestration-api/v1/init-workflow",
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["SEON_API_KEY"],
    },
    json={
        "workflowId": "550e8400-e29b-41d4-a716-446655440000",
        "inputs": {
            "user_id": "user-12345",
            "email": "john.doe@example.com",
            "phone_number": "+14155551234",
        },
    },
)

data = response.json()["data"]
print(data["token"], data["executionId"])

const response = await fetch("https://api.seon.io/orchestration-api/v1/init-workflow", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.SEON_API_KEY,
  },
  body: JSON.stringify({
    workflowId: "550e8400-e29b-41d4-a716-446655440000",
    inputs: {
      user_id: "user-12345",
      email: "john.doe@example.com",
      phone_number: "+14155551234",
    },
  }),
});

const { data } = await response.json();
console.log(data.token, data.executionId);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class InitWorkflow {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("SEON_API_KEY");

        String payload = """
            {
                "workflowId": "550e8400-e29b-41d4-a716-446655440000",
                "inputs": {
                    "user_id": "user-12345",
                    "email": "john.doe@example.com",
                    "phone_number": "+14155551234"
                }
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.seon.io/orchestration-api/v1/init-workflow"))
            .header("Content-Type", "application/json")
            .header("x-api-key", apiKey)
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}

<?php
$apiKey = getenv('SEON_API_KEY');

$payload = [
    'workflowId' => '550e8400-e29b-41d4-a716-446655440000',
    'inputs' => [
        'user_id' => 'user-12345',
        'email' => 'john.doe@example.com',
        'phone_number' => '+14155551234',
    ],
];

$ch = curl_init('https://api.seon.io/orchestration-api/v1/init-workflow');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        "x-api-key: {$apiKey}",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true)['data'];
echo $data['token'] . "\n";
echo $data['executionId'] . "\n";

Response

The endpoint returns a JSON structured response.

{
  "data": {
    "executionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Error Responses

The init-workflow and workflow-link endpoints return the same error responses. The execution endpoints below list their own.

Retrieving workflow execution results

Once an execution has started you can read its current state and, once it has finished, the result of every check it ran. The object returned in data is the same object the workflow webhooks deliver, so use this endpoint to fetch results on demand — after a missed webhook, to download captured media later, or to reconcile — rather than as your primary way of receiving results.

curl "https://api.seon.io/orchestration-api/v1/workflow-execution/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "x-api-key: $SEON_API_KEY"

import os
import requests

execution_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.get(
    f"https://api.seon.io/orchestration-api/v1/workflow-execution/{execution_id}",
    headers={"x-api-key": os.environ["SEON_API_KEY"]},
)

data = response.json()["data"]
print(data["status"], [c["checkType"] for c in data["checks"] or []])

const executionId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
  `https://api.seon.io/orchestration-api/v1/workflow-execution/${executionId}`,
  { headers: { "x-api-key": process.env.SEON_API_KEY } },
);

const { data } = await response.json();
console.log(data.status, data.checks?.map((c) => c.checkType));

Workflow execution object

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "APPROVED",
    "workflow": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "KYC Onboarding Flow"
    },
    "createdAt": "2026-08-20T09:12:31.000Z",
    "dataPurgedAt": null,
    "loip": {
      "result": "BASELINE",
      "evaluatedAt": "2026-08-20T09:16:02.369Z"
    },
    "checks": [
      {
        "checkType": "DOCUMENT_CHECK",
        "status": "APPROVED",
        "sessionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "transactionId": null,
        "startedAt": "2026-08-20T09:12:40.000Z",
        "finishedAt": "2026-08-20T09:14:02.000Z",
        "platform": "WEB",
        "duplicatesFound": false,
        "statusDetail": null,
        "referenceId": null,
        "email": "john.doe@example.com",
        "phoneNumber": null,
        "userId": "user-12345",
        "documentCheckResult": {
          "overallResult": "APPROVED",
          "documentValidityCheckResult": "PASS",
          "imageQualityCheckResult": "PASS"
        },
        "documentCheckExtractedData": {
          "fullName": "JOHN DOE",
          "birthDate": "1990-05-15",
          "documentType": "PASSPORT",
          "country": "US"
        },
        "selfieVerificationResult": null,
        "proofOfAddressCheckResult": null,
        "proofOfAddressExtractedData": null,
        "creditCardVerificationResult": null,
        "evidenceCollectionCheckResult": null,
        "capturedMedia": null
      },
      {
        "checkType": "SELFIE_CHECK",
        "status": "APPROVED",
        "sessionId": "9b2f1c3e-5d4a-4f6b-8c7d-0e1f2a3b4c5d",
        "transactionId": null,
        "startedAt": "2026-08-20T09:14:05.000Z",
        "finishedAt": "2026-08-20T09:15:10.000Z",
        "platform": "WEB",
        "duplicatesFound": false,
        "statusDetail": null,
        "referenceId": null,
        "email": "john.doe@example.com",
        "phoneNumber": null,
        "userId": "user-12345",
        "documentCheckResult": null,
        "documentCheckExtractedData": null,
        "selfieVerificationResult": {
          "overallResult": "APPROVED",
          "livenessCheckResult": "PASS",
          "faceMatchingResult": "PASS"
        },
        "proofOfAddressCheckResult": null,
        "proofOfAddressExtractedData": null,
        "creditCardVerificationResult": null,
        "evidenceCollectionCheckResult": null,
        "capturedMedia": null
      },
      {
        "checkType": "FRAUD_API",
        "status": "APPROVED",
        "sessionId": null,
        "transactionId": "98db9a56b2e3",
        "startedAt": "2026-08-20T09:15:11.000Z",
        "finishedAt": "2026-08-20T09:15:12.000Z",
        "platform": null,
        "duplicatesFound": null,
        "statusDetail": null,
        "referenceId": null,
        "email": "john.doe@example.com",
        "phoneNumber": "+14155551234",
        "userId": "user-12345",
        "documentCheckResult": null,
        "documentCheckExtractedData": null,
        "selfieVerificationResult": null,
        "proofOfAddressCheckResult": null,
        "proofOfAddressExtractedData": null,
        "creditCardVerificationResult": null,
        "evidenceCollectionCheckResult": null,
        "capturedMedia": null
      }
    ]
  }
}

Good to know about execution results

• status is PENDING while the user is still in the flow. checks is null until the execution finishes.
• A negative outcome is DECLINED, both for the execution and for individual checks.
• Identity checks (DOCUMENT_CHECK, SELFIE_CHECK, POA_CHECK, CREDIT_CARD_CHECK, EVIDENCE_COLLECTION) carry a sessionId; the FRAUD_API check carries a transactionId instead. Result objects such as documentCheckResult use the same field-level schema as the identity verification session webhook.
• loip is present only when your workflow evaluates a Level of Identity Proofing, and unmetConditions appears only when the result is NONE.
• After personal data is purged under your retention settings, dataPurgedAt is set and each check keeps only its type, status and timestamps; result and extracted-data fields are null and mediaOnly returns an empty list.

Recording a decision

If you make your own final decision on a verification — for example after a manual review on your side — record it on the execution so that the Admin Panel, your webhooks and later reads all reflect it.

{
  "status": "APPROVED",
  "comment": "Approved after manual review of the address document."
}

curl -X PATCH "https://api.seon.io/orchestration-api/v1/workflow-execution/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SEON_API_KEY" \
  -d '{ "status": "APPROVED", "comment": "Approved after manual review." }'

import os
import requests

execution_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.patch(
    f"https://api.seon.io/orchestration-api/v1/workflow-execution/{execution_id}",
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["SEON_API_KEY"],
    },
    json={"status": "APPROVED", "comment": "Approved after manual review."},
)
response.raise_for_status()

const executionId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
await fetch(`https://api.seon.io/orchestration-api/v1/workflow-execution/${executionId}`, {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.SEON_API_KEY,
  },
  body: JSON.stringify({ status: "APPROVED", comment: "Approved after manual review." }),
});

• Decisions can be recorded only on finished executions (APPROVED, REVIEW, DECLINED or EXPIRED), not while one is PENDING or after an ERROR.
• A recorded decision triggers a workflow_execution_updated webhook carrying the new status.
• The response data is an empty object; a 200 status means the decision was stored.

Workflow webhooks

Webhooks are the authoritative way to receive results. Subscribe to the events below in Admin Panel / Settings / Webhooks; for endpoint setup, signature verification and retries see the Webhooks reference.

Every event carries the same payload: the envelope below, with data being the workflow execution object.

Shareable Workflow Links

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 about workflow links

• 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.
• 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.

Workflow link request

The headers and all input fields are identical to the Workflow API. Workflow links additionally accept expiresIn, completedUrl and incompleteUrl:

Your request should look like 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"
}

curl -X POST "https://api.seon.io/orchestration-api/v1/workflow-link" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $SEON_API_KEY" \
  -d '{
    "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"
  }'

import os
import requests

response = requests.post(
    "https://api.seon.io/orchestration-api/v1/workflow-link",
    headers={
        "Content-Type": "application/json",
        "x-api-key": os.environ["SEON_API_KEY"],
    },
    json={
        "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",
    },
)

data = response.json()["data"]
print(data["redirectUrl"], data["executionId"])

const response = await fetch("https://api.seon.io/orchestration-api/v1/workflow-link", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.SEON_API_KEY,
  },
  body: JSON.stringify({
    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",
  }),
});

const { data } = await response.json();
console.log(data.redirectUrl, data.executionId);

<?php
$apiKey = getenv('SEON_API_KEY');

$payload = [
    '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',
];

$ch = curl_init('https://api.seon.io/orchestration-api/v1/workflow-link');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        "x-api-key: {$apiKey}",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true)['data'];
echo $data['redirectUrl'] . "\n";

Workflow link response

{
  "data": {
    "executionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "redirectUrl": "https://transfer.seonidv.com/?t=euw1:1e1f66b0-cc43-429d-ba69-096daca813fd"
  }
}

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.

Orchestration SDK

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.

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.

Installation

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

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, create a config object and pass it to SeonOrchestration.start(config).

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

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>
  );
}