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

# Deal Room Documents

> How to upload and manage supporting documents for a securitization deal using the 9Squid API.

The Deal Room is a secure document workspace attached to a securitization deal. Originators use it to upload supporting materials — W9 forms, legal agreements, and other deal documentation — that investors and the platform review as part of the approval process.

## Overview

```
1. POST /v1/api/deals/documents/upload-url   → get a proxied upload URL
2. PUT  <upload_url>                          → stream the document through the gateway
3. POST /v1/api/deals/documents/complete      → register the uploaded file
4. GET  /v1/api/deals/:dealId/documents       → list documents for a securitization deal
5. GET  /v1/api/deals/:dealId/documents/:id   → get document metadata + masked download URL
```

> `:dealId` — the **Securitization Deal ID** returned from `POST /originator/loans` or `GET /originator/loans`.

***

## Step 1 — Get an Upload URL

Request an upload URL for the document. Specify the file name and document type.

```bash theme={null}
curl -X POST "https://api.9squid.com/v1/api/deals/documents/upload-url" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "w9-form.pdf",
    "document_type": "W9_FORM"
  }'
```

**Supported document types:**

| Type         | Description                             |
| ------------ | --------------------------------------- |
| `W9_FORM`    | IRS W-9 form for US tax identification  |
| `LEGAL`      | Legal agreements, NDAs, or side letters |
| `PROSPECTUS` | Deal prospectus or offering memorandum  |
| `OTHER`      | Any other supporting document           |

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "uploadUrl": "https://api.9squid.com/v1/api/originator/loans/upload?u=<token>",
    "fileKey": "upload/documents/onboarding/<uuid>.pdf",
    "expiresIn": 3600,
    "document_type": "W9_FORM"
  }
}
```

> The upload URL routes through the platform gateway — the S3 domain is never exposed to clients.

***

## Step 2 — Upload the Document

Stream the file to the `uploadUrl`. Include your `Authorization` header and `Content-Length`.

```bash theme={null}
curl -X PUT "<uploadUrl>" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Length: <file_size_in_bytes>" \
  --data-binary @w9-form.pdf
```

**Response**

```json theme={null}
{
  "success": true,
  "file_path": "upload/documents/onboarding/<uuid>.pdf"
}
```

> `Content-Length` is required — the gateway streams the body directly to storage and needs the size upfront.

***

## Step 3 — Complete the Upload

Register the uploaded file against the document record.

```bash theme={null}
curl -X POST "https://api.9squid.com/v1/api/deals/documents/complete" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "w9-form.pdf",
    "fileKey": "upload/documents/onboarding/<uuid>.pdf",
    "document_type": "W9_FORM"
  }'
```

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "document_id": "clxdoc001",
    "status": "uploaded",
    "document_type": "W9_FORM"
  }
}
```

***

## Step 4 — List Documents for a Deal

Retrieve all documents uploaded to a securitization deal, grouped by document type.

```bash theme={null}
curl "https://api.9squid.com/v1/api/deals/clx1a2b3c4d5e6f7g8h9/documents" \
  -H "Authorization: Bearer <your_token>"
```

> `clx1a2b3c4d5e6f7g8h9` is the **Securitization Deal ID** from `POST /originator/loans`.

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "loan_tape": {
      "folderName": "Loan Tapes",
      "documents": [{ "document_id": "clxdoc001", "documentType": "loan_tape" }],
      "count": 1
    },
    "legal": {
      "folderName": "Legal Documents",
      "documents": [],
      "count": 0
    }
  }
}
```

***

## Step 5 — Download a Document

Fetch full metadata and a masked download URL for a specific document.

```bash theme={null}
curl "https://api.9squid.com/v1/api/deals/clx1a2b3c4d5e6f7g8h9/documents/clxdoc001" \
  -H "Authorization: Bearer <your_token>"
```

**Response**

```json theme={null}
{
  "success": true,
  "data": {
    "document_id": "clxdoc001",
    "documentType": "loan_tape",
    "downloadUrl": "https://api.9squid.com/v1/api/download?u=<token>",
    "downloadUrlExpiresAt": "2026-04-21T11:00:00Z"
  }
}
```

Use the `downloadUrl` to stream the file through the gateway. The underlying S3 URL is never exposed.

***

## Webhook Notification

Subscribe to `document.uploaded` to be notified when a document is processed:

```json theme={null}
{
  "event": "document.uploaded",
  "timestamp": "2026-04-21T10:30:00Z",
  "data": {
    "deal_id": "clx1a2b3c4d5e6f7g8h9",
    "document_id": "clxdoc001",
    "type": "W9_FORM",
    "status": "UPLOADED"
  }
}
```

See the [Webhooks](/workflows/webhooks) guide for setup instructions.

***

## What's Next

* [Create a Deal](/workflows/create-a-deal) — submit a loan tape before uploading deal room documents
* [Webhooks](/workflows/webhooks) — subscribe to `document.uploaded` events for real-time notifications