Migrate from API v1 to API v2

Learn what's changed, what stays the same, and how to update your integration

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

API v1API v2
Product-specific orchestrationWorkflow-based orchestration
Independent product lifecyclesUnified workflow lifecycle
Product-specific status endpointsUnified workflow status
Report formats: ZIP, PDFReport formats: JSON, ZIP, PDF, XML
Product-specific webhooksUnified workflow webhook

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 SDK 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.

ItemAPI v1API v2Action
Endpoint/v1/workflows/v2/workflowsUpdate the endpoint URL.
Request fieldworkflowNameworkflowRename the field.
Request fieldproviderClientIdpartnerClientIdRename the field and reuse the identifier for the same natural person.
Request fieldbranchbranch has no equivalent field in API v2Branch-level rules are replaced by workflow configurations. Each branch that had different document, country, or nationality rules should be mapped to a separate v2 workflow configuration.
ResponseReturns workflowId and clientIdUnchangedNo changes required.
Success response200 OK201 CreatedUpdate your success handling.
{
  "workflowName": "IDVandQES",
  "providerClientId": "usr-9f2a1b34",
  "branch": "NL_KYC"
}

Note

Use the same partnerClientId value across v1 and v2 to link the client's history. In v2, workflowName is no longer a standard value, it is the name of your specific workflow configuration.


Create an SDK session

Generate a validation code for the Mobile SDK (iOS or Android) or Web SDK.

ItemAPI v1API v2Action
Endpoint/v1/workflows/{workflowId}/validationcode/v2/workflows/{workflowId}/validationcodeUpdate the endpoint URL.
Request and responseUnchangedUnchangedNo changes required.

{"target":"Mobile"}'

or

{"target":"Web"}'

Upload client data (optional)

Upload or update identity data for a client.

ItemAPI v1API v2Action
Endpoint/v1/verifications/{verificationId}/kycdata/v2/workflows/{workflowId}/clients/{clientId}Update the endpoint URL.
Client reuseNot supportedSupportedReuse clientId.
Reference dataNot supportedreferenceDocumentDataUpload reference data.
Request and responseSee Upload identity dataSee Upload or update client dataReview the API v2 schema.

Field mapping

The following table maps v1 upload fields to their v2 equivalents. Some fields have been renamed, moved under a new parent object, or removed entirely. Use this table to update your client data upload when migrating from v1 to v2.

v1 fieldv2 fieldNotes
person.firstNameidentityData.personalData.firstName
person.middleNameidentityData.personalData.middleName
person.lastNameidentityData.personalData.lastName
person.dateOfBirthidentityData.personalData.birthDateField renamed from dateOfBirth to birthDate
person.genderidentityData.personalData.genderString enum: Male, Female, Unknown, not an integer
person.nationalityidentityData.personalData.nationalityISO 3166-1 alpha-3
person.placeOfBirthidentityData.personalData.placeOfBirthValue stored in uppercase, e.g. "SALZBURG"
person.countryOfBirthidentityData.personalData.countryOfBirth
person.initialsidentityData.personalData.initials
emailAndPhone.emailidentityData.contactDetails.emailValue must be lowercase
emailAndPhone.phoneidentityData.contactDetails.phone
emailAndPhone.mobileidentityData.contactDetails.mobileFormat: +33 612345678 (space after country code)
address.streetidentityData.address.street
address.streetNumberidentityData.address.streetNumber
address.streetNumberSuffixidentityData.address.streetNumberSuffix
address.postalCodeidentityData.address.postalCode
address.cityidentityData.address.city
address.countryidentityData.address.countryISO 3166-1 alpha-3
address.regionidentityData.address.region
tax.countrySubjectToTaxationidentityData.tax.countrySubjectToTaxation
tax.tinidentityData.tax.tin
deviceMetaData.languageidentityData.deviceMetaData.languageSDK fills automatically in SDK flows. Required in API-only flows.
deviceMetaData.regionidentityData.deviceMetaData.regionSDK fills automatically in SDK flows. Required in API-only flows.
deviceMetaData.modelidentityData.deviceMetaData.modelDo not send from backend > SDK fills it. Sending a wrong value breaks the QES device check.
deviceMetaData.ipAddressidentityData.deviceMetaData.ipAddressNot filled by SDK > confirm if required for your configuration.
deviceMetaData.latitudeidentityData.deviceMetaData.latitudeOnly if geolocation module is enabled.
deviceMetaData.longitudeidentityData.deviceMetaData.longitudeOnly if geolocation module is enabled.

Upload files (optional)

Upload identity documents and other files for a client.

ItemAPI v1API v2Action
Identity documentsPOST /v1/verifications/{verificationId}/kycdocumentPOST /v2/workflows/{workflowId}/clients/{clientId}/dataUpdate the endpoint URL.
Documents to signPOST /v1/onboarding/signatures/{workflowId}/documentsToSignPOST /v2/workflows/{workflowId}/clients/{clientId}/dataUpdate the endpoint URL.
Request and responseSee Upload identity filesSee Upload client documentReview the API v2 schema.

