Migrate from API v1 to API v2

Fourthline API v2 introduces a configurable workflow model that replaces legacy product-specific integrations.

Overview

This guide explains how to migrate an existing API v1 integration to API v2.

API v2 preserves the overall integration flow used in API v1. Authentication, asynchronous processing, and the request lifecycle remain unchanged. Most migrations only require updating endpoint URLs, request parameters, and webhook handling.

Am I using API v1?

You're using API v1 if your integration calls endpoints under the /v1/ path, or uses product-specific endpoints such as /v1/verifications or /v1/signatures.

If you're unsure, review your integration's endpoint URLs or contact your customer success manager.

Before you begin

Before migrating, make sure you:

• Have an existing API v1 integration.
• Have access to the API v2 documentation.
• Can test your integration in the sandbox environment.
• Identify the API v1 endpoints your integration uses.
• Inventory your existing webhook callback URLs.

What's changed

What stays the same

Authentication, asynchronous request processing, standard HTTP methods, and HTTPS-only communication are unchanged in API v2.

Workflow

The following diagram shows the API v2 request flow.

API v2 preserves the overall integration flow used in API v1. Most migrations only require updating endpoint URLs, request payloads, and response schemas.

API v2 request flow

Migration checklist

Complete the following tasks to migrate your integration:

• Update endpoint URLs.
• Update request parameters.
• Update response handling where applicable.
• Update webhook configuration.
• Review asynchronous workflow handling.
• Review error handling.
• Validate your integration in the sandbox.
• Deploy to production.

Authentication

Authentication is unchanged in API v2. Continue using the client credentials grant and the existing /v1/oauth2/token endpoint. No integration changes are required.

{
      "grant_type": "client_credentials",
      "client_id": "string",
      "client_secret": "string"
}

Create a workflow

Create a workflow for a new or existing client.

{
  "workflowName": "IDVandQES",
  "providerClientId": "abcd-client-12345"",
}

Note

Use the same partnerClientId for the same natural person across workflows to prevent duplicate client records.

Create an SDK session

Generate a validation code for the Mobile SDK or Web SDK.

{"target":"Mobile"}'

or

{"target":"Web"}'

Upload client data (optional)

Upload or update identity data for a client.

{
  "person": {
    "type": "string",
    "name": "string",
    "initials": "string",
    "firstName": "string",
    "middleName": "string",
    "lastName": "string",
    "otherLastName": "string",
    "nationality": "string",
    "gender": "string",
    "birthDate": "string",
    "placeOfBirth": "string"
  },
  "address": {
    "street": "string",
    "streetNumberPrefix": "string",
    "streetNumber": 0,
    "streetNumberSuffix": "string",
    "postalCode": "string",
    "region": "string",
    "city": "string",
    "country": "string"
  },
  "emailAndPhone": {
    "email": "string",
    "phone": "string",
    "mobile": "string"
  },
  "tax": {
    "countrySubjectToTaxation": "string",
    "tin": "string",
    "usPerson": "string",
    "usTin": "string"
  },
  "riskRequirements": [],
  "deviceMetaData": {
    "browserType": "string",
    "browserVersion": "string",
    "ipAddress": "string",
    "language": "string",
    "latitude": "string",
    "longitude": "string",
    "model": "string",
    "osCompromised": "string",
    "osVersion": "string",
    "region": "string",
    "sdkVersion": "string",
    "analyticsId": "string"
  }
}
'

Upload files (optional)

Upload identity documents and other files for a client.

Start a workflow (optional)

You don't need to call this endpoint when using the Mobile SDK or Web SDK.

Check workflow status

Retrieve the current workflow and product statuses.

{
  "verificationId": "790f325a-48c9-4b82-bb53-c0ea128236f0",
  "verificationStatus": "new",
  "dataValidationError": {}
}

Retrieve reports

Retrieve the reports generated for a completed workflow.

Update webhooks

Update your webhook integration to receive workflow-based notifications.

Validate your migration

Before deploying to production, verify that your integration can:

• Confirm production credentials and endpoints are configured.
• Authenticate successfully.
• Create a workflow.
• Generate an SDK validation code.
• Upload client data and documents.
• Start workflows where required.
• Receive webhook notifications.
• Retrieve workflow status.
• Retrieve reports in the required format.
• Handle retries and error responses correctly.

Support

For any questions, contact your Fourthline delivery manager.