# Documents

## Get a Document

> Retrieve a specific document for the specified merchant by document ID. 
> \
> The value provided in the MerchantId header must match the merchantNumber specified in the URL.

```json
{"openapi":"3.0.1","info":{"title":"EDocs Reporting API - US Onboarding","version":"1.0"},"paths":{"/api/documents/v1.0/document/{merchantNumber}/{documentId}":{"get":{"tags":["Documents"],"summary":"Get a Document","description":"Retrieve a specific document for the specified merchant by document ID. \r\nThe value provided in the MerchantId header must match the merchantNumber specified in the URL.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}},{"name":"documentId","in":"path","description":"Document ID of the document to be retrieved.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Returns the document as a file stream."},"500":{"description":"Error occurred retrieving the document.","content":{"application/octet-stream":{"schema":{"$ref":"#/components/schemas/ErrorResults"}}}}}}}},"components":{"schemas":{"ErrorResults":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ReportingError"},"nullable":true},"statusCode":{"type":"integer","format":"int32"}},"additionalProperties":false},"ReportingError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"A human readable description of the error that occurred. These descriptions are subject to change and may be\r\nupdated to better reflect different scenarios. ResultCode should be used instead if any programmatic handling\r\nof errors is needed.","nullable":true},"resultCode":{"type":"integer","description":"A numeric identifier for the error.","format":"int32"},"timeStamp":{"type":"string","description":"The time at which the error occurred expressed as Coordinated Universal Time (UTC).","format":"date-time","readOnly":true}},"additionalProperties":false}}}}
```

## Get Document Types

> Retrieve a list of available document types for the specified merchant. 
> \
> The MerchantId value provided in the request header must match the merchantNumber specified in the URL

```json
{"openapi":"3.0.1","info":{"title":"EDocs Reporting API - US Onboarding","version":"1.0"},"paths":{"/api/documents/v1.0/document/{merchantNumber}/DocumentTypes":{"get":{"tags":["Documents"],"summary":"Get Document Types","description":"Retrieve a list of available document types for the specified merchant. \r\nThe MerchantId value provided in the request header must match the merchantNumber specified in the URL","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns a list of document types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentTypes"}}}},"500":{"description":"Error occurred retrieving document types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResults"}}}}}}}},"components":{"schemas":{"DocumentTypes":{"type":"object","properties":{"types":{"type":"array","items":{"$ref":"#/components/schemas/CategoryDetails"},"description":"An array containing the set of document categories available.","nullable":true}},"additionalProperties":false},"CategoryDetails":{"type":"object","properties":{"id":{"type":"integer","description":"The numeric id of this document category.","format":"int32"},"name":{"type":"string","description":"The name of this document category","nullable":true},"description":{"type":"string","description":"A description of this document category.","nullable":true}},"additionalProperties":false,"description":"The category that this document was classified under when uploaded.\r\nA list of the available document categories can be retrieved by calling the Get Document Types endpoint."},"ErrorResults":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ReportingError"},"nullable":true},"statusCode":{"type":"integer","format":"int32"}},"additionalProperties":false},"ReportingError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"A human readable description of the error that occurred. These descriptions are subject to change and may be\r\nupdated to better reflect different scenarios. ResultCode should be used instead if any programmatic handling\r\nof errors is needed.","nullable":true},"resultCode":{"type":"integer","description":"A numeric identifier for the error.","format":"int32"},"timeStamp":{"type":"string","description":"The time at which the error occurred expressed as Coordinated Universal Time (UTC).","format":"date-time","readOnly":true}},"additionalProperties":false}}}}
```

## Get Documents by Type

> Retrieve a list of documents associated with the specified merchant, filtered by document type.
> \
> You can use either the documentTypeName or documentTypeId query parameter, but not both.
> \
> If you use documentTypeName, make sure it is URL-encoded before including it in the request.
> \
> The MerchantId value provided in the request header must match the merchantNumber specified in the URL.

