V2 Integrations

Integration Guides API v2

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:


Minimum viable integration

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

StepoperationIdWhat you do
1AuthenticateObtain a bearer token. Tokens are valid for 1 hour.
2Create workflowPOST workflow and either partnerClientId or clientId, but not both. Store workflowId.
3Upload client data / Upload client documentUpload all mandatory data and documents required by your workflow configuration.
4Start workflowFor an API-only integration, start processing. Expect 202 Accepted and an empty body. The SDK calls this endpoint automatically.
5Get workflow statusCheck the workflow status until workflowStatus reaches completedor failed. Review the status of each product in products[].status.
6Get report as...After the workflow completes, retrieve the workflow report in your preferred format: JSON, ZIP, PDF, or XML. Each format has a dedicated endpoint.

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

ApproachWhen to useWhat you implement
API-onlyYou control capture in your app or backend.Upload client data, Upload client document, optional bulk upload
SDKFourthline 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.

Identity Verification SDK flow


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 you need to upload deviceMetaData in an SDK flow?

No. The SDK uploads model, language, region, osVersion, and sdkVersion automatically when the client opens the session.


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 automatically start the workflow after capture is complete?

Yes. The SDK automatically calls Start workflow once capture is complete. You do not need to call this endpoint yourself when using the SDK.

Is there a webhook or status indicating that capture is complete?

No. There is no dedicated webhook or status indicating that capture is complete. Once the SDK calls Start workflow, the workflow transitions to pending. A pending webhook or a pending status returned by Get workflow status confirms that processing has started.

What happens if Start workflow is called before capture is complete?

The endpoint validates that all required data has been uploaded. If a selfie or another required capture is missing, it returns a 400 Bad Request response with an error message identifying the missing data, such as IdentityVerification: selfie image required.

Can you call the endpoint multiple times

Yes. The endpoint is idempotent, so calling it multiple times for the same workflow has no additional effect.


6. Monitor status

Monitor the workflow until it reaches a terminal state.

You can:

Workflow and product statuses

LayerWhereUse
Workflow statusworkflowStatusIndicates the overall workflow state: new, pending, completed, or failed.:
Product statusproducts[].status and related fieldsIndicates the outcome of each product. Use this status to determine the business outcome. See Product statuses.

If you use polling, call Get workflow status every 15–60 seconds while workflowStatus is pending. Stop polling when the status changes to completed or failed.

In your production environment, run a daily reconciliation job to identify workflows that remain pending in your database.


7. Retrieve reports

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

NeedEndpoint
Structured workflow result, statuses, CDD data, and product blocksGet JSON report
ZIP bundle with PDF, XML, and identity filesGet ZIP report
PDF onlyGet PDF report
XML onlyGet XML report

See Workflow reports for report structure and examples.


Support

For any questions, contact your Fourthline delivery manager.