Workflows API

The Workflows API allows you to group packages into named workflows for easier management.

Overview

Workflows are named groups of packages that can span across folders. Unlike folders, workflows don't affect where packages are stored — they provide a flexible way to organize packages by business criteria.

Key concepts: A Workflow is a named group of packages. Membership means packages can belong to multiple workflows.

Use cases: Group packages by loan type, status, or client; create audit batches for compliance review; build custom reports by selecting specific packages; track packages that need attention.

Required scopes

Scope	Description
`workflows:read`	View workflows and their packages
`workflows:write`	Create, modify, and delete workflows
`workflows`	Full access (read + write)

List Workflows

Retrieve all workflows in the vault.

GET /api/workflows

Required scope: workflows:read.

Response (200 OK)

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "vaultId": "2fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "High-Value Loans",
    "originalFileName": null,
    "status": "Ready",
    "packageCount": 45,
    "matchedCount": 0,
    "unmatchedCount": 0,
    "errorMessage": null,
    "createdByUserId": "8fa85f64-5717-4562-b3fc-2c963f66afa6",
    "createdByUserName": "Jane Doe",
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": null,
    "csvColumns": []
  }
]

Get Workflow

Retrieve details for a specific workflow.

GET /api/workflows/{id}

Required scope: workflows:read. Path parameter id (guid, required).

Response (200 OK): Returns a WorkflowViewModel object.

Error responses: 404 — Workflow not found.

Create Workflow

Create a new workflow that packages can be added to.

POST /api/workflows

Required scope: workflows:write.

Request body: name (string, required) — Workflow name (max 255 chars).

Response (201 Created): Returns the created WorkflowViewModel.

Error responses: 400 — Name is required; 400 — Name exceeds max length.

Update Workflow

Update a workflow's name.

PATCH /api/workflows/{id}

Required scope: workflows:write. Path parameter id (guid, required).

Request body: name (string, required) — New workflow name (max 255).

Response (200 OK): Returns the updated WorkflowViewModel.

Error responses: 400 — Name already exists in vault; 404 — Workflow not found.

Delete Workflow

Delete a workflow. This does not delete the packages within it.

DELETE /api/workflows/{id}

Required scope: workflows:write. Path parameter id (guid, required).

Response (204 No Content).

Add Packages to Workflow

Add packages to an existing workflow.

POST /api/workflows/{id}/packages

Required scope: workflows:write. Path parameter id (guid, required).

Request body: packageIds (guid[], required) — Package IDs to add (max 1000).

Response (200 OK)

{
  "addedCount": 2,
  "alreadyExistedCount": 0,
  "notFoundCount": 0,
  "totalPackageCount": 47
}

Error responses: 404 — Workflow not found.

Remove Packages from Workflow

Remove packages from a workflow.

POST /api/workflows/{id}/packages/remove

Required scope: workflows:write. Path parameter id (guid, required).

Request body: packageIds (guid[], required) — Package IDs to remove (max 1000).

Response (200 OK)

{
  "removedCount": 1,
  "notInWorkflowCount": 0,
  "totalPackageCount": 46
}

Error responses: 404 — Workflow not found.

Get Workflow Packages

Retrieve packages in a workflow.

GET /api/workflows/{id}/packages

Required scope: workflows:read. Path parameter id (guid, required).

Query parameters

Parameter	Type	Required	Default	Description
`page`	integer	No	1	Page number
`pageSize`	integer	No	25	Items per page (max: 100)
`sortBy`	string	No	—	Sort column: `Name`, `Folder`, or `ImportedAt`
`sortDirection`	string	No	Asc	Sort direction: `Asc` or `Desc`

When no sort column is specified, packages are returned newest-matched-first.

Response (200 OK)

{
  "data": [
    {
      "id": "9fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Loan Package 2024-001",
      "packageType": "AuthoritativeCopy",
      "source": "Api",
      "fileCount": 3,
      "importedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "metadata": { "page": 1, "pageSize": 25, "totalCount": 45 }
}

Download Workflow Packages

Download all packages in a workflow as a CSV file.

GET /api/workflows/{id}/packages/download

Required scope: workflows:read. Path parameter id (guid, required).

Response: Returns a CSV file with columns: Id, Name, Type, Source, Folder, Size, custom vault fields, and ImportedAt.

Response models (Workflows API)

WorkflowViewModel

Field	Type	Description
`id`	guid	Unique identifier
`vaultId`	guid	Vault ID
`name`	string	Workflow name
`originalFileName`	string	Original filename of the uploaded CSV, or null
`status`	string	Processing status (see Workflow Status)
`packageCount`	integer	Total packages in workflow
`matchedCount`	integer	CSV rows that matched existing vault packages
`unmatchedCount`	integer	CSV rows that did not match any vault packages
`errorMessage`	string	Error message if processing failed, otherwise null
`createdByUserId`	guid	Creator user ID
`createdByUserName`	string	Creator display name
`createdAt`	datetime	Creation timestamp (ISO 8601)
`updatedAt`	datetime	Last update timestamp
`csvColumns`	string[]	Column headers from the uploaded CSV (populated when awaiting configuration)

Next: Certified Prints API.