# Document Operations

### Introduction

This section covers how to upload, list, retrieve, and delete documents associated with a virtual IBAN account. 

Use the the folowing endpoints when you need to:

* upload and documents associated with a customer account
* review which documents have already been submitted
* retrieve details for a specific document
* remove a document that was uploaded incorrectly or is no longer needed

## Upload virtual IBAN document

> Upload virtual IBAN document

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.2.0"},"tags":[{"name":"Documents","description":"Documents"}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Authentication using a Bearer token.","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"UUID":{"description":"Universally Unique Identifier (UUID) as defined by RFC 4122.","type":"string","format":"uuid","pattern":"^[a-zA-Z0-9]{8}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{12}$"},"API.Requests.UploadDocument":{"title":"Virtual Account upload document","description":"Data required to upload a document to a virtual account.","required":["type","file_name","attachment"],"properties":{"type":{"description":"Document type","type":"string","enum":["registration_document","vat_document","proof_of_ownership","proof_of_industry","identity_card","drivers_license","passport","residence_permit","proof_of_residence","proof_of_address","other"]},"description":{"description":"Description","type":"string"},"file_name":{"description":"Original filename","type":"string"},"attachment":{"required":["content"],"properties":{"content":{"description":"Base64 encoded file content","type":"string","format":"byte"},"page_type":{"description":"Page side of the document (required for identity_card and drivers_license)","type":"string","enum":["front","back"],"nullable":true}},"type":"object"}},"type":"object"},"ValidationResponse":{"title":"Validation Error Response","description":"Standard response format for validation errors (HTTP 422).","required":["status","status_code","message","errors"],"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"description":"An object containing validation errors. Keys are field names, values are arrays of error messages for that field.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"}}},"paths":{"/api/v1/customers/{customer_uuid}/accounts/{account_uuid}/documents":{"post":{"tags":["Documents"],"summary":"Upload virtual IBAN document","description":"Upload virtual IBAN document","operationId":"API.Documents.Upload","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"account_uuid","in":"path","description":"The unique identifier (UUID) of the account.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"requestBody":{"description":"Document upload payload","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Requests.UploadDocument"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Virtual IBAN not found."},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}}
```

## Get Documents List

> Get a paginated list of documents associated with the given customer UUID and account ID.

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.2.0"},"tags":[{"name":"Documents","description":"Documents"}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Authentication using a Bearer token.","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"UUID":{"description":"Universally Unique Identifier (UUID) as defined by RFC 4122.","type":"string","format":"uuid","pattern":"^[a-zA-Z0-9]{8}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{12}$"},"perPage":{"description":"Number of items to return per page in a paginated response.","type":"integer","default":15,"maximum":100,"minimum":1},"page":{"description":"The current page number for paginated results.","type":"integer","default":1,"minimum":1},"API.Resources.DocumentResource":{"properties":{"uuid":{"description":"The unique identifier (UUID) of the document.","type":"string","format":"uuid"},"type":{"description":"The type of the document.","type":"string","enum":["registration_document","vat_document","proof_of_ownership","proof_of_industry","identity_card","drivers_license","passport","residence_permit","proof_of_residence","proof_of_address","other"]},"file_name":{"description":"The original filename of the uploaded document.","type":"string"},"description":{"description":"Description of the document.","type":"string"},"page_type":{"description":"Page side of the document (available for identity_card and drivers_license)","type":"string","enum":["front","back"],"nullable":true},"created_at":{"description":"The timestamp when the document was created.","type":"string","format":"date-time"},"status":{"description":"Status of the document","type":"string","enum":["pending","uploaded","rejected"]}},"type":"object"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"ValidationResponse":{"title":"Validation Error Response","description":"Standard response format for validation errors (HTTP 422).","required":["status","status_code","message","errors"],"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"description":"An object containing validation errors. Keys are field names, values are arrays of error messages for that field.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"}}},"paths":{"/api/v1/customers/{customer_uuid}/accounts/{account_uuid}/documents":{"get":{"tags":["Documents"],"summary":"Get Documents List","description":"Get a paginated list of documents associated with the given customer UUID and account ID.","operationId":"API.Documents.List","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"account_uuid","in":"path","description":"The unique identifier (UUID) of the account.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"type","in":"query","description":"Optional document type filter.","required":false,"schema":{"type":"string","enum":["registration_document","vat_document","proof_of_ownership","proof_of_industry","identity_card","drivers_license","passport","residence_permit","proof_of_residence","proof_of_address","other"]}},{"name":"filename","in":"query","description":"Optional document filename filter.","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","description":"Number of messages to return per page.","required":false,"schema":{"$ref":"#/components/schemas/perPage"}},{"name":"page","in":"query","description":"The page number to retrieve.","required":false,"schema":{"$ref":"#/components/schemas/page"}},{"name":"sort","in":"query","description":"Field to sort the documents list by.","required":false,"schema":{"type":"string","default":"created_at","enum":["id","original_name","type","created_at"]}},{"name":"direction","in":"query","description":"Sort direction for the message list.","required":false,"schema":{"type":"string","default":"desc","enum":["asc","desc"]}}],"responses":{"200":{"description":"Successful retrieval of documents.","headers":{"X-Total-Count":{"description":"Total number of records matching the filter criteria.","schema":{"type":"integer"}},"X-Offset":{"description":"Current pagination offset.","schema":{"type":"integer"}},"X-Limit":{"description":"Current pagination limit.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/API.Resources.DocumentResource"}}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Document not found."},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}}
```

## Get Document Details

> Retrieves the details of a specific document by its UUID.

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.2.0"},"tags":[{"name":"Documents","description":"Documents"}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Authentication using a Bearer token.","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"UUID":{"description":"Universally Unique Identifier (UUID) as defined by RFC 4122.","type":"string","format":"uuid","pattern":"^[a-zA-Z0-9]{8}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{12}$"},"API.Resources.DocumentResource":{"properties":{"uuid":{"description":"The unique identifier (UUID) of the document.","type":"string","format":"uuid"},"type":{"description":"The type of the document.","type":"string","enum":["registration_document","vat_document","proof_of_ownership","proof_of_industry","identity_card","drivers_license","passport","residence_permit","proof_of_residence","proof_of_address","other"]},"file_name":{"description":"The original filename of the uploaded document.","type":"string"},"description":{"description":"Description of the document.","type":"string"},"page_type":{"description":"Page side of the document (available for identity_card and drivers_license)","type":"string","enum":["front","back"],"nullable":true},"created_at":{"description":"The timestamp when the document was created.","type":"string","format":"date-time"},"status":{"description":"Status of the document","type":"string","enum":["pending","uploaded","rejected"]}},"type":"object"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"ValidationResponse":{"title":"Validation Error Response","description":"Standard response format for validation errors (HTTP 422).","required":["status","status_code","message","errors"],"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"description":"An object containing validation errors. Keys are field names, values are arrays of error messages for that field.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"}}},"paths":{"/api/v1/customers/{customer_uuid}/accounts/{account_uuid}/documents/{document_uuid}":{"get":{"tags":["Documents"],"summary":"Get Document Details","description":"Retrieves the details of a specific document by its UUID.","operationId":"API.Documents.Show","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"account_uuid","in":"path","description":"The unique identifier (UUID) of the account.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"document_uuid","in":"path","description":"The unique identifier (UUID) of the document to retrieve.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"200":{"description":"Successful retrieval of document details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/API.Resources.DocumentResource"}}}},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Document not found."},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}}
```

## Delete Document

> Deletes a specific document by its UUID.

```json
{"openapi":"3.0.0","info":{"title":"GURUPAY API","version":"0.2.0"},"tags":[{"name":"Documents","description":"Documents"}],"servers":[{"url":"https://public-api.gurupay.eu","description":"Production API Server"},{"url":"https://public-api-dev.gurupay.eu","description":"Sandbox API Server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Authentication using a Bearer token.","name":"Authorization","in":"header","bearerFormat":"JWT","scheme":"bearer"}},"schemas":{"UUID":{"description":"Universally Unique Identifier (UUID) as defined by RFC 4122.","type":"string","format":"uuid","pattern":"^[a-zA-Z0-9]{8}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{4}-[a-zA-Z0-9]{12}$"},"UnauthenticatedResponse":{"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"type":"object"},"ValidationResponse":{"title":"Validation Error Response","description":"Standard response format for validation errors (HTTP 422).","required":["status","status_code","message","errors"],"properties":{"status":{"type":"boolean"},"status_code":{"type":"integer"},"message":{"type":"string"},"errors":{"description":"An object containing validation errors. Keys are field names, values are arrays of error messages for that field.","type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"type":"object"}}},"paths":{"/api/v1/customers/{customer_uuid}/accounts/{account_uuid}/documents/{document_uuid}":{"delete":{"tags":["Documents"],"summary":"Delete Document","description":"Deletes a specific document by its UUID.","operationId":"API.Documents.Destroy","parameters":[{"name":"customer_uuid","in":"path","description":"The unique identifier (UUID) of the customer.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"account_uuid","in":"path","description":"The unique identifier (UUID) of the account.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}},{"name":"document_uuid","in":"path","description":"The unique identifier (UUID) of the document to delete.","required":true,"schema":{"$ref":"#/components/schemas/UUID"}}],"responses":{"204":{"description":"Document successfully deleted."},"401":{"description":"Unauthorized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthenticatedResponse"}}}},"404":{"description":"Document not found."},"422":{"description":"Unprocessable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationResponse"}}}}}}}}}
```