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:
- Fourthline API credentials and access to Create access token
- The workflow name passed as
workflowon 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 | Authenticate | Obtain a bearer token. Tokens are valid for 1 hour. |
| 2 | Create workflow | 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. The SDK calls this endpoint automatically. |
| 5 | Get workflow status | Check the workflow status until workflowStatus reaches completedor failed. Review the status of each product in products[].status. |
| 6 | Get 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 untilworkflowStatusiscompleted, 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.

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_tokenvalid for 1 hour.
API reference: Create access token
2. Create workflow
Create a workflow for the client.
- Set
workflowto your configured workflow name. - Provide either
partnerClientIdorclientId, but not both. - Use
partnerClientIdwhen onboarding a new client with your own client reference. - Use
clientIdfor returning clients when you already have the Fourthline client id. - Store the returned
workflowIdandclientId.
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
failedworkflow status or product-levelinvalid_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
workflowIdandtarget(MobileorWeb). - You receive a single-use
validationCode. - The
validationCodeexpires 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:
- Poll Get workflow status.
- Listen for webhooks, then call Get workflow status for details.
Workflow and product statuses
| Layer | Where | Use |
|---|---|---|
| Workflow status | workflowStatus | Indicates the overall workflow state: new, pending, completed, or failed.: |
| Product status | products[].status and related fields | Indicates 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.
| 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.
Updated 4 days ago