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/verificationsor/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 v1 | API v2 |
|---|---|
| Product-specific orchestration | Workflow-based orchestration |
| Independent product lifecycles | Unified workflow lifecycle |
| Product-specific status endpoints | Unified workflow status |
| Report formats: ZIP, PDF | Report formats: JSON, ZIP, PDF, XML |
| Product-specific webhooks | Unified 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.
| Item | API v1 | API v2 | Action |
|---|---|---|---|
| Endpoint | /v1/workflows | /v2/workflows | Update the endpoint URL. |
| Request field | workflowName | workflow | Rename the field. |
| Request field | providerClientId | partnerClientId | Rename the field and reuse the identifier for the same natural person. |
| Request field | branch | branch has no equivalent field in API v2 | Branch-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. |
| Response | Returns workflowId and clientId | Unchanged | No changes required. |
| Success response | 200 OK | 201 Created | Update your success handling. |
{
"workflowName": "IDVandQES",
"providerClientId": "usr-9f2a1b34",
"branch": "NL_KYC"
}Note
Use the same
partnerClientIdvalue across v1 and v2 to link the client's history. In v2,workflowNameis 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.
| Item | API v1 | API v2 | Action |
|---|---|---|---|
| Endpoint | /v1/workflows/{workflowId}/validationcode | /v2/workflows/{workflowId}/validationcode | Update the endpoint URL. |
| Request and response | Unchanged | Unchanged | No changes required. |
{"target":"Mobile"}'
or
{"target":"Web"}'Upload client data (optional)
Upload or update identity data for a client.
| Item | API v1 | API v2 | Action |
|---|---|---|---|
| Endpoint | /v1/verifications/{verificationId}/kycdata | /v2/workflows/{workflowId}/clients/{clientId} | Update the endpoint URL. |
| Client reuse | Not supported | Supported | Reuse clientId. |
| Reference data | Not supported | referenceDocumentData | Upload reference data. |
| Request and response | See Upload identity data | See Upload or update client data | Review 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 field | v2 field | Notes |
|---|---|---|
person.firstName | identityData.personalData.firstName | |
person.middleName | identityData.personalData.middleName | |
person.lastName | identityData.personalData.lastName | |
person.dateOfBirth | identityData.personalData.birthDate | Field renamed from dateOfBirth to birthDate |
person.gender | identityData.personalData.gender | String enum: Male, Female, Unknown, not an integer |
person.nationality | identityData.personalData.nationality | ISO 3166-1 alpha-3 |
person.placeOfBirth | identityData.personalData.placeOfBirth | Value stored in uppercase, e.g. "SALZBURG" |
person.countryOfBirth | identityData.personalData.countryOfBirth | |
person.initials | identityData.personalData.initials | |
emailAndPhone.email | identityData.contactDetails.email | Value must be lowercase |
emailAndPhone.phone | identityData.contactDetails.phone | |
emailAndPhone.mobile | identityData.contactDetails.mobile | Format: +33 612345678 (space after country code) |
address.street | identityData.address.street | |
address.streetNumber | identityData.address.streetNumber | |
address.streetNumberSuffix | identityData.address.streetNumberSuffix | |
address.postalCode | identityData.address.postalCode | |
address.city | identityData.address.city | |
address.country | identityData.address.country | ISO 3166-1 alpha-3 |
address.region | identityData.address.region | |
tax.countrySubjectToTaxation | identityData.tax.countrySubjectToTaxation | |
tax.tin | identityData.tax.tin | |
deviceMetaData.language | identityData.deviceMetaData.language | SDK fills automatically in SDK flows. Required in API-only flows. |
deviceMetaData.region | identityData.deviceMetaData.region | SDK fills automatically in SDK flows. Required in API-only flows. |
deviceMetaData.model | identityData.deviceMetaData.model | Do not send from backend > SDK fills it. Sending a wrong value breaks the QES device check. |
deviceMetaData.ipAddress | identityData.deviceMetaData.ipAddress | Not filled by SDK > confirm if required for your configuration. |
deviceMetaData.latitude | identityData.deviceMetaData.latitude | Only if geolocation module is enabled. |
deviceMetaData.longitude | identityData.deviceMetaData.longitude | Only if geolocation module is enabled. |
Upload files (optional)
Upload identity documents and other files for a client.
| Item | API v1 | API v2 | Action |
|---|---|---|---|
| Identity documents | POST /v1/verifications/{verificationId}/kycdocument | POST /v2/workflows/{workflowId}/clients/{clientId}/data | Update the endpoint URL. |
| Documents to sign | POST /v1/onboarding/signatures/{workflowId}/documentsToSign | POST /v2/workflows/{workflowId}/clients/{clientId}/data | Update the endpoint URL. |
| Request and response | See Upload identity files | See Upload client document | Review the API v2 schema. |
Note
In v2, all identity document types and documents to sign are uploaded to the same endpoint. Use the
typefield 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.
| Item | API v1 | API v2 | Action |
|---|---|---|---|
| SDK flows | Not required > SDK calls start automatically | Not required | No change required. |
| API-only flows | Not applicable | POST /v2/workflows/{workflowId}/start | Call after all required data is uploaded. |
| Request and response | See API Reference | See Start workflow | Review the API v2 schema. |
Check workflow status
Retrieve the current workflow and product statuses.
| Item | API v1 | API v2 | Action | |
|---|---|---|---|---|
| Endpoint | Multiple product-specific endpoints | /v2/workflows/{workflowId}/status | Update the endpoint URL. | |
| Status model | Product status | Workflow and product statuses | Handle workflowStatus and products[].status. | |
| Request and response | See API Reference | See Get workflow status | Review 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.
| Status | Sent in v1? | Sent in v2? | Notes |
|---|---|---|---|
new | ✅ Yes | ✅ Yes | |
pending | ✅ Yes | ✅ Yes | |
completed | ✅ Yes | ✅ Yes | In v2, covers accepted, rejected, and fraud outcomes > read messages[].statusCode for the result. |
inconsistent_data | ✅ Yes | ✅ Yes | |
invalid_data | ✅ Yes | ✅ Yes | |
timed_out | ❌ No | ✅ Yes | New in v2. Maps to failed overall workflowStatus. |
Note
All terminal outcomes have a status of
completed. Themessages[].statusCodeindicates 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.
| Item | API v1 | API v2 | Action |
|---|---|---|---|
| Report formats | PDF, ZIP | JSON, PDF, ZIP, XML | JSON and XML are new in v2. |
| JSON report | Not available | GET /v2/workflows/{workflowId}/reports/json | New in v2. |
| PDF report | GET /v1/verifications/{verificationId}/getpdfresult | GET /v2/workflows/{workflowId}/reports/pdf | Update the endpoint URL. |
| ZIP report | GET /v1/verifications/{verificationId}/reports | GET /v2/workflows/{workflowId}/reports/zip | Update the endpoint URL. |
| XML report | Not available | GET /v2/workflows/{workflowId}/reports/xml | New in v2. |
| Signed documents | GET /v1/signatures/{signatureId}/signedDocuments/{documentId} | GET /v1/signatures/{signatureId}/signedDocuments/{documentId} | No change required. |
| Request and response | See API Reference | See API Reference | Review the API v2 schema. |
Update webhooks
Update your webhook integration to receive workflow-based notifications.
| Item | API v1 | API v2 | Action |
|---|---|---|---|
| Callback URLs | Separate URL per product (Identity Verification, QES, BAV) | Single URL for all products > workflowId appended | Consolidate to one webhook endpoint. |
| Authentication | Basic or Bearer per product | Basic or Bearer - single configuration | Update to a single authentication configuration. |
| Payload format | Single JSON object | Single JSON object | Structure changed, see payload comparison. |
| Notifications | Product-specific events | Workflow-based events under details | Update 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:
- 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.