> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simpledocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Discover and inspect workflows to create legal requests

Workflows define the structure of a legal process — who signs, what variables are required, and what document is used. Before creating a request, you need to find a published workflow and understand what it expects.

## Listing workflows

Use the [List workflows](/api-reference/workflows/list-workflows) endpoint to retrieve all workflows for your company:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl https://app.simpledocs.com/api/v1/workflows \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "data": [
    {
      "id": "k9Xp2m",
      "type": "workflow",
      "attributes": {
        "name": "NDA — Mutual",
        "description": "Mutual non-disclosure agreement for partnerships",
        "status": "published",
        "type": "generated"
      }
    },
    {
      "id": "rT7vWx",
      "type": "workflow",
      "attributes": {
        "name": "Vendor Agreement",
        "description": "Standard agreement for new vendor onboarding",
        "status": "published",
        "type": "generated"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 1,
    "total_count": 2
  }
}
```

You can filter to only published workflows by adding `?status=published`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl "https://app.simpledocs.com/api/v1/workflows?status=published" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Getting a workflow's schema

Before creating a request, fetch the workflow schema to discover exactly which fields and variables are required. Use the [Get workflow schema](/api-reference/workflows/get-workflow-schema) endpoint:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
curl https://app.simpledocs.com/api/v1/workflows/k9Xp2m/schema \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "name": "NDA — Mutual",
  "description": "Mutual non-disclosure agreement for partnerships",
  "required_fields": [
    "workflow_id",
    "requester_email",
    "counterparty_name",
    "counterparty_email",
    "counterparty_organization_name",
    "internal_signer_email"
  ],
  "optional_fields": [
    "support_documents[]",
    "merge_documents_into_pdf"
  ],
  "required_variables": ["purpose"],
  "fields_properties": {
    "workflow_id": {
      "required": true,
      "properties": { "type": "string" }
    },
    "requester_email": {
      "required": true,
      "properties": { "type": "string" }
    },
    "counterparty_name": {
      "required": true,
      "properties": { "type": "string" }
    },
    "counterparty_email": {
      "required": true,
      "properties": { "type": "string" }
    },
    "counterparty_organization_name": {
      "required": true,
      "properties": { "type": "string" }
    },
    "support_documents[]": {
      "required": false,
      "properties": { "type": "file" }
    },
    "internal_signer_email": {
      "required": true,
      "properties": {
        "type": "string",
        "options": ["alice@yourcompany.com", "carol@yourcompany.com"]
      }
    },
    "merge_documents_into_pdf": {
      "required": false,
      "properties": { "type": "boolean" }
    }
  },
  "variables_properties": {
    "purpose": {
      "required": true,
      "properties": {
        "type": "string"
      }
    },
    "duration": {
      "required": false,
      "properties": {
        "type": "integer"
      }
    },
    "duration_unit": {
      "required": false,
      "properties": {
        "type": "string",
        "options": ["month", "year"]
      }
    }
  }
}
```

### Multi-signer workflows

When a workflow supports multiple internal signers, `internal_signer_emails[]` replaces `internal_signer_email` in the schema. It appears in `required_fields` and accepts an ordered array of signer emails.

```json theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
{
  "required_fields": [
    "workflow_id",
    "requester_email",
    "counterparty_name",
    "counterparty_email",
    "counterparty_organization_name",
    "internal_signer_emails[]"
  ],
  "optional_fields": ["support_documents[]", "merge_documents_into_pdf"],
  "fields_properties": {
    "internal_signer_emails[]": {
      "required": true,
      "properties": {
        "type": "array",
        "options": ["alice@yourcompany.com", "carol@yourcompany.com", "eve@yourcompany.com"]
      }
    }
  }
}
```

Check `options` for the list of valid signer emails before creating a request.

### Reading the schema

| Field                  | Description                                                    |
| ---------------------- | -------------------------------------------------------------- |
| `required_fields`      | Top-level fields you must include when calling Create request. |
| `optional_fields`      | Optional top-level fields the workflow accepts.                |
| `required_variables`   | Keys that must appear inside the `variables` object.           |
| `fields_properties`    | Type information for each top-level field.                     |
| `variables_properties` | Type information and available options for each variable.      |

Use this schema to build the correct Create request payload. See the [Requests](/requests-guide) guide for a full example.