Skip to main content

Creating a Signing Session

This use case describes the step-by-step process of creating and starting a new signing session via the EasyInk Public API.

Overview​

Creating a signing session is a multi-step process. You first create a Draft, configure it by adding documents, participants, and signature fields, then Convert it to a ready to start session, and finally Start the session to notify participants.

Workflow Summary​

  1. Create Draft – Initialize a container for your signing session.
  2. Upload Documents – Add PDF files that need to be signed.
  3. Add Participants – Define who needs to sign or receive copies.
  4. Place Signature Fields – Specify where participants should sign on the documents.
  5. Convert to Session – Finalize the draft configuration and prepare for starting.
  6. Start Session – Send invitations to participants.

Step 1: Create a Draft​

Initialize the signing session by providing a subject. This returns a signingSessionId which you will use in all subsequent steps.

Endpoint: POST /api/signingSessionDrafts

Request:

{
  "subject": "Onboarding Documents - Jane Doe"
}

Response: "3fa85f64-5717-4562-b3fc-2c963f66afa6" (the signingSessionId)

Step 2: Upload Documents​

Upload the PDF documents that participants will sign. You can upload multiple documents to a single session.

Endpoint: POST /api/signingSessionDrafts/{signingSessionId}/documents

Request (Multipart Form Data):

  • fileContent: Binary content of the PDF or Word document.

Step 3: Add Participants​

Add one or more participants to the session. You must specify their role (Signer, CC) and delivery methods (Email, SMS).

Endpoint: POST /api/signingSessionDrafts/{id}/participants

Request:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane.doe@example.com",
  "deliveryMethods": ["Email"],
  "language": "English"
}

Step 4: Place Signature Fields​

Define where each participant needs to sign. Fields are linked to specific documents and participants using their respective IDs.

Endpoint: POST /api/signingSessionDrafts/{id}/signatureFields

Request:

{
  "documentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "participantId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "type": "Signature",
  "placement": {
    "page": 1,
    "positionX": 100,
    "positionY": 500,
    "sizeX": 150,
    "sizeY": 40
  }
}

Step 5: Convert Draft to Session​

Before starting the session, you must convert the draft into a "Ready to Start" session. This step validates the entire configuration (documents, participants, fields) and locks the draft for further changes.

Endpoint: POST /api/signingSessions/{signingSessionId}

Step 6: Start the Session​

Once the session is in ReadyToStart status, you can trigger the actual start. This changes the status to InProgress and sends notifications to all participants according to their configured delivery methods.

Endpoint: POST /api/signingSessions/{signingSessionId}/started

Best Practices​

  • Error Handling: Check the ApiError response if a step fails. Common issues include invalid coordinates for fields or missing contact info for signers.