In this example, let’s say you need to onboard a new customer: Kelly Smith.

Before becoming a customer, Kelly must complete your signup form and then submit some documents that need to be verified :

A Bank Account Details Document
An Identity Document
A Proof of Address

In this workflow, your Workflow Template contains 3 Action Groups:

Bank Account Verification
Identity Verification
Proof of Address Verification

Step 1: Retrieve the Workflow Template ID

Endpoint: List Workflow Templates (GET /workflow_templates)

// no request body required

{
  "meta": {
    "next_cursor": null
  },
  "data": [
    {
      "id": "35a07993...",
      "name": "Customer onboarding",
      "action_groups": [
        {
          "type": "identity_verification"
        },
        {
          "type": "bank_account_verificaiton"
        }, 
        {
          "type" : "proof_of_address_verification"
        }

      ],
      "workspaces": [],
      "created_at": "2025-09-10T12:56:59+00:00",
      "updated_at": "2025-09-10T12:56:59+00:00"
    }
  ]
}

Step 2: Create a new Workflow Session

Endpoint: Create a new Workflow Session (POST /workflow_sessions)
Content type: application/json

In the request, pass the Workflow Template Id.

Give the session a clear name so it’s easy to identify later in the app dashboard.

{
  "name": "Onboarding of Kelly Smith",
  "workflow_template_id": "35a07993...",
  "workspace_id": null
}

{
  "id": "c0cbf043...",
  "name": "Onboarding of Kelly Smith",
  "workflow_template_id": "35a07993...",
  "workspace_id": "814aac47...",
  "status": "awaiting",
  "action_groups": [
    {
      "type": "identity_verification",
      "status": "awaiting",
      "actions": []
    },
    {
      "type": "bank_account_verification",
      "status": "awaiting",
      "actions": []
    }, 
    {
      "type" : "proof_of_address_verification",   
      "status" : "awaiting",  
      "actions" : []
    }
  ],
  "created_at": "2025-09-22T14:30:00+00:00",
  "updated_at": "2025-09-22T14:30:00+00:00"
}

At this point, all Action Groups are empty and the Workflow Session status is awaiting.

Step 3: Add an Applicant to your Workflow Session

Endpoint: Create a new Applicant (POST /workflow_sessions)
Content type: application/json

Create a natural person here with all the information needed to cross-reference-check the data on your verifications.

{
    "label": "Kelly Smith", 
    "type" : "natural_person", 
    "natural_person" : {
        "identity" : {
            "first_name" : "Kelly",
            "last_name" : "Smith"
        }, 
        "address" : {
            "line_1" : "123 York Street",
            "line_2" : null,   
            "city" : "Paris", 
            "zip_code" : "123"
        }, 
        "bank_account" : {
            "iban" : "FR7630001007941234567890185", 
            "bic" : "BCHAFR21" 
        }
    }

}

{
    "natural_person": {
        "identity": {
            "first_name": "Kelly",
            "last_name": "Smith"
        },
        "address": {
            "line_1" : "123 York Street", 
            "line_2" : null, 
            "country" : "France", 
            "city" : "Paris", 
            "zip_code" : "123"
        },
        "bank_account": {
            "iban": "FR7630001007941234567890185",
            "bic": "BCHAFR21"
        }
    },
    "id": "7fb27946-e874-4d7c-b175-b3ccc8417af0",
    "workflow_session_id": "c0cbf043...",
    "status": "initiated",
    "label": "Kelly Smith",
    "reference_id": null,
    "created_at": "2026-03-10T09:11:59+00:00",
    "updated_at": "2026-03-10T09:11:59+00:00",
    "type": "natural_person"
}

