Create a Workflow from a Blueprint (Deep Dive)

The most common way to start a SignStack process is by using a pre-defined Blueprint. This guide provides a detailed look at the POST /workflows/from-blueprint API endpoint and its parameters.

This endpoint acts like a "compiler," taking the reusable Blueprint plan, combining it with your specific transaction data, and creating a live, running Workflow instance.

Endpoint

POST /v1/organizations/{organizationId}/workflows/from-blueprint/{blueprintKey}

organizationId: The ID of your organization (or use me).
blueprintKey: The unique key of the Blueprint you want to use.

Authentication

This endpoint requires a valid, short-lived SignStack JWT Access Token obtained via the /v1/auth/token endpoint. Include it in the Authorization: Bearer <token> header.

Request Body

The request body is a JSON object where you provide the specific data and participants for this one transaction.

JSON

{
  "displayName": "Optional Workflow Name (e.g., Q4 Sales Contract - ACME Corp)",
  "entityData": [
    {
      "key": "clientInfo",
      "data": {
        "companyName": "ACME Corporation",
        "contactEmail": "contact@acme.com",
        "tier": "Enterprise"
      }
    },
    {
      "key": "dealInfo",
      "data": {
        "value": 150000,
        "product": "Enterprise Suite",
        "termMonths": 24
      }
    }
  ],
  "participantMapping": {
    "primaryBuyer": {
      "firstName": "Jane",
      "lastName": "Doe",
      "email": "jane.doe@acme.com"
    },
    "salesRep": {
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@yourcompany.com"
    }
  }
}

Key Request Body Fields:

displayName (Optional string): A human-readable name for this specific Workflow instance. If omitted, a default name might be generated.
entityData (Required array): This array provides the initial data for the Entities required by the Blueprint. Each object in the array must contain:
- key: The key of the entitySlot defined in the Blueprint (e.g., clientInfo).
- data: The full JSON object for that entity. SignStack will validate this data against the Schema specified in the Blueprint's entitySlot.
participantMapping (Required object): This object maps the abstract Roles defined in the Blueprint to real people for this Workflow.
- Keys: The key of the role defined in the Blueprint's roles array (e.g., primaryBuyer).
- Values: An object containing the participant's details:
  - firstName (Required string)
  - lastName (Required string)
  - email (Required string)

Response (Success: `201 Created`)

If the request is successful, SignStack compiles the Blueprint with your provided data, creates the Workflow instance, and starts the first step(s). The response body contains the full Workflow object.

Example Response (truncated):

{
  "id": "wf_123abc456def", // The unique ID of the new Workflow
  "organizationId": "org_...",
  "status": "InProgress", // The workflow has started
  "displayName": "Q4 Sales Contract - ACME Corp",
  "blueprintId": "bp_xyz789", // ID of the source Blueprint version
  "participants": [
    { "participantId": "p_jane_doe_...", "firstName": "Jane", ... },
    { "participantId": "p_john_smith_...", "firstName": "John", ... }
  ],
  "documents": [
    // Details of the specific document instances for this workflow
  ],
  "steps": [
    // The fully resolved execution plan (steps) for this workflow
  ],
  "createdAt": "...",
  "updatedAt": "..."
}

You can now use the returned id to track the status of this Workflow using the GET /workflows/{workflowId} endpoint. The first participant(s) will also receive their email notifications to begin their tasks.