Onfido logo home page
Watch a demo
Get in touch
Arrow back Back to guides

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_progressawaiting_input, awaiting_client_input or processing
    • clearapproved
    • faildeclined
    • manual_reviewreview
    • cancelledabandoned 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


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
Onfido

Our solutions

Onfido uses 256-bit SSL encryption 100% of the time on every device.

BSI ISO/IEC27001

Onfido has been certified by BSI to ISO 27001 under certificate number IS 660122.

© Onfido™, 2022. All rights reserved.
Company Registration Number: 07479524.