{
  "info": {
    "name": "DocuHelix API",
    "description": "DocuHelix document ingestion API. Authenticate with your API client credentials, then submit documents for asynchronous processing.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://api.docuhelix.com",
      "type": "string"
    },
    {
      "key": "client_id",
      "value": "",
      "type": "string"
    },
    {
      "key": "client_secret",
      "value": "",
      "type": "string"
    },
    {
      "key": "org_uid",
      "value": "",
      "type": "string"
    },
    {
      "key": "access_token",
      "value": "",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "Authentication",
      "item": [
        {
          "name": "Issue Access Token",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "if (pm.response.code === 200) {",
                  "    var json = pm.response.json();",
                  "    pm.collectionVariables.set('access_token', json.access_token);",
                  "    pm.test('Token issued successfully', function () {",
                  "        pm.expect(json.access_token).to.be.a('string');",
                  "        pm.expect(json.token_type).to.eql('bearer');",
                  "        pm.expect(json.expires_in).to.be.a('number');",
                  "    });",
                  "}"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              },
              {
                "key": "X-Tenant-ID",
                "value": "{{org_uid}}"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"client_id\": \"{{client_id}}\",\n  \"client_secret\": \"{{client_secret}}\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/api/v1/auth/token",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "auth", "token"]
            },
            "description": "Exchange API client credentials for a short-lived JWT access token (30 minutes)."
          },
          "response": [
            {
              "name": "200 — Token issued",
              "status": "OK",
              "code": 200,
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJkb2N1aGVsaXgtYXBpLXNlcnZpY2UiLCJzdWIiOiIwMUo5QUJDMTIzREVGNDU2R0hJNzg5SktMTSIsIm9yZyI6IjAxSjhLUDRRWFJOM01WNVlaV1Q2SDJBQkNEIiwic2NvcGVzIjpbImRvY3VtZW50czppbmdlc3QiXX0.signature\",\n  \"token_type\": \"bearer\",\n  \"expires_in\": 1800\n}"
            },
            {
              "name": "401 — Invalid credentials",
              "status": "Unauthorized",
              "code": 401,
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"error\": {\n    \"code\": \"invalid_credentials\",\n    \"message\": \"Invalid client credentials.\"\n  }\n}"
            }
          ]
        }
      ]
    },
    {
      "name": "Ingestion",
      "item": [
        {
          "name": "Submit Document",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{access_token}}"
              },
              {
                "key": "X-Tenant-ID",
                "value": "{{org_uid}}"
              }
            ],
            "body": {
              "mode": "formdata",
              "formdata": [
                {
                  "key": "file",
                  "type": "file",
                  "src": "",
                  "description": "Required. The document file to ingest (max 500 MB)."
                },
                {
                  "key": "industry_key",
                  "value": "mortgage",
                  "type": "text",
                  "description": "Optional. Industry identifier.",
                  "disabled": true
                },
                {
                  "key": "industry_uid",
                  "value": "",
                  "type": "text",
                  "description": "Optional. Industry ULID (26 chars). Validated against tenant config.",
                  "disabled": true
                },
                {
                  "key": "cabinet_uid",
                  "value": "",
                  "type": "text",
                  "description": "Optional. Target cabinet ULID.",
                  "disabled": true
                },
                {
                  "key": "cabinet_name",
                  "value": "",
                  "type": "text",
                  "description": "Optional. Target cabinet name (resolved to UID).",
                  "disabled": true
                },
                {
                  "key": "module_key",
                  "value": "",
                  "type": "text",
                  "description": "Optional. Metadata module key.",
                  "disabled": true
                },
                {
                  "key": "external_source",
                  "value": "my-system",
                  "type": "text",
                  "description": "Optional. Name of the sending system.",
                  "disabled": true
                },
                {
                  "key": "external_reference_id",
                  "value": "",
                  "type": "text",
                  "description": "Optional. Your system's unique ID for this document.",
                  "disabled": true
                },
                {
                  "key": "external_entity_type",
                  "value": "",
                  "type": "text",
                  "description": "Optional. Entity type in your system.",
                  "disabled": true
                },
                {
                  "key": "external_entity_id",
                  "value": "",
                  "type": "text",
                  "description": "Optional. Entity ID in your system.",
                  "disabled": true
                },
                {
                  "key": "raw_document_type",
                  "value": "",
                  "type": "text",
                  "description": "Optional. Your classification label.",
                  "disabled": true
                },
                {
                  "key": "metadata",
                  "value": "{\"key\":\"value\"}",
                  "type": "text",
                  "description": "Optional. Custom metadata as JSON string.",
                  "disabled": true
                },
                {
                  "key": "notes",
                  "value": "",
                  "type": "text",
                  "description": "Optional. Internal notes.",
                  "disabled": true
                }
              ]
            },
            "url": {
              "raw": "{{base_url}}/api/v1/ingestion/documents",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "ingestion", "documents"]
            },
            "description": "Submit a document for asynchronous ingestion. Only the `file` field is required. Enable optional fields as needed."
          },
          "response": [
            {
              "name": "201 — Document accepted",
              "status": "Created",
              "code": 201,
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"data\": {\n    \"uid\": \"01JNQR7V3KXMSW8YBT4FH6PZEA\",\n    \"org_uid\": \"01J8KP4QXRN3MV5YZWT6H2ABCD\",\n    \"api_client_uid\": \"01J9ABC123DEF456GHI789JKLM\",\n    \"correlation_uid\": \"01JNQR7V3KXMSW8YBT4FH6PZEB\",\n    \"status\": \"processing\",\n    \"content_sha256\": \"a3f2b8c1d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1\",\n    \"original_filename\": \"closing-disclosure.pdf\",\n    \"external_source\": \"loan-origination-system\",\n    \"external_reference_id\": \"LOAN-2026-04-00183\",\n    \"external_entity_type\": \"Loan\",\n    \"external_entity_id\": \"loan-78432\",\n    \"raw_document_type\": \"Closing Disclosure\",\n    \"industry_key\": \"mortgage\",\n    \"industry_uid\": null,\n    \"cabinet_uid\": \"01JABC123CABINET456UIDXYZ\",\n    \"module_key\": null,\n    \"received_at\": \"2026-04-03T21:15:00.000000Z\",\n    \"processed_at\": null,\n    \"created_at\": \"2026-04-03T21:15:00.000000Z\",\n    \"updated_at\": \"2026-04-03T21:15:00.000000Z\"\n  }\n}"
            },
            {
              "name": "401 — Missing token",
              "status": "Unauthorized",
              "code": 401,
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"error\": {\n    \"code\": \"missing_token\",\n    \"message\": \"Bearer token is required.\"\n  }\n}"
            },
            {
              "name": "401 — Invalid token",
              "status": "Unauthorized",
              "code": 401,
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"error\": {\n    \"code\": \"invalid_token\",\n    \"message\": \"Token is invalid or expired.\"\n  }\n}"
            },
            {
              "name": "403 — Insufficient scope",
              "status": "Forbidden",
              "code": 403,
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"error\": {\n    \"code\": \"insufficient_scope\",\n    \"message\": \"Token does not have the documents:ingest scope.\"\n  }\n}"
            },
            {
              "name": "403 — Tenant mismatch",
              "status": "Forbidden",
              "code": 403,
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"error\": {\n    \"code\": \"tenant_mismatch\",\n    \"message\": \"Invalid tenant identifier.\"\n  }\n}"
            },
            {
              "name": "422 — Routing validation failed",
              "status": "Unprocessable Entity",
              "code": 422,
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"error\": {\n    \"code\": \"validation_error\",\n    \"message\": \"Validation error\",\n    \"details\": {\n      \"cabinet_uid\": [\"Cabinet not found in this organization.\"],\n      \"module_key\": [\"Module key not found for this organization.\"]\n    }\n  }\n}"
            },
            {
              "name": "429 — Rate limit exceeded",
              "status": "Too Many Requests",
              "code": 429,
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": ""
            },
            {
              "name": "500 — Server error",
              "status": "Internal Server Error",
              "code": 500,
              "header": [
                {
                  "key": "Content-Type",
                  "value": "application/json"
                }
              ],
              "body": "{\n  \"error\": {\n    \"code\": \"server_error\",\n    \"message\": \"An unexpected error occurred.\"\n  }\n}"
            }
          ]
        },
        {
          "name": "Submit Document (Full Routing)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{access_token}}"
              },
              {
                "key": "X-Tenant-ID",
                "value": "{{org_uid}}"
              },
              {
                "key": "Idempotency-Key",
                "value": "los-2026-04-03-loan-78432-cd"
              }
            ],
            "body": {
              "mode": "formdata",
              "formdata": [
                {
                  "key": "file",
                  "type": "file",
                  "src": "",
                  "description": "The document file."
                },
                {
                  "key": "industry_key",
                  "value": "mortgage",
                  "type": "text"
                },
                {
                  "key": "cabinet_uid",
                  "value": "01JABC123CABINET456UIDXYZ",
                  "type": "text"
                },
                {
                  "key": "module_key",
                  "value": "closing-documents",
                  "type": "text"
                },
                {
                  "key": "external_source",
                  "value": "loan-origination-system",
                  "type": "text"
                },
                {
                  "key": "external_reference_id",
                  "value": "LOAN-2026-04-00183",
                  "type": "text"
                },
                {
                  "key": "external_entity_type",
                  "value": "Loan",
                  "type": "text"
                },
                {
                  "key": "external_entity_id",
                  "value": "loan-78432",
                  "type": "text"
                },
                {
                  "key": "raw_document_type",
                  "value": "Closing Disclosure",
                  "type": "text"
                },
                {
                  "key": "metadata",
                  "value": "{\"loan_number\":\"2026-04-00183\",\"borrower\":\"Jane Doe\",\"property_address\":\"123 Main St\"}",
                  "type": "text"
                }
              ]
            },
            "url": {
              "raw": "{{base_url}}/api/v1/ingestion/documents",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "ingestion", "documents"]
            },
            "description": "Example: Mortgage loan origination system submitting a closing disclosure with full routing. Bypasses classification entirely."
          },
          "response": []
        },
        {
          "name": "Submit Document (No Routing)",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Authorization",
                "value": "Bearer {{access_token}}"
              },
              {
                "key": "X-Tenant-ID",
                "value": "{{org_uid}}"
              },
              {
                "key": "Idempotency-Key",
                "value": "workday-export-2026-04-03-emp-4821"
              }
            ],
            "body": {
              "mode": "formdata",
              "formdata": [
                {
                  "key": "file",
                  "type": "file",
                  "src": "",
                  "description": "The document file."
                },
                {
                  "key": "external_source",
                  "value": "workday",
                  "type": "text"
                },
                {
                  "key": "external_reference_id",
                  "value": "EMP-4821-W2-2025",
                  "type": "text"
                },
                {
                  "key": "external_entity_type",
                  "value": "Employee",
                  "type": "text"
                },
                {
                  "key": "external_entity_id",
                  "value": "emp-4821",
                  "type": "text"
                },
                {
                  "key": "raw_document_type",
                  "value": "W-2",
                  "type": "text"
                }
              ]
            },
            "url": {
              "raw": "{{base_url}}/api/v1/ingestion/documents",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "ingestion", "documents"]
            },
            "description": "Example: HR system submitting an employee document with no routing. DocuHelix performs full classification."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Discovery",
      "item": [
        {
          "name": "Get Org Context",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Authorization", "value": "Bearer {{access_token}}" },
              { "key": "X-Tenant-ID", "value": "{{org_uid}}" }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/org",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "org"]
            },
            "description": "Returns authenticated org context including industries and scopes. Requires org:read scope."
          },
          "response": [
            {
              "name": "200 — Org context",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"data\": {\n    \"org_uid\": \"01J8KP4QXRN3MV5YZWT6H2ABCD\",\n    \"api_client_uid\": \"01J9ABC123DEF456GHI789JKLM\",\n    \"scopes\": [\"documents:ingest\", \"org:read\", \"cabinets:read\"],\n    \"industries\": [\n      { \"uid\": \"01JABC...\", \"key\": \"mortgage\", \"name\": \"Mortgage & Lending\" },\n      { \"uid\": \"01JDEF...\", \"key\": \"legal\", \"name\": \"Legal Services\" }\n    ]\n  }\n}"
            }
          ]
        },
        {
          "name": "Get Ingestion Status",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Authorization", "value": "Bearer {{access_token}}" },
              { "key": "X-Tenant-ID", "value": "{{org_uid}}" }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/ingestions/01JNQR7V3KXMSW8YBT4FH6PZEA",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "ingestions", "01JNQR7V3KXMSW8YBT4FH6PZEA"]
            },
            "description": "Check async ingestion/classification/promotion status. Requires ingestions:read scope."
          },
          "response": [
            {
              "name": "200 — Ingestion status",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"data\": {\n    \"ingestion_request_uid\": \"01JNQR7V3KXMSW8YBT4FH6PZEA\",\n    \"status\": \"published\",\n    \"original_filename\": \"closing-disclosure.pdf\",\n    \"content_sha256\": \"a3f2b8c1...\",\n    \"received_at\": \"2026-04-03T21:15:00.000000Z\",\n    \"published_at\": \"2026-04-03T21:15:01.000000Z\",\n    \"classification\": {\n      \"status\": \"classified\",\n      \"suggested_industry\": { \"uid\": \"01JABC...\", \"name\": \"Mortgage & Lending\" },\n      \"suggested_cabinet\": { \"uid\": \"01JCAB...\", \"name\": \"Active Loans\" },\n      \"suggested_module_key\": \"closing_disclosure\",\n      \"confidence\": { \"industry\": 1.0, \"cabinet\": 0.95, \"module\": 1.0 }\n    },\n    \"promotion\": {\n      \"status\": \"promoted\",\n      \"document_uid\": \"01JDOC...\",\n      \"version_uid\": \"01JVER...\"\n    },\n    \"last_error\": null,\n    \"updated_at\": \"2026-04-03T21:15:05.000000Z\"\n  }\n}"
            }
          ]
        },
        {
          "name": "List Cabinets",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Authorization", "value": "Bearer {{access_token}}" },
              { "key": "X-Tenant-ID", "value": "{{org_uid}}" }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/cabinets?per_page=25",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "cabinets"],
              "query": [
                { "key": "industry_uid", "value": "", "disabled": true, "description": "Filter by industry ULID" },
                { "key": "q", "value": "", "disabled": true, "description": "Search by name" },
                { "key": "page", "value": "1", "disabled": true },
                { "key": "per_page", "value": "25" }
              ]
            },
            "description": "List cabinets for the authenticated org. Requires cabinets:read scope."
          },
          "response": [
            {
              "name": "200 — Cabinet list",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"data\": [\n    { \"uid\": \"01JCAB...\", \"name\": \"Active Loans\", \"industry_uid\": \"01JABC...\", \"description\": \"Documents for active loan files\" }\n  ],\n  \"meta\": { \"current_page\": 1, \"last_page\": 1, \"per_page\": 25, \"total\": 1 }\n}"
            }
          ]
        },
        {
          "name": "List Document Types",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Authorization", "value": "Bearer {{access_token}}" },
              { "key": "X-Tenant-ID", "value": "{{org_uid}}" }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/document-types",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "document-types"],
              "query": [
                { "key": "q", "value": "", "disabled": true, "description": "Search by name or key" }
              ]
            },
            "description": "List available document types/module keys. Requires document-types:read scope."
          },
          "response": [
            {
              "name": "200 — Document types",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"data\": [\n    { \"uid\": \"01JMOD...\", \"key\": \"closing_disclosure\", \"name\": \"Closing Disclosure\" },\n    { \"uid\": \"01JMOD...\", \"key\": \"contract\", \"name\": \"Contract\" }\n  ]\n}"
            }
          ]
        },
        {
          "name": "List Documents",
          "request": {
            "method": "GET",
            "header": [
              { "key": "Authorization", "value": "Bearer {{access_token}}" },
              { "key": "X-Tenant-ID", "value": "{{org_uid}}" }
            ],
            "url": {
              "raw": "{{base_url}}/api/v1/documents?per_page=25",
              "host": ["{{base_url}}"],
              "path": ["api", "v1", "documents"],
              "query": [
                { "key": "q", "value": "", "disabled": true, "description": "Search by title" },
                { "key": "cabinet_uid", "value": "", "disabled": true, "description": "Filter by cabinet ULID" },
                { "key": "module_key", "value": "", "disabled": true, "description": "Filter by document type" },
                { "key": "page", "value": "1", "disabled": true },
                { "key": "per_page", "value": "25" }
              ]
            },
            "description": "Search documents for the authenticated org. Requires documents:read scope."
          },
          "response": [
            {
              "name": "200 — Document list",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"data\": [\n    {\n      \"uid\": \"01JDOC...\",\n      \"title\": \"NDA-2026-Partnership.pdf\",\n      \"cabinet_uid\": \"01JCAB...\",\n      \"cabinet_name\": \"Active Loans\",\n      \"module_key\": \"contract\",\n      \"created_by_type\": \"api_client\",\n      \"created_at\": \"2026-04-03T21:15:05.000000Z\"\n    }\n  ],\n  \"meta\": { \"current_page\": 1, \"last_page\": 1, \"per_page\": 25, \"total\": 1 }\n}"
            }
          ]
        }
      ]
    }
  ]
}