```json
{"openapi":"3.0.1","info":{"title":"EDocs Reporting API - US Onboarding","version":"1.0"},"paths":{"/api/documents/v1.0/document/{merchantNumber}/Documents":{"get":{"tags":["Documents"],"summary":"Get Documents by Type","description":"Retrieve a list of documents associated with the specified merchant, filtered by document type.\r\nYou can use either the documentTypeName or documentTypeId query parameter, but not both.\r\nIf you use documentTypeName, make sure it is URL-encoded before including it in the request.\r\nThe MerchantId value provided in the request header must match the merchantNumber specified in the URL.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}},{"name":"documentTypeId","in":"query","description":"A unique identifier of the document type.","schema":{"type":"string"}},{"name":"documentTypeName","in":"query","description":"A name of the document type.","schema":{"type":"string"}}],"responses":{"200":{"description":"Returns a list of documents filtered by type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResult"}}}},"400":{"description":"Both documentTypeId and documentTypeName were passed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResults"}}}},"500":{"description":"Error occurred retrieving documents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResults"}}}}}}}},"components":{"schemas":{"DocumentResult":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/DocumentMetadata"},"nullable":true}},"additionalProperties":false,"description":"An array containing the set of document categories available."},"DocumentMetadata":{"type":"object","properties":{"documentId":{"type":"string","description":"A GUID that identifies this specific document.","format":"uuid"},"merchantNumber":{"type":"string","description":"The Merchant Number that this document is associated with.","nullable":true},"name":{"type":"string","description":"The name of the document.","nullable":true},"description":{"type":"string","description":"An optional description of the document.","nullable":true},"category":{"$ref":"#/components/schemas/CategoryDetails"},"additionalProperties":{"type":"object","additionalProperties":{"type":"string","description":"Additional properties"},"description":"An dictionary containing additional metadata about this document. Metadata will often include the Month and Year\r\nfor which a particular document was generated, however thse fields may be missing depending on the type of document \r\nand the age of the document being requested. Any code using this should handle the situation where those fields are\r\nnot present.","nullable":true,"readOnly":true},"documentURL":{"type":"string","description":"The URL that can be used to download the document.","nullable":true}},"additionalProperties":false},"CategoryDetails":{"type":"object","properties":{"id":{"type":"integer","description":"The numeric id of this document category.","format":"int32"},"name":{"type":"string","description":"The name of this document category","nullable":true},"description":{"type":"string","description":"A description of this document category.","nullable":true}},"additionalProperties":false,"description":"The category that this document was classified under when uploaded.\r\nA list of the available document categories can be retrieved by calling the Get Document Types endpoint."},"ErrorResults":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ReportingError"},"nullable":true},"statusCode":{"type":"integer","format":"int32"}},"additionalProperties":false},"ReportingError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"A human readable description of the error that occurred. These descriptions are subject to change and may be\r\nupdated to better reflect different scenarios. ResultCode should be used instead if any programmatic handling\r\nof errors is needed.","nullable":true},"resultCode":{"type":"integer","description":"A numeric identifier for the error.","format":"int32"},"timeStamp":{"type":"string","description":"The time at which the error occurred expressed as Coordinated Universal Time (UTC).","format":"date-time","readOnly":true}},"additionalProperties":false}}}}
```

## Get Statements by Year

> Retrieve all statements for the specified merchant for the given year.

```json
{"openapi":"3.0.1","info":{"title":"EDocs Reporting API - US Onboarding","version":"1.0"},"paths":{"/api/documents/v1.0/document/{merchantNumber}/Statements/{year}":{"get":{"tags":["Documents"],"summary":"Get Statements by Year","description":"Retrieve all statements for the specified merchant for the given year.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}},{"name":"year","in":"path","description":"A year for which to retrieve statements.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns a list of statements for the given year.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResult"}}}},"400":{"description":"Returned when an invalid year was passed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResults"}}}},"500":{"description":"Returned when an error occurred retrieving statements.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResults"}}}}}}}},"components":{"schemas":{"DocumentResult":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/DocumentMetadata"},"nullable":true}},"additionalProperties":false,"description":"An array containing the set of document categories available."},"DocumentMetadata":{"type":"object","properties":{"documentId":{"type":"string","description":"A GUID that identifies this specific document.","format":"uuid"},"merchantNumber":{"type":"string","description":"The Merchant Number that this document is associated with.","nullable":true},"name":{"type":"string","description":"The name of the document.","nullable":true},"description":{"type":"string","description":"An optional description of the document.","nullable":true},"category":{"$ref":"#/components/schemas/CategoryDetails"},"additionalProperties":{"type":"object","additionalProperties":{"type":"string","description":"Additional properties"},"description":"An dictionary containing additional metadata about this document. Metadata will often include the Month and Year\r\nfor which a particular document was generated, however thse fields may be missing depending on the type of document \r\nand the age of the document being requested. Any code using this should handle the situation where those fields are\r\nnot present.","nullable":true,"readOnly":true},"documentURL":{"type":"string","description":"The URL that can be used to download the document.","nullable":true}},"additionalProperties":false},"CategoryDetails":{"type":"object","properties":{"id":{"type":"integer","description":"The numeric id of this document category.","format":"int32"},"name":{"type":"string","description":"The name of this document category","nullable":true},"description":{"type":"string","description":"A description of this document category.","nullable":true}},"additionalProperties":false,"description":"The category that this document was classified under when uploaded.\r\nA list of the available document categories can be retrieved by calling the Get Document Types endpoint."},"ErrorResults":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ReportingError"},"nullable":true},"statusCode":{"type":"integer","format":"int32"}},"additionalProperties":false},"ReportingError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"A human readable description of the error that occurred. These descriptions are subject to change and may be\r\nupdated to better reflect different scenarios. ResultCode should be used instead if any programmatic handling\r\nof errors is needed.","nullable":true},"resultCode":{"type":"integer","description":"A numeric identifier for the error.","format":"int32"},"timeStamp":{"type":"string","description":"The time at which the error occurred expressed as Coordinated Universal Time (UTC).","format":"date-time","readOnly":true}},"additionalProperties":false}}}}
```

