Integrating with the Assure API using the Onfido iOS SDK

On this page, you will find all the necessary instructions to start using the Assure API in a native iOS environment, using Onfido as an identity verification provider.In this use case you must use Onfido’s iOS SDK for capturing and uploading the ID images during Step 2 of the basic flow.

Setting up Onfido’s iOS SDK


Import SDK

  1. Make sure you have downloaded and installed the latest version of CocoaPods.
  2. Add the following row to your Podfile:
pod 'Onfido'
  1. Run pod install .
  2. Make sure to use the .xcworkspace file to open your project in Xcode, instead of the .xcodeproj file, from here on.

Integrating with the Assure API and with Onfido’s iOS SDK

Step 1.1: Create a dossier

Use the Create Dossier endpoint to create a new dossier:

curl -X POST \
  <ENVIRONMENT>/assure/dossiers \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \

Save the dossierId from the response body to use on the next requests.

Step 1.2: Get document types

Before proceeding to the next step, you must know which type of ID document the end-user will provide to validate their identity (you will need that information in Step 1.3).

To find out which types of identity documents are supported by Onfido for each country, use the Get Document Types endpoint:

curl -X GET \
  <ENVIRONMENT>/assure/onfido/document-types \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <>' \

Step 1.3: Create a process, using Onfido as the identity verification provider

Use the Create Process endpoint to create a new process:

curl -X POST \
  <ENVIRONMENT>/assure/dossiers/<DOSSIER_ID>/processes \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "provider": "onfido",
  "documentType": "passport"

Make sure to:

Save the processId and the authorization from the response body to use in the next steps.

Step 1.4: Launch the Onfido iOS SDK

import UIKit
import Onfido

final class ViewController: UIViewController {

    private let token = "YOUR_TOKEN_HERE"

    private func runFlow(forApplicantWithId applicantId: String) {

        let responseHandler: (OnfidoResponse) -> Void = { response in 

            self.responseHandler(response: response)

        let config = try! OnfidoConfig.builder()
            .withWelcomeStep() // You can decide if you want to show/hide Onfido's pre-defined wecolme screen
            .withDocumentStep(ofType: documentType, andCountryCode: coutryCode) // You can omit the parameters if you want to use Onfido's built-in steps to select Document type and Country 
            .withFaceStep(ofVariant: .photo(withConfiguration: nil))

        let onfidoFlow = OnfidoFlow(withConfiguration: config)
            .with(responseHandler: responseHandler)
        do {

            let onfidoRun = try
            onfidoRun.modalPresentationStyle = .formSheet // to present modally
            self.present(onfidoRun, animated: true, completion: nil)
        } catch let error {

           // cannot execute the flow
           // check CameraPermissions
           self.showErrorMessage(forError: error)

    private func responseHandler(response: OnfidoResponse) {
        switch response {
            case let .error(error): self.errorHandler(onfidoError: error)
            case let .success(results): successHandler(result: results)
            case .cancel: cancelHandler()

    private func errorHandler(onfidoError: Error) -> MsgErrorStruct {
        let somethingHappened = "Something happened"
        var text = somethingHappened
        switch onfidoError {
        case OnfidoFlowError.cameraPermission: text = "Permission denies for camera"
        case OnfidoFlowError.failedToWriteToDisk: text = "Failed to write to disk, maybe due to a lack of space"
        case OnfidoFlowError.microphonePermission: text = "Permission denies for microphone"
        case OnfidoFlowError.upload(let OnfidoApiError):
            print("Error message \(OnfidoApiError.description)")
            switch OnfidoApiError.type {
            case "authorization_error":
                text = "Sorry...Possible issue with your credentials"
                text = OnfidoApiError.message
        case OnfidoFlowError.exception(withError: let error, withMessage: let message):
            print(message ?? "")
        if (text == somethingHappened) {
            switch URLError.Code(rawValue: onfidoError._code) {
            case .notConnectedToInternet: text = onfidoError.localizedDescription
            default: text = onfidoError.localizedDescription
        return MsgErrorStruct(title: text, subTitle: "")


Step 1.5: Start verification

When the end-user is done collecting the images, you must tell the Assure API to start verifying all of the provided data.

To do that, you must call the Start Verification endpoint of the Assure API:

curl -X POST \
  <ENVIRONMENT>/assure/dossiers/<DOSSIER_ID>/processes/<PROCESS_ID> \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "notificationUrl": "",
  "authorizationHeader": "Token xSUh9hniB7bKJbNOhoasddasd"

Make sure to use the dossierId (<DOSSIER_ID>) and processId (<PROCESS_ID>) from the previous steps.

You can provide a notificationUrl (and an authorizationHeader if needed – setting this value will add an Authorization header to the request that is sent to the notificationUrl). These fields are not mandatory but are required if you want to receive a notification when the verification has finished (step 1.6).

Step 1.6: Get the verification results

After you receive the callback notification (in the URL you provided in step 1.5), you must use the Get Process endpoint to check the full result of the identity verification:

curl -X GET \
  <ENVIRONMENT>/assure/dossiers/<DOSSIER_ID>/processes/<PROCESS_ID> \
  -H 'Authorization: Bearer <OIDC_ACCESS_TOKEN>' \
  -H 'Accept: application/json' \

You will get all the process and result information in the response body. Please refer to the Process Details documentation for more information about the contents of this response.

Note that you can call this endpoint at any time. However, the final result will only be available after the notification has been sent.