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.

---

Optional capabilities

Add these only when your workflow requires them.

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

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.

---

4. Create SDK session

Create an SDK session only if you use App Drop-in or Web SDK capture. 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 or Web SDK.

API reference: Create SDK session

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

---

5. Start workflow

Start processing after all mandatory uploads are complete and, if applicable, after SDK capture is complete.

• You provide workflowId.
• Workflows cannot be restarted.
• Every successful start request, including retries after the workflow has already started, returns 202 Accepted with an empty response body. Duplicate requests are treated as idempotent and acknowledged without issuing additional start commands for products that are no longer in the new state.

API reference: Start workflow

---

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

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.

See Workflow reports for report structure and examples.

---

Support

For any questions, contact your Fourthline delivery manager.