V2 Integrations

Use this guide to integrate with API v2, which uses a single lifecycle for all configured products:

Your workflow configuration determines which products are executed. The integration flow remains consistent across workflows. The following elements vary by configuration:

The configured workflow name
The required uploads
The product-level statuses you evaluate

Migrating from a legacy integration?

Legacy integration guides are organized per product. v2 integrations are workflow-centric. Use this page as the main integration path, then use Product statuses to interpret each product outcome.

Before you begin

Make sure you have:

Fourthline API credentials and access to Create access token
The workflow name passed as workflow on Create workflow
The list of required uploads for your workflow, such as identity data, identity documents, reference data, or documents to sign
Handling for workflow statuses and product statuses
Optional: a webhook endpoint for status notifications

Minimum viable integration

Use this sequence to validate Sandbox end-to-end before you add webhooks, QES, or custom UI components.

Step	operationId	What you do
1	`create-access-token-v2`	Obtain a bearer token. Tokens are valid for 1 hour.
2	`create-workflow-v2`	POST `workflow` and either `partnerClientId` or `clientId`, but not both. Store `workflowId`.
3	`upload-client-data` / `upload-client-document`	Upload all mandatory data and documents required by your workflow configuration.
4	`start-workflow`	For an API-only integration, start processing. Expect 202 Accepted and an empty body. App Drop-in and Web SDK call this endpoint when capture ends.
5	`get-workflow-status`	Check the workflow status until `workflowStatus` reaches `completed`or `failed`. Review the status of each product in `products[].status`.
6	`get-report-json`	After the workflow completes, retrieve the JSON workflow report.

Optional capabilities

Add these only when your workflow requires them.

Capability	When to use	Where to continue
SDK capture	Use Fourthline-hosted SDK flows to capture client data and documents.	Create SDK session
Webhooks	Receive event-driven workflow updates without repeatedly checking workflow status.	Webhooks
QES	Your workflow includes Qualified Electronic Signature (QES).	QES in API v2
Bulk document upload	Upload multiple client documents in a single request.	Upload multiple client documents
Identity document metadata	Enrich an uploaded identity document with structured MRZ or NFC data.	Upload identity document metadata

Webhooks and reports

Webhook payloads do not include workflowStatus. After each webhook, call Get workflow status. Do not download final reports until workflowStatus is completed, unless your process explicitly allows partial data. See Workflow reports.

Choose how data is provided

Approach	When to use	What you implement
API-only	You control capture in your app or backend.	Upload client data, Upload client document, optional bulk upload
SDK	Fourthline captures data via App Drop-in, Web, or App Components.	Create SDK session after creating the workflow. Pass `validationCode` to the SDK. App Drop-in and Web SDK call Start workflow when capture ends.

You can combine approaches where your workflow allows it, for example SDK capture plus API-based supplemental uploads. Confirm supported options for your workflow with your delivery manager.

1. Authenticate

Create an access token and send it on every request in the Authorization header.

You provide your API credentials.
You receive an access_token valid for 1 hour.

API reference: Create access token

2. Create workflow

Create a workflow for the client.

Set workflow to your configured workflow name.
Provide either partnerClientId or clientId, but not both.
Use partnerClientId when onboarding a new client with your own client reference.
Use clientId for returning clients when you already have the Fourthline client id.
Store the returned workflowId and clientId.

API reference: Create workflow

After creation, workflowStatus is typically new. See Workflow statuses.

3. Upload client data and documents

Upload all mandatory inputs before you start the workflow. Required uploads depend on your workflow configuration.

Identity and reference data

Use Upload client data with the appropriate type, such as identityData or referenceDocumentData.

Files

Use Upload client document for each file, or Upload multiple client documents for batch upload.

Each upload includes metadata such as type, id, and type-specific fields like documentId or side. Accepted formats depend on the document type; see the API reference for each upload endpoint.

Document metadata after capture

If your workflow uses structured MRZ or NFC enrichment, use Upload identity document metadata for an existing documentId.

Upload before starting

Do not call Start workflow until all mandatory data and documents are uploaded. Missing inputs can result in failed workflow status or product-level invalid_data. If mandatory data is missing after start, create a new workflow unless your implementation guide explicitly supports correction for that case.

FAQ

Do I need to upload deviceMetaData in an SDK flow?

No. In an SDK flow, omit identityData.deviceMetaData. When the client opens the session, the SDK uploads model, language, region, osVersion, and sdkVersion.

Do not send model from your backend in an SDK flow. A value you send replaces the device model stored by the SDK, and the Qualified Electronic Signature device check can fail.

You can send language and region inside identityData.deviceMetaData to set the Qualified Electronic Signature SMS language. The SDK replaces both with the device locale when the session opens. Matching values do not conflict.

The SDK does not set ipAddress. Whether your backend must send it depends on your workflow configuration. Confirm that with your Fourthline delivery manager.

In an API-only integration, upload identityData.deviceMetaData with at least language, region, and model.

4. Create SDK session

Create an SDK session if you use App Drop-in (target: Mobile), Web SDK (target: Web), or App Components (target: Mobile). Skip this step for API-only integrations.

Create the SDK session before starting the workflow.

You provide workflowId and target (Mobile or Web).
You receive a single-use validationCode.
The validationCode expires after 2 hours.
Pass the code to the App Drop-in, Web SDK, or App Components.

API reference: Create SDK session

If the client abandons the flow, create a new SDK session. Closing the app or browser invalidates the code.

FAQ

Does API v2 require an SDK update?

We recommend using the latest Fourthline SDK version to ensure compatibility with API v2 workflows and benefit from the latest features, improvements, and bug fixes.

5. Start workflow

For an API-only integration, call Start workflow after all mandatory uploads are complete.

You provide workflowId.
Workflows cannot be restarted.

API reference: Start workflow

FAQ

Does the SDK start the workflow itself when capture ends?

Yes. The SDK calls Start workflow when capture is complete. In an SDK flow, you do not call it yourself.

Which webhook or status tells you capture is finished?

There is no capture-finished webhook or status. After the SDK calls Start workflow, the workflow moves to pending. The pending webhook, or Get workflow status showing pending, is the signal that processing has started. After a webhook, call Get workflow status.

What happens if you call Start workflow before capture is finished?

The endpoint checks that all required data is present. If the selfie or another required capture is not uploaded yet, the call returns 400 Bad Request with a message that names the missing data, for example IdentityVerification: selfie image required. In an SDK flow, you do not call Start workflow.

Is a second call harmless (202) or an error (400)?

Harmless. The endpoint is idempotent. A second call returns 202 Accepted and changes nothing.

6. Monitor status

Track progress until the workflow reaches a terminal state.

You can:

poll Get workflow status, and/or
listen for webhooks, then call Get workflow status for details.

Two layers of status

Layer	Where	Use
Workflow status	`workflowStatus`	Overall lifecycle state: `new`, `pending`, `completed`, or `failed`.
Product status	`products[].status` and related fields	Per-product result. Use this to decide the business outcome. See Product statuses.

If you poll only, call Get workflow status every 15–60 seconds while workflowStatus is pending. Stop when the status is completed, or failed.

For Production monitoring, combine status handling with a daily reconciliation job for workflows that remain pending in your database.

7. Retrieve reports

When workflowStatus is completed, retrieve reports according to your product requirements and internal business rules.

Need	Endpoint
Structured workflow result, statuses, CDD data, and product blocks	Get JSON report
ZIP bundle with PDF, XML, and identity files	Get ZIP report
PDF only	Get PDF report
XML only	Get XML report

See Workflow reports for report structure and examples.

Support

For any questions, contact your Fourthline delivery manager.