Onfido Studio migration guide (v4 to v3.5)

Start here

Following the general release of Onfido Studio in API v3.4 and v3.5, all integrations using v4 must be migrated to v3.5.

API v4 was used for initial integrations prior to Studio's official release. This API version will soon be decommissioned, after which all v4 integration requests will fail.

This guide will help those who are still using API v4 to migrate their integration over to v3.5.

Endpoint mapping v4 → v3.5

In API v3.5, a number of endpoints have changed, some have been added, while others have been deprecated. You will find specific details on the endpoint mapping in the table below:

v4	v3.5	Description
Workflow run endpoints
POST v4/workflow_runs	POST v3.5/workflow_runs	Creates a workflow run
GET v4/workflow_runs/{workflow_run_id}	GET v3.5/workflow_runs/{workflow_run_id}	Retrieves a workflow run
N/A	GET v3.5/workflow_runs	Retrieves the workflow runs of the client
Task endpoints
N/A	GET v3.5/workflow_runs/{workflow_run_id}/tasks	Retrieves the tasks for a workflow run
N/A	GET v3.5/workflow_runs/{workflow_run_id}/tasks/{task_id}	Retrieves a specific task for a workflow run
Workflow links
POST v4/workflow_links	N/A	Note: This functionality is now under "POST /workflow_runs"
DELETE v4/workflow_links/{workflow_link_id}	N/A	Note: This functionality is no longer supported

Request payloads and response bodies

As a consequence of endpoint changes in API v3.5, the request payloads and response bodies have also been modified. You will find specific details in the tables below:

Workflow run endpoints

