Quick Start: Your First Workflow (API)

Quick Start: Your First Workflow (API)

Let's get your first SignStack workflow running using the API! This guide walks you through sending a simple Employee Onboarding packet using a pre-built Blueprint from your Starter Pack.

Goal: Send an onboarding workflow via API in under 5 minutes. ⏱️ Method: Use the

POST /workflows/from-blueprint API endpoint with the required entityData.

Prerequisites

Before you start, make sure you have:

1. A SignStack Account: Sign up if you haven't already. Your account comes pre-loaded with an "Employee Onboarding" Starter Pack.

2. Your API Key: Generate an API Key from your SignStack dashboard (Organization Settings -> Developer -> API Keys). Choose the Test Mode key for this quick start. Copy the key and store it securely – we'll refer to it as <YOUR_API_KEY>.

3. An Access Token: SignStack uses short-lived JWT Access Tokens for API calls. You exchange your long-lived API Key for a temporary Access Token.

   • Get your Access Token: Make a POST request to /v1/auth/token with your API Key.

     curl -X POST https://api.signstack.ai/v1/auth/token \
       -H "Content-Type: application/json" \
       -d '{ "apiKey": "<YOUR_API_KEY>" }'

     bash

   • Store the Token: The response will contain an accessToken. Copy this value – we'll refer to it as <YOUR_ACCESS_TOKEN> in the next step. Keep this token secure; it grants access to your account for a short time (usually 1 hour).

The Scenario: Employee Onboarding

We'll use these assets from your "Starter Pack":

• Blueprint Key: employeeOnboardingV1(Workflow: New Hire signs Offer Letter & Policy Acknowledgment -> HR countersigns.)

• Required Entities: This Blueprint needs two pieces of data:

  • empInfo (using schema employeeInfoSchemaV1)

  • offerData (using schema offerDetailsSchemaV1)

• Required Roles:

  • newHire

  • hrManager

Step 1: Prepare the API Request

We'll use the POST /workflows/from-blueprint endpoint, providing the entityData and participantsInfo in the payload.

Create a file named payload.json with the following content. Replace the placeholder emails with real email addresses you can access.

payload.json:

{
  "entityData": [
    {
      "key": "empInfo",
      "data": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.newhire@example.com"
      }
    },
    {
      "key": "offerData",
      "data": {
        "companyName": "Tech Solutions Inc.",
        "hrRepName": "Alice Admin",
        "positionTitle": "Software Engineer",
        "department": "Technology",
        "startDate": "2025-11-15",
        "baseSalary": 100000
      }
    }
  ],
  "participantMapping": {
    "newHire": {
      "firstName": "John",
      "lastName": "Doe",
      "email": "<NEW_HIRE_EMAIL>"
    },
    "hrManager": {
      "firstName": "Alice",
      "lastName": "Admin",
      "email": "<HR_MANAGER_EMAIL>"
    }
  }
}

• entityData: An array containing the actual data objects. The key in each object (empInfo, offerData) matches the key defined in the Blueprint's entitySlots.

• participantMapping: Assigns real people (with emails) to the roles defined in the Blueprint (newHire, hrManager).

Step 2: Make the API Call

Now, run the following curl command in your terminal. Remember to replace <YOUR_ACCESS_TOKEN> with the actual short-lived JWT you obtained.

curl -X POST \
  https://api.signstack.ai/v1/organizations/me/workflows/from-blueprint/employeeOnboardingV1 \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  --data @payload.json

Step 3: Check the Results!

If the call is successful, you'll receive a 201 Created response containing the details of the newly created Workflow, including its unique id.

Example Response (truncated):

JSON

{
  "id": "wf_123abc456def",
  "organizationId": "org_...",
  "status": "InProgress",
  "displayName": "Standard Employee Onboarding - John Doe",
  // ... participants, documents, steps ...
  "createdAt": "..."
}

Simultaneously, the first participant in the workflow (John Doe, using the email you provided) will receive an email notification prompting them to review and sign the documents. 📧

Congratulations! You've just run your first intelligent agreement workflow with SignStack via the API. 🎉

Next Steps

You've successfully run your first workflow using a pre-built Blueprint! This demonstrates the basic flow of providing data and participants to start an automated process with SignStack.

Now that you've seen it in action, you're ready to dive deeper into the platform's capabilities:

• Explore Core Concepts: Get a solid understanding of the fundamental building blocks like Templates, Schemas, the Step model, and the EntityContext that powers SignStack's data-first approach. This knowledge is key to unlocking the platform's full potential.

• Design Your Own Blueprint: Learn how to move beyond the starter pack and create custom workflows tailored precisely to your business needs, including sequential steps, parallel approvals, and conditional logic.

• Integrate Your Data: Discover the power of onCompleteMappers to make your workflows truly reactive, transforming data and evolving the EntityContext automatically based on participant input or system events.

➡️ Next: Core Concepts: The SignStack Model