---
title: "List recipient-scoped document shares"
method: GET
path: "/document-shares"
tags: ["Consent and data sharing"]
---

# List recipient-scoped document shares

`GET /document-shares`

## Request

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

Returns the document shares where the authenticated organization is the recipient. Requires `document_shares.read`. External URL: `/v1/document-shares`. Current Next.js implementation path: `/api/platform/v1/document-shares`. This read-only route does not require `Idempotency-Key`; manifest metadata only, never raw documents or storage paths.

## Query parameters

- `grant_id` string, uuid

## Headers

- `X-Correlation-Id` string

## Response `200`

Recipient-scoped document shares.

- PlatformDocumentShareListResponse
  - `document_shares` PlatformDocumentShareResource[], required
    - `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.
- `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)