{"openapi":"3.1.0","info":{"title":"Benefits Documents Service API","description":"The Benefits Documents API lets you:\n* Submit supporting 526EZ claims documentation to a VBMSeFolder.\n* Retrieve a list of supporting 526EZ claim document names from a Veteran's VBMS eFolder.\n* Return upload status of documents submitted to a VBMS eFolder.\n* Search for and download claims letter documents.\n\n## Technical overview\nThe Benefits Documents API receives a VBMS Participant ID or File Number. The ID or File\nNumber is used to identify the Veteran or dependent associated with a particular VBMS eFolder.\n\nWith either the Participant ID or File Number, you can:\n* Submit supporting documentation for a disability claim.\n* Retrieve a list of supporting claims document names from the eFolder.\n* Check the status of submitted claims documents.\n* Search for and download claims letter documents.\n\nAccepted document attachment types for submissions are:\n  * PDF\n  * JPG\n  * TXT\n  * TIF\n  * PNG\n  * GIF\n  * BMP\n\nThe Participant ID (participantId) parameter can be used to identify Veterans and dependents.\nIf Veterans and dependents of deceased Veterans submit this parameter, they can upload and\nsearch for supporting claims documentation in their associated Veteran's eFolder. \n\n**Note**: Dependents of living Veterans can not upload and search for documentation. \n\n### Authentication and authorization \nThe authentication model for the Benefits Documents Service API is based on OAuth 2.0/OpenID\nConnect and supports client [credentials grant (CCG)](https://developer.va.gov/explore/api/benefits-documents/client-credentials).\n\n**Important**: To get production access, you must either work for VA or have specific VA agreements in\nplace. If you have questions, [contact us](https://developer.va.gov/support/contact-us).\n","version":"v1"},"servers":[{"url":"https://sandbox-api.va.gov/services/benefits-documents/{version}","description":"Sandbox","variables":{"version":{"default":"v1"}}},{"url":"https://api.va.gov/services/benefits-documents/{version}","description":"Production","variables":{"version":{"default":"v1"}}}],"paths":{"/uploads/status":{"post":{"tags":["Documents Service"],"summary":"Returns the upload status of multiple disability claim documents.","description":"  Returns the current processing status of multiple disability\n   claims document uploads related to the given list of request IDs.\n","operationId":"POST:/uploads/status","parameters":[{"name":"includeInternalOnlyStepStatuses","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadRequestAsyncProcessingStatusBulkRequestV1"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadRequestAsyncProcessingStatusBulkResponseV1"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Request size limit exceeded"}}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"API rate limit exceeded"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}},"security":[{"oauth2":["documents.read"]}]}},"/participant/documents/search":{"post":{"tags":["Documents Service"],"summary":" Returns all VBMS document names associated with a participantId.\n","description":" Returns a list of all VBMS document names related to participantId.\n","operationId":"POST:/participant/documents/search","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VbmsSearchDocumentsRequestV1"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VbmsSearchDocumentsResponseV1"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Request size limit exceeded"}}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"API rate limit exceeded"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}},"security":[{"oauth2":["documents.read"]}]}},"/participant/documents/download":{"post":{"tags":["Documents Service"],"summary":"Download the document for a participant.","description":"  Use this endpoint to download the full content of a document (such\n  as a PDF). The document must be identified by its unique ID, and associated with\n  either a Participant ID or File Number.\n","operationId":"POST:/participant/documents/download","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VbmsDownloadDocumentRequestV1"}}},"required":true},"responses":{"200":{"description":"Binary document stream (e.g., PDF).","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Request size limit exceeded"}}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"API rate limit exceeded"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}},"security":[{"oauth2":["documents.read"]}]}},"/documents":{"post":{"tags":["Documents Service"],"summary":"Uploads a file to a Veteran's VBMS eFolder.","description":"Receives and uploads a file based on the required parameters of systemName, docType,\nfileNumber, participantId, claimId, and fileName. Parameters are described in\nthe schema section for UploadRequestV1.UploadData.\n\n## Example Payload (using File Number)\n\nThe following demonstrates a (redacted) multipart payload, identified by fileNumber,\nsuitable for submitting to this endpoint. Most programming languages should have\nprovisions for assembling a multipart payload like this without having to do so\nmanually.\n\n```\nPOST /benefits-documents/v1/documents HTTP/1.1\nHost: <server>\nUser-Agent: curl/7.75.0\nAccept: */*\nAuthorization: Bearer <token>\nContent-Length: 11871\nContent-Type: multipart/form-data; boundary=------------------------94408bea7cc00a68\n\nContent-Type: application/json\n\n{\n  \"data\": {\n    \"systemName\":\"VA.gov\",\n    \"docType\":\"L533\",\n    \"fileNumber\":\"987654321\",\n    \"claimId\":\"123\",\n    \"fileName\":\"Test-PDF-Valid.pdf\",\n    \"trackedItemIds\": [ 456,789 ]\n  }\n}\n\n```\n\nIn this curl example, we store the parameters inside JSON file called\nupload-request.p2iO.json:\n\n```\n{\n  \"data\": {\n    \"systemName\":\"VA.gov\",\n    \"docType\":\"L533\",\n    \"fileNumber\":\"987654321\",\n    \"claimId\":\"123\",\n    \"fileName\":\"Test-PDF-Valid.pdf\",\n    \"trackedItemIds\": [ 456,789 ]\n  }\n}\n\n```\n\nThis is an example curl command:\n\n```\n\ncurl -v '-HAuthorization: Bearer <token>' -HContent-Type:multipart/form-data --form 'parameters=@upload-request.p2iO.json;type=application/json' --form 'file=@<path/to/pdf/file>;type=application/pdf' https://sandbox-api.va.gov/services/benefits-documents/v1/documents\n\n```\n\n## Example Payload (using Participant ID)\n\nTo upload using participantId, we'll use the same upload example as above, this time\nproviding a participantId instead of a fileNumber:\n\n```\nPOST /benefits-documents/v1/documents HTTP/1.1\nHost: <server>\nUser-Agent: curl/7.75.0\nAccept: */*\nAuthorization: Bearer <token>\nContent-Length: 11871\nContent-Type: multipart/form-data; boundary=------------------------94408bea7cc00a68\n\nContent-Type: application/json\n\n{\n  \"data\": {\n    \"systemName\":\"VA.gov\",\n    \"docType\":\"L533\",\n    \"participantId\":\"123456789\",\n    \"claimId\":\"123\",\n    \"fileName\":\"Test-PDF-Valid.pdf\",\n    \"trackedItemIds\": [ 456,789 ]\n  }\n}\n\n```\n\nWe can store the parameters inside a JSON file as in the previous example - this time\nwe'll call it upload-request-participant-id.p2iO.json.\n\nThen, we can execute the same cURL command in the previous example,\nusing the new parameters file:\n\n```\n\ncurl -v '-HAuthorization: Bearer <token>' -HContent-Type:multipart/form-data --form 'parameters=@upload-request-participant-id.p2iO.json;type=application/json' --form 'file=@<path/to/pdf/file>;type=application/pdf' https://sandbox-api.va.gov/services/benefits-documents/v1/documents\n\n```\n\n","operationId":"POST:/documents","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"parameters":{"$ref":"#/components/schemas/UploadRequestV1"},"file":{"type":"string","format":"binary"}},"required":["file","parameters"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadResponseV1"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Request size limit exceeded"}}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"API rate limit exceeded"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}},"security":[{"oauth2":["documents.write"]}]}},"/documents/validate/claimant":{"post":{"tags":["Documents Service"],"summary":"Validates that the claimant can upload a file to a Veteran's VBMS eFolder.","description":"Determines whether a claimant, identified by either a fileNumber or participantId,\ncan upload documents of the given docType for the claim identified by the\nprovided claimId. If the claimant is successfully validated, a validation token\nand token expiration time are provided. The token can be used to avoid duplicate\nvalidation for an upload using identical parameters. Note that while a successful\nresponse indicates the pairing of claimant, document, and claim information is\nvalid, it does not guarantee success of the operation itself.\n","operationId":"POST:/documents/validate/claimant","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateUploadClaimantRequestV1"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimantValidationResponseV1"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Request size limit exceeded"}}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"API rate limit exceeded"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}},"security":[{"oauth2":["documents.read"]}]}},"/documents/search":{"post":{"tags":["Documents Service"],"summary":"  Returns all claims evidence document names associated with a participantId\n  or fileNumber.\n","description":"  Returns a list of all claims evidence document names related to the\n   claim identified by the claimId, fileNumber, or participantId.\n","operationId":"POST:/documents/search","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimDocumentsRequestV1"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimDocumentsResponseV1"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Request size limit exceeded"}}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"API rate limit exceeded"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}},"security":[{"oauth2":["documents.read"]}]}},"/claim-letters/search":{"post":{"tags":["Documents Service"],"summary":"  Returns a list of downloadable Claims Evidence claim letter documents, along with\n  their associated metadata, linked to a Participant ID or File Number.\n","description":"  Returns a list of downloadable Claims Evidence claim letter documents associated\n  with the provided Participant ID or File Number. Each document entry includes\n  metadata such as the document UUID, type, subject, original file name, tracked\n  item ID, and upload date.\n","operationId":"POST:/claim-letters/search","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindClaimLetterDocumentsRequestV1"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindClaimLetterDocumentsResponseV1"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Request size limit exceeded"}}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"API rate limit exceeded"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}},"security":[{"oauth2":["documents.read"]}]}},"/claim-letters/download":{"post":{"tags":["Documents Service"],"summary":"Download the full claim letter document for a claimant.","description":"  Use this endpoint to download the full content of a claim letter document (such\n  as a PDF). The document must be identified by its unique ID, and associated with\n  either a Participant ID or File Number. Note: Only some document types are\n  available for download.\n","operationId":"POST:/claim-letters/download","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadClaimLetterDocumentRequestV1"}}},"required":true},"responses":{"200":{"description":"Binary document stream (e.g., PDF).","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Request size limit exceeded"}}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"API rate limit exceeded"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}},"security":[{"oauth2":["documents.read"]}]}},"/uploads/{requestId}/status":{"get":{"tags":["Documents Service"],"summary":"Returns the processing status of a single disability claim document upload.","description":"  Returns the current processing status of a disability claims document upload\n  related to the given requestId.\n","operationId":"GET:/uploads/{requestId}/status","parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"integer","format":"int64"}},{"name":"includeInternalOnlyStepStatuses","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadRequestAsyncProcessingStatusResponseV1"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Request size limit exceeded"}}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"API rate limit exceeded"}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"502":{"description":"Bad Gateway","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicErrorDocumentV1"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}},"security":[{"oauth2":["documents.read"]}]}}},"components":{"schemas":{"BasicErrorDocumentV1":{"type":"object","description":"An error response in JSON:API format (see https://jsonapi.org/format/#document-structure).","properties":{"errors":{"type":"array","description":"The list of errors returned from the attempted operation.","items":{"$ref":"#/components/schemas/BasicErrorV1"}}},"required":["errors"]},"BasicErrorV1":{"type":"object","description":"API invocation or processing error","properties":{"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem.","example":"Code must match \"^[A-Z]{2}$\""},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence of the problem.","example":400},"type":{"type":"string","description":"A URI reference that identifies the problem type.","example":"https://example.net/validation-error"},"title":{"type":"string","description":"A short, human-readable summary of the problem type.","example":"Invalid field value"},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem.","example":"e6d1119e-dc91-4b4d-b583-0f309de0807b"},"diagnostics":{"type":"string","description":"Diagnostic information that can be submitted with a support request to aid with diagnosing and solving issues.","example":"e6d1119edc914b4db5830f309de0807b"}}},"UploadRequestAsyncProcessingStatusBulkRequestV1":{"type":"object","description":"Requests the asynchronous processing status of more than one document upload request.","properties":{"data":{"$ref":"#/components/schemas/UploadRequestAsyncProcessingStatusBulkRequestV1.UploadRequestIds"}},"required":["data"]},"UploadRequestAsyncProcessingStatusBulkRequestV1.UploadRequestIds":{"type":"object","properties":{"requestIds":{"type":"array","description":"The list of requestIds that identify upload requests to retrieve status for.","items":{"type":"integer","format":"int64"}}},"required":["requestIds"]},"UploadRequestAsyncProcessingStatusBulkResponseV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UploadRequestAsyncProcessingStatusBulkResponseV1.UploadRequestStatuses"}},"required":["data"]},"UploadRequestAsyncProcessingStatusBulkResponseV1.UploadRequestStatuses":{"type":"object","properties":{"statuses":{"type":"array","items":{"$ref":"#/components/schemas/UploadRequestAsyncProcessingStatusV1"}},"requestIdsNotFound":{"type":"array","description":"A list populated with requestIds whose status was not found.\n","items":{"type":"integer","format":"int64"}}},"required":["requestIdsNotFound"]},"UploadRequestAsyncProcessingStatusV1":{"type":"object","description":"The asynchronous processing workflow status of a single upload request.","properties":{"requestId":{"type":"integer","format":"int64","description":"The requestId of the upload request.","example":600000001},"time":{"$ref":"#/components/schemas/UploadRequestAsyncProcessingStatusV1.WorkflowTime"},"status":{"type":"string","description":"The current execution status of the workflow:\n* `IN_PROGRESS`: the workflow is currently executing.\n* `SUCCESS`: the workflow has completed all steps successfully.\n* `FAILED`: the workflow could not complete because a step encountered\na non-recoverable error.\n","enum":["IN_PROGRESS","SUCCESS","FAILED"]},"steps":{"type":"array","description":"The list of workflow steps that process the document upload, ordered by their sequence.","items":{"$ref":"#/components/schemas/UploadRequestAsyncProcessingStatusV1.Step"}},"error":{"$ref":"#/components/schemas/UploadRequestAsyncProcessingStatusV1.WorkflowError"}},"required":["requestId","status","steps","time"]},"UploadRequestAsyncProcessingStatusV1.Step":{"type":"object","description":"The description of a single workflow step.","properties":{"name":{"type":"string","description":"The workflow step name:\n* `CLAIMS_EVIDENCE`: the workflow step that uploads the document to Claims Evidence.\n* `BENEFITS_GATEWAY_SERVICE`: the workflow step that uploads the document to Benefits\nGateway Service.\n* `REMOVE_FILE_BINARY`: the workflow step that removes file binary\nGateway Service.\n","enum":["REMOVE_FILE_BINARY","BENEFITS_GATEWAY_SERVICE","CLAIMS_EVIDENCE"]},"nextStepName":{"type":"string","description":"The workflow step name:\n* `CLAIMS_EVIDENCE`: the workflow step that uploads the document to Claims Evidence.\n* `BENEFITS_GATEWAY_SERVICE`: the workflow step that uploads the document to Benefits\nGateway Service.\n* `REMOVE_FILE_BINARY`: the workflow step that removes file binary\nGateway Service.\n","enum":["REMOVE_FILE_BINARY","BENEFITS_GATEWAY_SERVICE","CLAIMS_EVIDENCE"]},"description":{"type":"string","description":"A short description of the workflow step"},"status":{"type":"string","description":"The current execution status of the workflow step:\n* `NOT_STARTED`: the workflow step is not yet executing and awaiting completion\nof the previous step.\n* `IN_PROGRESS`: the workflow step is currently executing.\n* `SUCCESS`: the workflow step has completed successfully.\n* `FAILED`: the workflow step encountered a non-recoverable error.\n","enum":["NOT_STARTED","IN_PROGRESS","SUCCESS","FAILED"]}}},"UploadRequestAsyncProcessingStatusV1.WorkflowError":{"type":"object","description":"Workflow error information.","properties":{"detail":{"type":"string","description":"A human-readable summary of the error."},"step":{"type":"string","description":"The workflow step name:\n* `CLAIMS_EVIDENCE`: the workflow step that uploads the document to Claims Evidence.\n* `BENEFITS_GATEWAY_SERVICE`: the workflow step that uploads the document to Benefits\nGateway Service.\n* `REMOVE_FILE_BINARY`: the workflow step that removes file binary\nGateway Service.\n","enum":["REMOVE_FILE_BINARY","BENEFITS_GATEWAY_SERVICE","CLAIMS_EVIDENCE"]}}},"UploadRequestAsyncProcessingStatusV1.WorkflowTime":{"type":"object","description":"Workflow timing information.","properties":{"startTime":{"type":"integer","format":"int64","description":"The time, in milliseconds since epoch, that the workflow began executing.","example":1502199000},"endTime":{"type":"integer","format":"int64","description":"The time, in milliseconds since epoch, that the workflow finished executing.\nIn the case of a currently executing workflow, this will be null.\n","example":1502199000}}},"Pagination":{"type":"object","properties":{"pageNumber":{"type":"integer","format":"int32","description":"1-based page number to retrieve. Defaults to 1.","example":1},"pageSize":{"type":"integer","format":"int32","description":"Number of results per page (1–100). Defaults to 100.","example":25}}},"VbmsDocumentsIdentifier":{"type":"object","properties":{"participantId":{"type":"integer","format":"int64","description":"A unique identifier assigned to each patient entry in the Master Patient Index\nlinking patients to their records across VA systems.\n","example":999012105}}},"VbmsSearchDocumentsRequestV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VbmsDocumentsIdentifier"},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"VbmsDocumentV1":{"type":"object","properties":{"docTypeId":{"type":"integer","format":"int32","example":137},"subject":{"type":"string","example":"File contains evidence related to the claim"},"documentUuid":{"type":"string","description":"This value is obtained from the uuid field from BIP Claims Evidence.\nIt is the same value as the documentId field\nreported by the /documents/search endpoint.","example":"{12345678-ABCD-0123-cdef-124345679ABC}"},"currentVersionUuid":{"type":"string","description":"This value is obtained from the currentVersionUuid field from BIP Claims Evidence.","example":"{12345678-ABCD-0123-cdef-124345679ABC}"},"originalFileName":{"type":"string","example":"SupportingDocument.pdf"},"documentTypeLabel":{"type":"string","example":"VA 21-526 Veterans Application for Compensation or Pension"},"uploadedDateTime":{"type":"string","format":"date-time","example":"2016-02-04T17:51:56Z"},"receivedAt":{"type":"string","example":"2016-02-04"}}},"VbmsSearchDocumentsResponseV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VbmsSearchDocumentsResponseV1.Documents"},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["data"]},"VbmsSearchDocumentsResponseV1.Documents":{"type":"object","properties":{"documents":{"type":"array","description":"The list of VBMS documents.\n","items":{"$ref":"#/components/schemas/VbmsDocumentV1"}}}},"VbmsDownloadDocumentRequestV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VbmsDownloadDocumentRequestV1.DocumentInfo"}},"required":["data"]},"VbmsDownloadDocumentRequestV1.DocumentInfo":{"type":"object","properties":{"fileNumber":{"type":"string","description":"The Veteran's VBMS fileNumber used when uploading the document to VBMS.\n It indicates the eFolder in which the document resides.\n","example":"999012105"},"participantId":{"type":"integer","format":"int64","description":"A unique identifier assigned to each patient entry in the Master Patient Index\nlinking patients to their records across VA systems.\n","example":999012105},"documentUuid":{"type":"string","description":"The document's unique identifier in VBMS, obtained by making a Document Service API\nrequest to search for documents that are available to download for the Veteran.\nNote that this differs from the document's current version UUID.\n","example":"12345678-ABCD-0123-cdef-124345679ABC"}},"required":["documentUuid"]},"UploadRequestV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UploadRequestV1.UploadData"}},"required":["data"]},"UploadRequestV1.UploadData":{"type":"object","properties":{"trackedItemIds":{"type":"array","description":"A list of tracked item IDs that are associated\nwith the document being uploaded.\n","example":[1,2,3],"items":{"type":"integer","format":"int64"}},"systemName":{"type":"string","description":"Indicates which system is uploading the document.","example":"va.gov"},"docType":{"type":"string","description":"Indicates the L code of the type of document being uploaded.","example":"L122"},"fileNumber":{"type":"string","description":"The Veteran's VBMS fileNumber used when uploading the document to VBMS.\n It indicates the eFolder in which the document resides.\n","example":"999012105"},"participantId":{"type":"integer","format":"int64","description":"A unique identifier assigned to each patient entry in the Master Patient Index\nlinking patients to their records across VA systems.\n","example":999012105},"claimId":{"type":"integer","format":"int64","description":"The VBMS-issued claim identifier with which the document is associated.","example":1234,"maximum":9223372036854776000,"minimum":1},"fileName":{"type":"string","description":"The name of the file being uploaded.","example":"Document.pdf","maxLength":256},"validationToken":{"type":"string","description":"An optional validation token obtained during request claimant pre-validation,\nthat bypasses duplicate validation calls. For more information, review the section\non request pre-validation.\n","maxLength":64}},"required":["claimId","docType","fileName","systemName"]},"UploadResponseV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UploadResponseV1.UploadInfo"}},"required":["data"]},"UploadResponseV1.UploadInfo":{"type":"object","properties":{"success":{"type":"boolean","description":"Indicates if the upload request was successful.","example":true},"requestId":{"type":"integer","format":"int64","description":"The upload request identifier.","example":12345678,"maximum":9223372036854776000}},"required":["requestId","success"]},"ValidateUploadClaimantRequestV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ValidateUploadClaimantRequestV1.ValidateUploadData"}}},"ValidateUploadClaimantRequestV1.ValidateUploadData":{"type":"object","properties":{"docType":{"type":"string","description":"Indicates the L code of the type of document upload being validated.","example":"L122"},"fileNumber":{"type":"string","description":"The Veteran's VBMS fileNumber used when uploading the document to VBMS.\n It indicates the eFolder in which the document resides.\n","example":"999012105"},"participantId":{"type":"integer","format":"int64","description":"A unique identifier assigned to each patient entry in the Master Patient Index\nlinking patients to their records across VA systems.\n","example":999012105},"claimId":{"type":"integer","format":"int64","description":"The VBMS-issued claim identifier with which the document upload being\nvalidated is associated.\n","example":1234,"maximum":9223372036854776000,"minimum":1}},"required":["docType"]},"ClaimantValidationResponseV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ClaimantValidationResponseV1.ValidationResult"}},"required":["data"]},"ClaimantValidationResponseV1.ValidationError":{"type":"object","properties":{"message":{"type":"string","description":"The validation error message."}},"required":["message"]},"ClaimantValidationResponseV1.ValidationResult":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether the claimant was validated successfully."},"success":{"$ref":"#/components/schemas/ClaimantValidationResponseV1.ValidationSuccess","description":"The validation result, populated in the case of successful validation."},"error":{"$ref":"#/components/schemas/ClaimantValidationResponseV1.ValidationError","description":"The validation error, populated in the case of failed validation."}},"required":["valid"]},"ClaimantValidationResponseV1.ValidationSuccess":{"type":"object","properties":{"validationToken":{"type":"string","description":"The validation token."},"validUntil":{"type":"integer","format":"int64","description":"The time, in milliseconds since epoch, that the token expires."}},"required":["validUntil","validationToken"]},"ClaimDocumentsRequestV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ClaimDocumentsRequestV1.ClaimDocuments"}},"required":["data"]},"ClaimDocumentsRequestV1.ClaimDocuments":{"type":"object","properties":{"claimId":{"type":"integer","format":"int64","description":"The VBMS-issued claim identifier with which the document is associated.","example":1234,"maximum":9223372036854776000,"minimum":1},"fileNumber":{"type":"string","description":"The Veteran's VBMS fileNumber used when uploading the document to VBMS.\n It indicates the eFolder in which the document resides.\n","example":"999012105"},"participantId":{"type":"integer","format":"int64","description":"A unique identifier assigned to each patient entry in the Master Patient Index\nlinking patients to their records across VA systems.\n","example":999012105}},"required":["claimId"]},"ClaimDocumentV1":{"type":"object","properties":{"documentId":{"type":"string","example":"{12345678-ABCD-0123-cdef-124345679ABC}"},"documentUuid":{"type":"string","description":"The document's unique identifier in VBMS.\nNote that this differs from the document's current version UUID.\n","example":"12345678-ABCD-0123-cdef-124345679ABC"},"currentVersionUuid":{"type":"string","description":"This value is obtained from the currentVersionUuid field from BIP Claims Evidence.","example":"{12345678-ABCD-0123-cdef-124345679ABC}"},"originalFileName":{"type":"string","example":"SupportingDocument.pdf"},"documentTypeLabel":{"type":"string","example":"VA 21-526 Veterans Application for Compensation or Pension"},"trackedItemId":{"type":"integer","format":"int64","example":600000001},"uploadedDateTime":{"type":"string","format":"date-time","example":"2016-02-04T17:51:56Z"}},"required":["currentVersionUuid","documentId","documentTypeLabel","documentUuid","originalFileName","uploadedDateTime"]},"ClaimDocumentsResponseV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ClaimDocumentsResponseV1.Documents"}},"required":["data"]},"ClaimDocumentsResponseV1.Documents":{"type":"object","properties":{"documents":{"type":"array","description":"The list of benefits claim documents.\n","items":{"$ref":"#/components/schemas/ClaimDocumentV1"}}}},"FindClaimLetterDocumentsRequestV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FindClaimLetterDocumentsRequestV1.FindClaimLetterDocumentsData"}},"required":["data"]},"FindClaimLetterDocumentsRequestV1.FindClaimLetterDocumentsData":{"type":"object","properties":{"docTypeIds":{"type":"array","description":"The numeric document types to search for. If not provided, then\nall downloadable claim letter documents matching the other\nrequest criteria will be returned.\n","example":[27,34,184,408,700,704,706,858,859,864,942,1605],"items":{"type":"integer","format":"int32"}},"fileNumber":{"type":"string","description":"The Veteran's VBMS fileNumber used when uploading the document to VBMS.\n It indicates the eFolder in which the document resides.\n","example":"999012105"},"participantId":{"type":"integer","format":"int64","description":"A unique identifier assigned to each patient entry in the Master Patient Index\nlinking patients to their records across VA systems.\n","example":999012105}}},"ClaimLetterDocumentV1":{"type":"object","properties":{"docTypeId":{"type":"integer","format":"int32","description":"The numeric type code of the document.","example":184},"subject":{"type":"string","description":"The document subject."},"documentUuid":{"type":"string","description":"The document's unique identifier in VBMS.\nNote that this differs from the document's current version UUID.\n","example":"12345678-ABCD-0123-cdef-124345679ABC"},"currentVersionUuid":{"type":"string","description":"This value is obtained from the currentVersionUuid field from BIP Claims\nEvidence.\n","example":"{12345678-ABCD-0123-cdef-124345679ABC}"},"originalFileName":{"type":"string","example":"SupportingDocument.pdf"},"documentTypeLabel":{"type":"string","example":"VA 21-526 Veterans Application for Compensation or Pension"},"trackedItemId":{"type":"integer","format":"int64","example":600000001},"uploadedDateTime":{"type":"string","format":"date-time","example":"2016-02-04T17:51:56Z"},"receivedAt":{"type":"string","example":"2016-02-04"}},"required":["currentVersionUuid","docTypeId","documentTypeLabel","documentUuid","originalFileName","subject","uploadedDateTime"]},"FindClaimLetterDocumentsResponseV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FindClaimLetterDocumentsResponseV1.ClaimLetterDocuments"}},"required":["data"]},"FindClaimLetterDocumentsResponseV1.ClaimLetterDocuments":{"type":"object","properties":{"documents":{"type":"array","description":"The list of claim letter documents available for download.\n","items":{"$ref":"#/components/schemas/ClaimLetterDocumentV1"}}}},"DownloadClaimLetterDocumentRequestV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DownloadClaimLetterDocumentRequestV1.ClaimLetterDocumentInfo"}},"required":["data"]},"DownloadClaimLetterDocumentRequestV1.ClaimLetterDocumentInfo":{"type":"object","properties":{"fileNumber":{"type":"string","description":"The Veteran's VBMS fileNumber used when uploading the document to VBMS.\n It indicates the eFolder in which the document resides.\n","example":"999012105"},"participantId":{"type":"integer","format":"int64","description":"A unique identifier assigned to each patient entry in the Master Patient Index\nlinking patients to their records across VA systems.\n","example":999012105},"documentUuid":{"type":"string","description":"The document's unique identifier in VBMS, obtained by making a Document Service API\nrequest to search for documents that are available to download for the Veteran.\nNote that this differs from the document's current version UUID.\n","example":"12345678-ABCD-0123-cdef-124345679ABC"}},"required":["documentUuid"]},"UploadRequestAsyncProcessingStatusResponseV1":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/UploadRequestAsyncProcessingStatusV1"}},"required":["data"]}},"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.va.gov/oauth2/exemplar/system/v1/token","scopes":{"documents.write":"The Veteran's access to upload files that provide verification of eligibility for their benefits.","documents.read":"The Veteran's access to read data about files that have been uploaded."}}}}}}}