Note

In v2, all identity document types and documents to sign are uploaded to the same endpoint. Use the type field in the request body to specify the type of document being uploaded, such as: DocumentImage, SelfieImage, ReferenceSelfieImage, ProofOfResidence, DocumentToSign.


Start a workflow

If you use the Mobile SDK or Web SDK, you don't need to call this endpoint. The SDK automatically starts the workflow when capture is complete.

For API-only integrations, call this endpoint after uploading all required data. If any required data is missing, the API returns an HTTP 400 response with an error message indicating what's missing. For example: IdentityVerification: selfie image required.

This endpoint is idempotent. Calling it multiple times for the same workflow has no additional effect.

ItemAPI v1API v2Action
SDK flowsNot required > SDK calls start automaticallyNot requiredNo change required.
API-only flowsNot applicablePOST /v2/workflows/{workflowId}/startCall after all required data is uploaded.
Request and responseSee API ReferenceSee Start workflowReview the API v2 schema.

Check workflow status

Retrieve the current workflow and product statuses.

ItemAPI v1API v2Action
EndpointMultiple product-specific endpoints/v2/workflows/{workflowId}/statusUpdate the endpoint URL.
Status modelProduct statusWorkflow and product statusesHandle workflowStatus and products[].status.
Request and responseSee API ReferenceSee Get workflow statusReview the API v2 schema.

Identity Verification statuses

The following table compares the Identity Verification statuses returned in v1 and v2.

In v2, rejected and fraud are not returned as standalone statuses. Instead, the status is completed, and messages[].statusCode indicates the verification outcome.

StatusSent in v1?Sent in v2?Notes
new✅ Yes✅ Yes
pending✅ Yes✅ Yes
completed✅ Yes✅ YesIn v2, covers accepted, rejected, and fraud outcomes > read messages[].statusCode for the result.
inconsistent_data✅ Yes✅ Yes
invalid_data✅ Yes✅ Yes
timed_out❌ No✅ YesNew in v2. Maps to failed overall workflowStatus.

Note

All terminal outcomes have a status of completed. The messages[].statusCode indicates the verification outcome.


{
  "verificationId": "790f325a-48c9-4b82-bb53-c0ea128236f0",
  "verificationStatus": "completed",
  "riskInfo": {
    "statusCode": 200,
    "description": "Low risk"
  }
}

Note

The v1 response has been trimmed for clarity. The full response includes client data, documents, and raw VIZ readings. Only the fields relevant to status and risk are shown here.


Retrieve reports

Retrieve the reports generated for a completed workflow.

ItemAPI v1API v2Action
Report formatsPDF, ZIPJSON, PDF, ZIP, XMLJSON and XML are new in v2.
JSON reportNot availableGET /v2/workflows/{workflowId}/reports/jsonNew in v2.
PDF reportGET /v1/verifications/{verificationId}/getpdfresultGET /v2/workflows/{workflowId}/reports/pdfUpdate the endpoint URL.
ZIP reportGET /v1/verifications/{verificationId}/reportsGET /v2/workflows/{workflowId}/reports/zipUpdate the endpoint URL.
XML reportNot availableGET /v2/workflows/{workflowId}/reports/xmlNew in v2.
Signed documentsGET /v1/signatures/{signatureId}/signedDocuments/{documentId}GET /v1/signatures/{signatureId}/signedDocuments/{documentId}No change required.
Request and responseSee API ReferenceSee API ReferenceReview the API v2 schema.

Update webhooks

Update your webhook integration to receive workflow-based notifications.

ItemAPI v1API v2Action
Callback URLsSeparate URL per product (Identity Verification, QES, BAV)Single URL for all products > workflowId appendedConsolidate to one webhook endpoint.
AuthenticationBasic or Bearer per productBasic or Bearer - single configurationUpdate to a single authentication configuration.
Payload formatSingle JSON objectSingle JSON objectStructure changed, see payload comparison.
NotificationsProduct-specific eventsWorkflow-based events under detailsUpdate your handler to read details.name to identify the product.

Payload comparison

{
  "verificationId": "790f325a-48c9-4b82-bb53-c0ea128236f0",
  "hash": "6086c24e885ff4923bb3174fb2ed38b6",
  "status": "completed",
  "processType": "NaturalPersons",
  "sla": {
    "kycReceived": "2020-09-21T10:56:00.193Z",
    "slaStart": "2020-09-21T10:56:10.193Z",
    "slaPause": "2020-09-21T10:56:30.193Z",
    "slaEnd": "2020-09-21T10:56:50.193Z",
    "withinSla": true,
    "slaBucket": "bucket1"
  },
  "messages": [
    {
      "statusCode": 200,
      "description": "Verification completed - Low risk"
    }
  ],
  "dataRectified": false,
  "timestamp": "2022-08-08T11:45:52Z"
}


Validate your migration

Before deploying to production, verify that your integration can:


Support

For any questions, contact your Fourthline delivery manager.