{
    "label": "Yousign", 
    "type" : "legal_person", 
    "reference_id" : "123"  
    "legal_person" : {
        "company_name" : "Yousign" 
        "country_code" : "FR"
        "bank_account" : {
            "iban" : "FR7630001007941234567890185", 
            "bic" : "BCHAFR21" 
        }
      "legal_representatives" : [
        {
          "first_name" : "Alban"
          "last_name" : "Sayag"
        }
    ]

}

Get the applicant_id in the response to add Verification to your Applicant.

Step 4: Add Verifications to your Applicant

Since you need to run : Bank Account Verification, Proof Of Address Verification and Identity Verification, call the following endpoints simply by passing the applicant_id in the payload.

Attach an Image Identity Verification to an Applicant by calling this endpoint

{
   "applicant_id" : "7fb27946-e874-4d7c-b175-b3ccc8417af0"
}

{
    "id": "1509b015-5b72-4727-b75f-7b7eff236159",
    "workspace_id": "6ed2772f-8d7e-4f67-ab2a-790a1dce2adc",
    "created_at": "2026-03-10T09:26:12+00:00",
    "updated_at": "2026-03-10T09:26:12+00:00",
    "status": "awaiting_data",
    "status_codes": [],
    "data_anonymized": false,
    "workflow_session_id": "c0cbf043....",
    "previous_attempt_id": null,
    "data": {
        "extracted_from_document": {
            "first_name": null,
            "birth_name": null,
            "last_name": null,
            "born_on": null,
            "birth_location": null,
            "gender": null,
            "full_address": null,
            "type": null,
            "issuing_country_code": null,
            "issued_on": null,
            "expired_on": null,
            "document_number": null,
            "mrz": {
                "line1": null,
                "line2": null,
                "line3": null
            },
            "national_identification_number": null
        }
    }
}

📘
For Image Identity Verification, the end user will have the ability to choose the type of document he uploads between : id_card, passport or resident_permit, for more details see the detailed guide here.

Attach a Proof of Address Verification to an Applicant by calling this endpoint

{
   "applicant_id" : "7fb27946-e874-4d7c-b175-b3ccc8417af0"
}

{
    "id": "311efe2c-f215-494a-8586-655d77c717cd",
    "workspace_id": "6ed2772f-8d7e-4f67-ab2a-790a1dce2adc",
    "created_at": "2026-03-10T09:37:50+00:00",
    "updated_at": "2026-03-10T09:37:50+00:00",
    "status": "awaiting_data",
    "status_codes": [],
    "data_anonymized": false,
    "data": {
        "extracted_from_document": {
            "first_name": null,
            "last_name": null,
            "full_address": null,
            "issued_on": null,
            "document_type": null,
            "2d_doc": {
                "full_name": null,
                "address": {
                    "line1": null,
                    "postal_code": null,
                    "city": null,
                    "country_code": null
                }
            }
        }
    },
    "workflow_session_id": "c0cbf043...",
    "previous_attempt_id" :

Attach a Bank Account Verification to an Applicant by calling this endpoint

{
   "applicant_id" : "7fb27946-e874-4d7c-b175-b3ccc8417af0"
}

{
    "id": "6ead6ddb-8228-480f-85f8-18f395bb6be0",
    "workspace_id": "6ed2772f-8d7e-4f67-ab2a-790a1dce2adc",
    "created_at": "2026-03-10T09:39:43+00:00",
    "updated_at": "2026-03-10T09:39:43+00:00",
    "status": "awaiting_data",
    "status_codes": [],
    "data_anonymized": false,
    "workflow_session_id": "c0cbf043...",
    "previous_attempt_id": null,
    "data": {
        "extracted_from_document": {
            "iban": null,
            "bic": null
        }
    }
}

Step 4: Get you Workflow Session Links

Call the Workflow Session Links endpoint, to get the Workflow Session Link and share it to your end user, either via email or SMS.

// no request body required

{
  "applicants": [
    {
      "id": "7fb27946-e874-4d7c-b175-b3ccc8417af0",
      "workflow_session_id": "c0cbf043",
      "type": "natural_person",
      "label": "Jean Dupont",
      "reference_id": "user-42",
      "status": "notified",
      "workflow_session_link_url": "https://app.yousign.com/workflow_session_link?token=eyJh...",
      "workflow_session_link_expires_at": "2026-03-08T09:05:00+00:00",
      "created_at": "2026-03-06T09:01:00+00:00",
      "updated_at": "2026-03-06T09:05:00+00:00"
    }
  ]
}
}

Step 5: Follow the progress of your Workflow Session

To follow the progress of your Workflow Session you can either :

Monitor the Workflow Session Wehbooks as defined here
Follow the Workflow Session status directly within your Workflow's Dashboard.