---
title: "Create a document share against an owned grant"
method: POST
path: "/document-shares"
tags: ["Consent and data sharing"]
---

# Create a document share against an owned grant

`POST /document-shares`

## Request

- Base URL: `https://platform-api.homejourney.sg/v1`
- URL: `https://platform-api.homejourney.sg/v1/document-shares`
- Auth: HTTP bearer

Creates a high-risk document share anchored to an active grant the recipient holds. Requires `document_shares.write`. External URL: `/v1/document-shares`. Current Next.js implementation path: `/api/platform/v1/document-shares`. This mutating route requires `Idempotency-Key`. Shares carry manifest metadata and a short-lived handoff TTL only; raw documents, storage paths, and permanent URLs are never accepted or returned.

## Headers

- `X-Correlation-Id` string
- `Idempotency-Key` string, required

## Request body

- CreatePlatformDocumentShareRequest
  - `grant_id` string, uuid, required
  - `document_label` string, required
  - `data_category` 'loan_application_documents' | 'bank_documents' | 'law_firm_document_manifest' | 'regulated_documents' | 'payment_or_payout_status' | 'support_history', required
  - `manifest_summary` object, required
  - `expires_at` string, date-time, required
  - `retention_until` string, date-time, required
  - `purpose` string
  - `handoff_url_ttl_seconds` integer
  - `metadata` object

## Response `201`

Created document share.

- PlatformDocumentShareDetailResponse
  - `document_share` PlatformDocumentShareResource, required: Public-safe document-share record: manifest metadata and a short-lived handoff TTL only. Raw document content, storage paths, and permanent URLs are never included.
    - `id` string, uuid, required
    - `environment` 'sandbox' | 'live', required
    - `grant_id` string, uuid, required
    - `subject_user_id` string, uuid, required
    - `recipient_type` 'ai_host' | 'marketplace_app' | 'bank' | 'law_firm' | 'agent' | 'agency' | 'service_provider' | 'developer' | 'official_source_operator' | 'internal_operator', required
    - `recipient_organization_id` string, uuid, nullable
    - `recipient_client_id` string, uuid, nullable
    - `document_label` string, required
    - `data_category` string, required
    - `purpose` string, required
    - `manifest_summary` object, required
    - `share_status` 'active' | 'expired' | 'revoked' | 'superseded' | 'suspended', required
    - `handoff_url_ttl_seconds` integer, required
    - `last_handoff_at` string, date-time, nullable
    - `expires_at` string, date-time, required
    - `revoked_at` string, date-time, nullable
    - `revocation_reason` string, nullable
    - `retention_until` string, date-time, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `public_safety` PlatformDocumentSharePublicSafety, required: Redaction guarantees applied to every document-share response.
    - `raw_document_content_returned` false, required
    - `storage_paths_returned` false, required
    - `permanent_urls_returned` false, required
    - `internal_audit_ids_returned` false, required
  - `livemode` boolean, required
  - `request_id` string, required

## Other responses

- `400`: Request validation failed.
- `401`: Missing or invalid platform API key.
- `403`: Credential, environment, or scope is not allowed.
- `404`: Platform API feature or resource is not available.
- `409`: Idempotency key is in progress or conflicts with an earlier request body.
- `429`: Rate limit exceeded.
- `500`: Unexpected platform API failure.

---

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