---
updatedAt: 2026-04-09T13:37:24.000Z
agentTools:
  projectIndex: https://developer.onerecord.com/llms.txt
---

# Document Retrieve

Receives an inbound document retrieve request from an external network participant. The requesting party provides document identifiers obtained from a prior document query to retrieve the actual documents. Matching documents (C-CDAs, PDFs, etc.) are returned as Base64-encoded payloads in the response.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "OneRecord API Integrator Services",
    "description": "REST API services for OneRecord API Integrator version",
    "license": {
      "name": "OneRecord Licensed Product",
      "url": "https://onerecord.com/policies/terms"
    },
    "version": "2.0"
  },
  "externalDocs": {
    "description": "OneRecord API Documentation",
    "url": "https://developer.onerecord.com/password?redirect=/reference#integrator-service-controller"
  },
  "servers": [
    {
      "url": "https://stage.integrator.onerecord.com/integrator"
    }
  ],
  "tags": [
    {
      "name": "Responding Gateway Network Services",
      "description": "Network Service for responding to IHE requests"
    }
  ],
  "paths": {
    "/v2/gateway/document/retrieve": {
      "post": {
        "tags": [
          "Responding Gateway Network Services"
        ],
        "summary": "Document Retrieve",
        "description": "Receives an inbound document retrieve request from an external network participant. The requesting party provides document identifiers obtained from a prior document query to retrieve the actual documents. Matching documents (C-CDAs, PDFs, etc.) are returned as Base64-encoded payloads in the response.",
        "operationId": "respondingGatewayRetrieveDocumentsV2",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NetworkRespondingGatewayDocumentRetrieveRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK",
            "headers": {
              "OneRecord-Transaction-ID": {
                "description": "An ID generated by OneRecord to track the execution of the request",
                "style": "simple",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/hal+json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentRetrieveResponseWrapper"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/hal+json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object"
                    },
                    {
                      "$ref": "#/components/schemas/ServiceExceptionResponse"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/hal+json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceExceptionResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/hal+json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceExceptionResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/hal+json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceExceptionResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer-key": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ServiceExceptionResponse": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "format": "int32"
          },
          "error": {
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "message": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        }
      },
      "NetworkDocument": {
        "required": [
          "documentUniqueId"
        ],
        "type": "object",
        "properties": {
          "documentUniqueId": {
            "type": "string"
          },
          "repositoryUniqueId": {
            "type": "string"
          },
          "homeCommunityId": {
            "type": "string"
          }
        }
      },
      "Classification": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "codingScheme": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "Document": {
        "type": "object",
        "properties": {
          "documentUniqueId": {
            "type": "string"
          },
          "repositoryUniqueId": {
            "type": "string"
          },
          "homeCommunityId": {
            "type": "string"
          },
          "hash": {
            "type": "string"
          },
          "size": {
            "type": "string"
          },
          "mimeType": {
            "type": "string"
          },
          "classCode": {
            "$ref": "#/components/schemas/Classification"
          },
          "creationTime": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "comments": {
            "type": "string"
          },
          "serviceStartTime": {
            "type": "string"
          },
          "serviceStopTime": {
            "type": "string"
          },
          "languageCode": {
            "type": "string"
          },
          "legalAuthenticator": {
            "type": "string"
          },
          "authorInstitution": {
            "type": "string"
          },
          "authorPerson": {
            "type": "string"
          },
          "formatCode": {
            "$ref": "#/components/schemas/Classification"
          },
          "healthCareFacilityTypeCode": {
            "$ref": "#/components/schemas/Classification"
          },
          "status": {
            "type": "string"
          },
          "availability": {
            "type": "string"
          },
          "type": {
            "type": "string"
          },
          "practiceSettingCode": {
            "$ref": "#/components/schemas/Classification"
          },
          "typeCode": {
            "$ref": "#/components/schemas/Classification"
          },
          "confidentialityCode": {
            "$ref": "#/components/schemas/Classification"
          },
          "patientIdentifier": {
            "type": "string"
          },
          "document": {
            "type": "string"
          }
        }
      },
      "DocumentRetrieveResponse": {
        "type": "object",
        "properties": {
          "networkRequestId": {
            "type": "string"
          },
          "networkName": {
            "type": "string"
          },
          "document": {
            "$ref": "#/components/schemas/Document"
          },
          "error": {
            "$ref": "#/components/schemas/Error"
          }
        }
      },
      "DocumentRetrieveResponseWrapper": {
        "type": "object",
        "properties": {
          "clientRequestId": {
            "type": "string"
          },
          "responses": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DocumentRetrieveResponse"
            }
          }
        }
      },
      "Network": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "purposeOfUse": {
            "type": "string"
          },
          "initiatingOrganization": {
            "$ref": "#/components/schemas/NetworkOrganization"
          },
          "respondingOrganization": {
            "$ref": "#/components/schemas/NetworkOrganization"
          },
          "initiatingUser": {
            "$ref": "#/components/schemas/NetworkUser"
          }
        }
      },
      "NetworkOrganization": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "identifier": {
            "type": "string"
          }
        }
      },
      "NetworkUser": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "role": {
            "type": "string"
          }
        }
      },
      "NetworkRespondingGatewayDocumentRetrieveRequest": {
        "required": [
          "documents",
          "network"
        ],
        "type": "object",
        "properties": {
          "initiatorRequestId": {
            "type": "string",
            "description": "Optional field that can be used to track the request. If provided, this value will be included in the response for logging and troubleshooting purposes."
          },
          "network": {
            "$ref": "#/components/schemas/Network"
          },
          "documents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/NetworkDocument"
            }
          }
        },
        "example": {
          "initiatorRequestId": "794e5f40-880b-11f0-8c11-4a19a2fc2817",
          "documents": [
            {
              "documentUniqueId": "1e7d85ed-aabe-43cf-94ca-2388a3e33f23",
              "repositoryUniqueId": "2.16.840.1.113883.3.7080.2.4.1003.101.1",
              "homeCommunityId": "2.16.840.1.113883.3.7080.1.3"
            }
          ],
          "network": {
            "name": "Carequality",
            "purposeOfUse": "TREATMENT",
            "initiatingOrganization": {
              "name": "OneRecord, LLC",
              "identifier": "urn:oid:2.16.840.1.113883.3.7080.1.4"
            },
            "initiatingUser": {
              "name": "Test User",
              "email": "testemail@onerecord.com"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearer-key": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  },
  "x-explorer-enabled": true,
  "x-proxy-enabled": true,
  "x-samples-enabled": true,
  "x-sample_langugages": [
    "curl",
    "node",
    "ruby",
    "javascript",
    "python"
  ]
}
```