---
title: "Fetch exact raw bytes, parser structure, a typed document, or approved mapped output."
method: GET
path: "/v1/documents/{documentId}/payload"
tags: ["Documents"]
---

# Fetch exact raw bytes, parser structure, a typed document, or approved mapped output.

`GET /v1/documents/{documentId}/payload`

## Request

- Base URL: `https://signaledi.com/api`
- URL: `https://signaledi.com/api/v1/documents/{documentId}/payload`
- Auth: HTTP bearer

Credentials can read documents only in their exact Lab, Certification, or Production lane. `document` is available only where the registry proves typed receive; `mapped` is the approved customer mapping and `canonical` is its alias. Healthcare (PHI-classified) payloads are masked by default: every JSON view reports `masked`/`revealed`, and a raw download carries `X-SignalEDI-Masked`. Only an interactive dashboard session holding the reveal permission may pass `reveal=true`; API keys are refused with 403 PAYLOAD_REVEAL_FORBIDDEN before any tenant data is read, and a reveal that cannot be audited is refused with 503. Throttled at 120 calls per minute per API key.

## Path parameters

- `documentId` string, required

## Query parameters

- `reveal` 'true' | '1'
- `view` 'raw' | 'structured' | 'document' | 'mapped' | 'canonical'
- `download` boolean

## Response `200`

Authorized document payload view. With `download=true` on the raw view the exact (or masked) bytes are returned with the headers below.

- DocumentPayloadResult
  - `ok` true, required
  - `documentId` string, required
  - `transactionId` string
  - `view` 'raw' | 'structured' | 'document' | 'mapped', required
  - `environment` 'LAB' | 'CERTIFICATION' | 'PRODUCTION', required: The exact isolated lane identifier. The API route and payload remain the same. Lab is customer-to-Signal only; Certification uses the real third-party test route; Production is approved live exchange. SANDBOX is a historical request-only alias for Certification. Promotion creates an approved immutable version and never relabels traffic.
  - `standard` 'x12' | 'edifact' | 'X12' | 'EDIFACT', required
  - `direction` 'CUSTOMER_TO_PARTNER' | 'PARTNER_TO_CUSTOMER'
  - `documentTypeCode` string
  - `documentTypeCodes` string[], required
  - `schemaVersion` string
  - `payload` union
    - object
    - string
  - `transactions` object[]
  - `contentBase64` string
  - `contentEncoding` 'UTF-8' | 'ISO-8859-1'
  - `byteLength` integer
  - `sha256` string
  - `validation` ValidationSummary
    - `sourceFormat` 'X12' | 'EDIFACT', required
    - `valid` boolean, required
    - `errors` string[], required
    - `issues` ValidationIssue[]: Additive actionable diagnostics; legacy errors remain unchanged.
      - `code` string, required
      - `severity` 'error' | 'warning', required
      - `message` string, required
      - `suggestedAction` string, required
      - `segmentId` string
      - `segmentPosition` integer
      - `elementPosition` integer
      - `ruleRef` string
      - `correlationId` string
    - `transactionSet` string, required
    - `recognized` boolean, required
    - `semanticValidation` 'supported' | 'unsupported' | 'unknown', required: Semantic-validation capability, reported independently from catalog recognition.
    - `transactionSets` object[], required: One validation entry for every ST/SE transaction set.
      - `transactionSet` string, required
      - `controlNumber` string, required
      - `segmentCount` integer, required
      - `recognized` boolean, required
      - `semanticValidation` 'supported' | 'unsupported' | 'unknown', required
      - `valid` boolean, required
      - `sourceMessageType` string
      - `sourceMessageReference` string
    - `controlNumber` string, required
    - `segmentCount` integer, required
  - `masked` boolean: True when the payload contains healthcare-classified content that was masked before delivery. Non-sensitive payloads report false.
  - `revealed` boolean: True only after a gated, audited `reveal=true` succeeded for an interactive session; always false for API keys.

## Other responses

- `400`: `view` is not one of the documented values (`code` INVALID_PAYLOAD_VIEW).
- `401`: Missing or invalid API key (`code` AUTH_UNAUTHORIZED).
- `403`: Standard 403 causes (see Forbidden), or `reveal=true` was requested by a credential that may never reveal — any API key, or a session whose role lacks the reveal permission (`code` PAYLOAD_REVEAL_FORBIDDEN). The refusal happens before any tenant data is read.
- `404`: The document is not owned by the caller's workspace, is not readable in the key's exact lane, or the id is malformed (`code` DOCUMENT_NOT_FOUND); the workspace could not be resolved (WORKSPACE_NOT_FOUND); or the /v1 platform is disabled (NOT_FOUND).
- `409`: The requested view is unavailable (`code` MAPPED_VIEW_UNAVAILABLE, DOCUMENT_VIEW_UNAVAILABLE, PAYLOAD_NOT_READY, or DOCUMENT_ENCODING_INVALID). DOCUMENT_VIEW_UNAVAILABLE bodies add `supportedViews` and the registry `capabilities`.
- `429`: Rate limit exceeded (`code` RATE_LIMITED).
- `500`: Unexpected server error (`code` e.g. PARSE_FAILED, VALIDATE_FAILED, OUTBOUND_FAILED, INBOUND_FAILED, BATCH_FAILED, TRANSACTIONS_FAILED, DOCUMENT_RECEIPT_FAILED, DOCUMENT_PAYLOAD_FAILED). Sanitized bodies carry an opaque `correlationId` to quote to support; internal error text is never echoed.
- `503`: A permitted reveal could not be durably audited, so the unmasked payload was not released (`code` PAYLOAD_REVEAL_AUDIT_UNAVAILABLE). Retry later or read the masked view.

---

[API](https://skmtc.dev/signaledi/apis/signaledi-developer-api.md) · [All operations](https://skmtc.dev/signaledi/apis/signaledi-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/signaledi/apis/signaledi-developer-api/revisions/9bc596644a10?raw)