---
title: "Create document folder"
method: POST
path: "/documents/folder-create"
tags: ["Document AI — DMS"]
---

# Create document folder

`POST /documents/folder-create`

## Request

- Base URL: `https://api.paperoffice.ai/latest`
- URL: `https://api.paperoffice.ai/latest/documents/folder-create`
- Auth: HTTP bearer

Bundle at least two existing documents (POFIDs) into a stapled folder/heft in the Headless DMS. This is not an empty directory create — it links documents that already exist.

## Request body

- object
  - `pofids` string[], required: List the PaperOffice-Document IDs (POFIDs) that are to be summarized in the folder. At least 2 are required.
  - `folder_name` string: Name of the document folder. If empty, it is automatically generated (e.g., '3 linked Documents').
  - `folder_type` 'staple' | 'binder': Folder type: staple (stapled stack) or binder (ring binder).
  - `folder_description` string: Optional description for the document folder.
  - `parent_pofid` string: POFParent document ID. Default: first document in the list.

## Response `200`

Success

- object: Create document folder (stapling)
  - `status` 'success' | 'error', required: HTTP-Level Status
  - `job_id` string, required
  - `message` string: Human-readable status message
  - `pipeline` string: Name of the executed pipeline
  - `operation` string: Executed operation
  - `processing_time` string: Total processing time including queue (format: 123.45ms)
  - `result` object, required: The actual processing result
    - `status` 'completed' | 'failed' | 'timeout': Job-Level Status
    - `message` string: Pipeline-specific status message
    - `duration_ms` string: Pure pipeline processing time in ms
    - `output` object: Output
      - `folder_id` string
      - `document_count` number

## Other responses

- `4XX`: Error
- `5XX`: Error

---

[API](https://skmtc.dev/paperoffice/apis/paperoffice-ai-api.md) · [All operations](https://skmtc.dev/paperoffice/apis/paperoffice-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/paperoffice/apis/paperoffice-ai-api/revisions/c6a6228a4509?raw)