---
title: "Register Deal Document"
method: POST
path: "/api/external/v2/deals/{deal_id}/documents"
tags: ["external-v2-documents"]
---

# Register Deal Document

`POST /api/external/v2/deals/{deal_id}/documents`

## Request

- Base URL: `https://api.lev.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.lev.com/api/external/v2/deals/{deal_id}/documents`
- Auth: none declared

Step 2 of an upload. Same controller calls as a one-item ``createDocuments`` mutation with ``dealId``.

## Path parameters

- `deal_id` integer, required

## Request body

- RegisterDealDocumentRequest: Body for POST /api/external/v2/deals/<deal_id>/documents. Mirrors a single-item ``createDocuments`` mutation with ``dealId`` set. The S3 key is re-derived from ``file_name`` exactly as the mutation does.
  - `file_name` string, required: The same file name passed to the upload step.
  - `company_access_level` 'restricted' | 'company_wide'

## Response `201`

Successful Response

- DocumentObjectResponse: OpenAPI schema for GET /api/external/v2/deals/<deal_id>/documents/<document_id> (object envelope).
  - `request_id` string, required
  - `timestamp` string, required
  - `data` DocumentResponse, required: A single document on a deal. ``id`` is the underlying document id (stable across folder moves) — the same id the download route accepts. ``size_bytes`` may be null for older rows whose size was never persisted. ``vault`` tags which of the deal's vaults the document lives in (a document copied into more than one vault appears once per vault). Uploader attribution and document classification are deliberately omitted from Slice 1 (the listing query does not load those relationships; see the blueprint module docstring).
    - `id` integer, required
    - `file_name` string, nullable
    - `extension` string, nullable
    - `size_bytes` integer, nullable
    - `folder_path` string, nullable
    - `uploaded_at` union
      - string, date-time
      - string
    - `vault` DocumentVaultRef, required: The vault a document lives in, tagged onto each document in a listing. ``type`` is the structural category (``resources`` / ``shared``); ``title`` is the human name ("Deal Resources", "Deal Room", "Closing", …).
      - `id` integer, required
      - `type` 'resources' | 'shared', required
      - `title` string, nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-15** `bf1607c6be7e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/lev/apis/lev-api/changes/api/external/v2/deals/:deal_id/documents/post.md)

---

[API](https://skmtc.dev/lev/apis/lev-api.md) - [All operations](https://skmtc.dev/lev/apis/lev-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lev/apis/lev-api/revisions/6330d0ef0603?raw)