v4	v3.5
POST v4/workflow_runs	POST v3.5/workflow_runs
Request payload example: { "workflow_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "applicant_id": "13b88983-92ac-4698-9b5d-2d0b4d77dede", "applicant_data": { // -> Profile "first_name": "string", "last_name": "string", "ssn": "string", "identity_card": "string", "email": "string", "dob": "2022-08-02", "address": { "country": "ABW", "flat_number": "string", "building_number": "string", "building_name": "string", "street": "string", "sub_street": "string", "town": "string", "state": "string", "postcode": "string", "line1": "string", "line2": "string", "line3": "string" } }, "custom_data": {} }	Request payload example: `{ "workflow_id": "a7c8cd27-75a5-4891-9daa-99ad25db93d9", "applicant_id": "cdc4c2fc-716b-475f-8f48-e3c0eb0443b9", "custom_data": { "user_defined_parameter_1": "true", "user_defined_parameter_2": "string", }, "link": { "completed_redirect_url": "http://...", "expired_redirect_url": "http://...", "expires_at": "2022-10-17T14:40:50Z", "language": "en_US" } }`
Response body example: { "applicant_id": "5065ed28-8b10-456c-ae50-bd8fb38eccf3", "config": { "custom_output": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "timeout": 7200 }, "created_at": "2022-06-28T15:39:42.490079", "finished": false, "id": "caee5280-619e-4556-8db9-1ffdf0a17d57", "profile_data": {}, "state": "in_progress", "task_def_id": "start", "task_id": "66e02d87-f360-4b72-a899-47bd4509e321", "task_type": "SYNC", "updated_at": "2022-06-28T15:39:42.490079", "version_id": 11, "workflow_id": "15af606d-631b-47dd-af1f-3a3e43e8fce9" }	Response body example: { "applicant_id": "cdc4c2fc-716b-475f-8f48-e3c0eb0443b9", "created_at": "2022-11-24T12:16:10Z", "dashboard_url": "https://dashboard.onfido.com/results/bedb8975-fff4-4fa5-b13c-41c2a881e33b", "error": null, "id": "bedb8975-fff4-4fa5-b13c-41c2a881e33b", "link": { "completed_redirect_url": "http://...", "expired_redirect_url": "http://...", "expires_at": "2022-10-17T14:40:50Z", "language": "en_US", "url": "https://orchestration-test.eu.onfido.app/l/bedb8975-fff4-4fa5-b13c-41c2a881e33b" }, "output": null, "reasons": [], "status": "processing", "updated_at": "2022-11-24T12:16:10Z", "workflow_id": "a7c8cd27-75a5-4891-9daa-99ad25db93d9", "workflow_version_id": 3 }

Major differences:

Applicant data is no longer passed through the create request, an applicant ID is used instead. Find further documentation here
The Smart Capture Link URL is now created together with a workflow run and returned in the response body. Find further documentation here
Task information can now be obtained using a dedicated endpoint, not in the response body
The finished attribute was removed, information can be obtained from the status attribute
The state attribute has been replaced by the status attribute:
- in_progress → awaiting_input, awaiting_client_input or processing
- clear → approved
- fail → declined
- manual_review → review
- cancelled → abandoned or error
The version_id attribute has been renamed workflow_version_id

v4 v3.5

GET v4/workflow_runs/{workflow_run_id} GET v3.5/workflow_runs/{workflow_run_id}

Response body example:

{
  "applicant_id": "13b88983-92ac-4698-9b5d-2d0b4d77dede",
  "config": {
      "reasons": []       
  },
  "created_at": "2022-06-14T08:53:29.539504",
  "finished": true,
  "id": "2ba91ecb-fde1-4d5b-89d5-488d58544dd5",
  "outcome": true,
  "applicant_data": {     
    "addresses": [],   
    "client_id": "06a9ca08-b03b-4030-8cc0-943bdc22eed5",
    "dob": null,        // Rename to date_of_birth?
    "email": "dummy@dummy.com",
    "first_name": "iOS - 1",
    "last_name": "MU89",
    "ssn": "111223333",
  },
  "state": "clear",       
  "task_def_id": "pass_applicant",
  "task_id": "336b11b0-7940-4fbb-a467-489dded8da64",
  "task_type": "SYNC",
  "updated_at": "2022-06-14T08:56:46.427642",
  "version_id": 3,        
  "workflow_id": "29391e4e-a993-4f57-8116-e9277f1d4dbd"
}

Response body example:

{
  "applicant_id": "13b88983-92ac-4698-9b5d-2d0b4d77dede",
  "created_at": "2022-06-14T08:53:29.539504",
  "dashboard_url": "https://dashboard.onfido.com/results/5b4d1ae7-9d79-427a-999a-d128813d4c47
  "id": "2ba91ecb-fde1-4d5b-89d5-488d58544dd5",
  "error": null  
  "reasons": ["doc_and_face_clear", "reason2", "reason3"], 
  "status": "approved",   
  "updated_at": "2022-06-14T08:56:46.427642",
  "workflow_id": "29391e4e-a993-4f57-8116-e9277f1d4dbd",
  "workflow_version_id": 3,
  "output": {},
  "link": {
        "completed_redirect_url": null,
        "expired_redirect_url": null,
        "expires_at": null,
        "language": null,
        "url": "https://orchestration-test.eu.onfido.app/l/bedb8975-fff4-4fa5-b13c-41c2a881e33b"
  }
}

Major differences:

Applicant data is no longer available in the workflow run response, but can be retrieved via API or the Studio Dashboard. For mapping applicant data to output any fields from the profile, please refer to our API reference or Studio product guide for workflow run output documentation
Task information can now be obtained using a dedicated endpoint, not in the response body

v4	v3.5	Description
	GET v3.5/workflow_runs
N/A	New	A new endpoint available under v3.4 and v3.5 to retrieve the workflow runs of the client. Find further documentation here

Task endpoints

v4	v3.5	Description
	GET v3.5/workflow_runs/{workflow_run_id}/tasks
N/A	New	A new endpoint available under v3.4 and v3.5, to retrieve the tasks for a workflow run. Find further documentation here
	GET v3.5/workflow_runs/{workflow_run_id}/tasks/{task_id}
N/A	New	A new endpoint available under v3.4 and v3.5, to retrieve a specific task for a workflow run. Find further documentation here

Workflow links endpoints

v4	v3.5	Description
POST v4/workflow_links
	Deprecated	Deprecated endpoint. This functionality is now managed in the Create Workflow Run endpoint
DELETE v4/workflow_links/{workflow_link_id}
	Deprecated	Deprecated endpoint, no longer exists under v3.4 or v3.5