## Get Statements by Year and Month

> Retrieves all statements for the specified merchant for a given year and month.
> \
> The MerchantId value provided in the request header must match the merchantNumber specified in the URL.

```json
{"openapi":"3.0.1","info":{"title":"EDocs Reporting API - US Onboarding","version":"1.0"},"paths":{"/api/documents/v1.0/document/{merchantNumber}/Statements/{year}/{month}":{"get":{"tags":["Documents"],"summary":"Get Statements by Year and Month","description":"Retrieves all statements for the specified merchant for a given year and month.\r\nThe MerchantId value provided in the request header must match the merchantNumber specified in the URL.","parameters":[{"name":"merchantNumber","in":"path","description":"The merchant's unique identification number.","required":true,"schema":{"type":"string"}},{"name":"year","in":"path","description":"A year for which to retrieve statements.","required":true,"schema":{"type":"string"}},{"name":"month","in":"path","description":"A month for which to retrieve statements.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns a list of statements for the given year and month.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentResult"}}}},"400":{"description":"Returned when an invalid year or month was passed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResults"}}}},"500":{"description":"Returned when an error occurred retrieving statements.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResults"}}}}}}}},"components":{"schemas":{"DocumentResult":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/DocumentMetadata"},"nullable":true}},"additionalProperties":false,"description":"An array containing the set of document categories available."},"DocumentMetadata":{"type":"object","properties":{"documentId":{"type":"string","description":"A GUID that identifies this specific document.","format":"uuid"},"merchantNumber":{"type":"string","description":"The Merchant Number that this document is associated with.","nullable":true},"name":{"type":"string","description":"The name of the document.","nullable":true},"description":{"type":"string","description":"An optional description of the document.","nullable":true},"category":{"$ref":"#/components/schemas/CategoryDetails"},"additionalProperties":{"type":"object","additionalProperties":{"type":"string","description":"Additional properties"},"description":"An dictionary containing additional metadata about this document. Metadata will often include the Month and Year\r\nfor which a particular document was generated, however thse fields may be missing depending on the type of document \r\nand the age of the document being requested. Any code using this should handle the situation where those fields are\r\nnot present.","nullable":true,"readOnly":true},"documentURL":{"type":"string","description":"The URL that can be used to download the document.","nullable":true}},"additionalProperties":false},"CategoryDetails":{"type":"object","properties":{"id":{"type":"integer","description":"The numeric id of this document category.","format":"int32"},"name":{"type":"string","description":"The name of this document category","nullable":true},"description":{"type":"string","description":"A description of this document category.","nullable":true}},"additionalProperties":false,"description":"The category that this document was classified under when uploaded.\r\nA list of the available document categories can be retrieved by calling the Get Document Types endpoint."},"ErrorResults":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ReportingError"},"nullable":true},"statusCode":{"type":"integer","format":"int32"}},"additionalProperties":false},"ReportingError":{"type":"object","properties":{"errorMessage":{"type":"string","description":"A human readable description of the error that occurred. These descriptions are subject to change and may be\r\nupdated to better reflect different scenarios. ResultCode should be used instead if any programmatic handling\r\nof errors is needed.","nullable":true},"resultCode":{"type":"integer","description":"A numeric identifier for the error.","format":"int32"},"timeStamp":{"type":"string","description":"The time at which the error occurred expressed as Coordinated Universal Time (UTC).","format":"date-time","readOnly":true}},"additionalProperties":false}}}}
```