Guides
Status PageRoadmapTestimoniesShare feedback

How to guide - Create & Execute your first Workflow Session

A step-by-step guide to create and execute your first Workflow Session.

Suggest Edits

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

Before becoming a customer, Kelly must complete your onboarding workflow:

  1. Verify her identity
  2. Sign a contract

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

  • Identity Verification
  • Signature Request

➡️

Before you start:

Make sure your organization already has a Workflow Template.

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": "signature_request"
        }
      ],
      "workspaces": [],
      "created_at": "2025-09-10T12:56:59+00:00",
      "updated_at": "2025-09-10T12:56:59+00:00"
    }
  ]
}

👉 Save the Id value—you’ll need it to create a Workflow Session.

Step 2: Create a new Workflow Session

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": "signature_request",
      "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: Verify Kelly Smith’s Identity

Include the Workflow Session Id in your request.

--form 'file=@"/path/to/the/document/my_document.pdf"' \
--form 'workflow_session_id="c0cbf043..."'

{
  "id": "79a291fc...",
  "workspace_id": "814aac47...",
  "created_at": "2025-09-22T14:32:00+00:00",
  "updated_at": "2025-09-22T14:32:00+00:00",
  "status": "verified",
  "status_codes": [],
  "data_anonymized": false,
  "data": {
    "extracted_from_document": {
      "first_name": "Kelly",
      "birth_name": "Smith",
      "last_name": "Smith",
      "born_on": "1990-07-13",
      "birth_location": "Paris",
      "gender": "m",
      "full_address": "18 rue de Londres\nParis\nFRANCE",
      "type": "id_card",
      "issuing_country_code": "FR",
      "issued_on": "2020-08-11",
      "expired_on": "2030-08-10",
      "document_number": "X4RBBPBW4",
      "mrz": {
        "line1": "IDFRAX4RTBPFW46<<<<<<<<<<<<<<<",
        "line2": "9007138F3002119FRA<<<<<<<<<<<6",
        "line3": "SMITH<<KELLY<<<<<<<<<<<<<<<<<<<<<"
      }
    }
  }
}

The identity verification succeeded, so the resource status is now verified.

Step 4: Check the Workflow Session status

Endpoint: Retrieve a Workflow Session (GET /workflow_sessions/{workflowSessionId})

// no request body required

{
  "id": "c0cbf043...",
  "name": "Onboarding of Kelly Smith",
  "workflow_template_id": "35a07993...",
  "workspace_id": "814aac47...",
  "status": "ongoing",
  "action_groups": [
    {
      "type": "identity_verification",
      "status": "done",
      "actions": [
        {
          "resource": {
            "id": "79a291fc...",
            "type": "identity_document_verification",
            "status": "verified"
          }
        }
      ]
    },
    {
      "type": "signature_request",
      "status": "awaiting",
      "actions": []
    }
  ],
  "created_at": "2025-09-22T14:30:00+00:00",
  "updated_at": "2025-09-22T14:32:30+00:00"
}

The Action Group of type Identity Verification is now done, so the Workflow Session status has moved to ongoing.

Step 5: Create and send the contract for signature to Kelly Smith

{
  "name": "Kelly Smith contract",
  "delivery_mode": "email",
  "workflow_session_id": "c0cbf043..."
}

{
  "id": "6f7001fc...",
  "source": "public_api",
  "status": "draft",
  "name": "Kelly Smith contract",
  "created_at": "2025-09-22T14:34:00+00:00",
  "email_custom_note": null,
  "ordered_signers": false,
  "timezone": "Europe/Paris",
  "reminder_settings": null,
  "expiration_date": "2026-03-22T14:34:00+00:00",
  "delivery_mode": "email",
  "documents": [],
  "signers": [],
  "external_id": null,
  "branding_id": null,
  "custom_experience_id": null,
  "sender": null,
  "workspace_id": "814aac47...",
  "audit_trail_locale": "en",
  "signers_allowed_to_decline": false,
  "bulk_send_batch_id": null,
  "email_notification": {
    "sender": {
      "type": "organization",
      "custom_name": null
    },
    "custom_note": null
  }
}

Next steps:

  1. Add a Document, Signer, and Signature Field to the Signature Request.
  2. Activate the Signature Request.

📖

For detailed instructions, see How to guide - Create your first Signature Request.

Once Kelly signs the contract, the Signature Request status becomes done.

Step 6: Retrieve the final Workflow Session status

Endpoint: Retrieve a Workflow Session (GET /workflow_sessions/{workflowSessionId})

// no request body required

{
  "id": "c0cbf043...",
  "name": "Onboarding of Kelly Smith",
  "workflow_template_id": "35a07993...",
  "workspace_id": "814aac47...",
  "status": "done",
  "action_groups": [
    {
      "type": "identity_verification",
      "status": "done",
      "actions": [
        {
          "resource": {
            "id": "79a291fc...",
            "type": "identity_document_verification",
            "status": "verified"
          }
        }
      ]
    },
    {
      "type": "signature_request",
      "status": "awaiting",
      "actions": [
        {
          "resource": {
            "id": "6f7001fc...",
            "type": "signature_request",
            "status": "done"
          }
        }
      ]
    }
  ],
  "created_at": "2025-09-22T14:30:00+00:00",
  "updated_at": "2025-09-22T14:40:00+00:00"
}

All statuses are now done—Kelly Smith has successfully completed the onboarding workflow 🎉

Updated about 11 hours ago