openapi: 3.0.0
servers:
  - description: VA.gov API sandbox environment
    url: https://sandbox-api.va.gov/services/vba_documents/{version}
    variables:
      version:
        default: v1
  - description: VA.gov API production environment
    url: https://api.va.gov/services/vba_documents/{version}
    variables:
      version:
        default: v1
info:
  contact:
    name: va.gov
  description: |
    The Benefits Intake API allows authorized third-party systems used by Veteran Service Organizations (VSOs), agencies, and Veterans to digitally submit VA benefits claim documents directly to the Veterans Benefits Administration's (VBA) claims intake process. This API handles documents related to the following benefit claim types: 

    * Compensation
    * Pension/Survivors Benefits
    * Education
    * Fiduciary
    * Insurance
    * Veteran Readiness & Employment (VRE)
    * Board of Veteran Appeals (BVA)

    This API also provides submission status updates until documents are successfully established for VBA claim processing, eliminating the need for users to switch between systems to manually check whether documents have been successfully uploaded.

    ## Background 
    This API provides a secure, efficient, and tracked alternative to mail or fax for VA benefit claim document submissions. Documents are uploaded directly to the VBA so they can be processed as quickly as possible.

    ## Technical overview
    The Benefits Intake API first provides an upload location and unique submission identifier, and then accepts a payload consisting of a document in PDF format, zero or more optional attachments in PDF format, and some JSON metadata. 

    The metadata describes the document and attachments, and identifies the person for whom it is being submitted. This payload is encoded as binary multipart/form-data (not base64). The unique identifier supplied with the payload can subsequently be used to request the processing status of the uploaded document package.

    To avoid errors and processing delays, API consumers are encouraged to validate the `zipcode`,`fileNumber`, `veteranFirstName`, `veteranLastName` and `businessLine` fields before submission according to their description in the DocumentUploadMetadata model and use the 'businessLine' attribute for the most efficient processing. Additionally, please ensure no PDF user passwords are used in submitted PDFs. 

    ### Attachment & file size limits
    There is no limit on the number of files a payload can contain, but size limits do apply.

    * Uploaded documents cannot be larger than 21" x 21"
    * The entire payload cannot exceed 5 GB
    * No single file in a payload can exceed 100 MB

    ### Date of receipt
    The date that documents are successfully submitted through the Benefits Intake API is used as the official VA date of receipt. However, note that until a document status of `received`, `processing`, `success`, or `vbms` is returned, a client cannot consider the document received by VA. 

    A status of `received` means that the document package has been transmitted, but may not be validated. Any errors with the document package, such as unreadable PDFs or a Veteran not found, will cause the status to change to `error`.

    If the document status is `error`, VA has not received the submission and cannot honor the submission date as the date of receipt.

    ### Authentication and Authorization
    API requests are authorized through a symmetric API token, provided in an HTTP header with name 'apikey'. [Request an API key.](https://developer.va.gov/apply)

    ### Testing in the sandbox environment
    In the sandbox environment, the final status of a submission is `received` and submissions do not actually progress to the central mail repository or VBMS. 

    Progress beyond the `received` status can be simulated for testing. We allow passing in a `Status-Override` header on the `/uploads/{id}` endpoint so that you can change the status of your submission to simulate the various scenarios. 

    The available statuses are `pending`, `uploaded`, `received`, `processing`, `success`, `vbms`, and `error`. The meaning of the various statuses is listed below in Models under DocumentUploadStatusAttributes.

    ### Test data
    We use mock test data in the sandbox environment. Data is not sent upstream and it is not necessary to align submitted test data with any other systems' data.

    ### Validating documents
    Use the POST `/uploads/validate_document` endpoint to make sure your documents will pass system file requirements and
    validations before you send them through the submissions process. This step is optional but decreases the likelihood
    of individual document errors during the submission process.

    Validations performed:
    * Document is a valid PDF (Note: `Content-Type` header value must be "application/pdf")
    * Document does not have a user password (an owner password is acceptable)
    * File size does not exceed 100 MB
    * Page size does not exceed 21" x 21"

    ### Upload operation
    Allows a client to upload a multi-part document package (form + attachments + metadata).

    1. Client Request: POST https://sandbox-api.va.gov/services/vba_documents/v1/
        * No request body or parameters required

    2. Service Response: A JSON API object with the following attributes:
        * `guid`: An identifier used for subsequent status requests
        * `location`: A URL to which the actual document package payload can be submitted in the next step. The URL is specific to this upload request, and should not be re-used for subsequent uploads. The URL is valid for 900 seconds (15 minutes) from the time of this response. If the location is not used within 15 minutes, the GUID will expire. Once expired, status checks on the GUID will return a status of `expired`.
            * Note: If, after you've submitted a document, the status hasn't changed to `uploaded` before 15 minutes has elapsed, we recommend retrying the upload in order to make sure the document properly reaches our servers. If the upload continues to fail, try encoding the payload as Base64 (See below).

     3. Client Request: PUT to the location URL returned in Step 2.
        * Request body should be encoded as binary multipart/form-data (base64 also available - see details below), equivalent to that generated by an HTML form submission or using "curl -F…". The format is described in more detail below.
        * No `apikey` authorization header is required for this request, as authorization is embedded in the signed location URL.

    4. Service Response: The HTTP status indicates whether the upload was successful.
        * Additionally, the response includes an ETag header containing an MD5 hash of the submitted payload. This can be compared to the submitted payload to ensure data integrity of the upload.

    ### Status caching
    Due to current system limitations, data for the `/uploads/report` endpoint is cached for one hour.

    A request to the `/uploads/{id}` endpoint will return a real-time status for that GUID, and update its status in `/uploads/report`.

    The `updated_at` field indicates the last time the status for a given GUID was updated.

    ### Document Submission Statuses
    **Important note:** a submission has not been received by VA until it has a status of Received, Processing, Success, 
    or VBMS. Detailed descriptions of what each status means are found in this table.

    | Status        | What it means |
    | ---           |     ---     |
    | **Pending**   | Initial status.<br /><br />Indicates no document package has been uploaded yet.<br /><br />Date of Receipt is not yet established with this status |
    | **Uploaded**  | Indicates document package has been successfully uploaded (PUT) from your system to the API server but has not yet been validated.<br /><br />Date of Receipt is not yet established with this status. Any errors with the document package, such as having an unreadable PDF, may cause an Error status. |
    | **Received**  | Indicates document package has been received upstream of the API and is awaiting Processing.<br /><br />The VA Date of Receipt is set when this status is achieved.<br /><br />This is the final status in the sandbox environment unless further progress is simulated. |
    | **Processing**| Indicates the document package is being validated, processed, and made ready to route and work. |
    | **Success**   | Indicates the document package has been successfully received within VA's mail handling system.<br /><br />Success is the final status for a small percentage of submitted packages with claim types, Veteran types, or exception processes that are not worked in VBMS. Most submissions reach a Success status within 1 business day. A small portion will take longer; however, some submissions may take up to 2 weeks to reach a Success status. |
    | **VBMS**      | Indicates this document package was successfully uploaded into a Veteran's eFolder within VBMS.<br /><br />On average, submissions reach VBMS status within 3 business days; however, processing times vary and some submissions may remain in a Success status for several weeks before reaching a VBMS status.<br /><br />Some document packages are worked in VA systems other than VBMS. For these submissions, Success is the final status. |
    | **Error**     | Indicates that there was an error. Refer to the error code and message for further information. |
    | **Expired**   | After a POST request, there is a 15-minute window during which documents must be uploaded via a PUT request.<br /><br />An Expired status means the documents were not successfully uploaded within this 15-minute window. We recommend coding to retry unsuccessful uploads within 15 minutes using the same submission in case of connection issues. |

    ### Optional Base64 encoding

    Base64 is an encoding scheme that converts binary data into text format, so that encoded textual data can be easily transported over networks uncorrupted and without data loss. 

    Base64 can be used to encode binary multipart/form-data it in its entirety.  Note that the whole payload must be encoded, not individual parts/attachments.

    After encoding your payload, you'll be required to preface your base64 string with `data:multipart/form-data;base64,` in order to allow our system to distinguish the file type. Your final string payload would look something like `data:multipart/form-data;base64,(encryption string)==` and close with the standard == marker.  Note that the multipart boundaries i.e. -----WebKitFormBoundaryVfOwzCyvug0JmWYo and ending ------WebKitFormBoundaryVfOwzCyvug0JmWYo- must also be included.

    ### Consumer onboarding process
    When you're ready to move to production, [request a production API key.](https://developer.va.gov/go-live)
  title: Benefits Intake
  version: 1.0.0
  x-apisguru-categories:
    - open_data
  x-logo:
    url: https://prod-va-gov-assets.s3-us-gov-west-1.amazonaws.com/img/design/icons/apple-touch-icon.png
  x-origin:
    - format: openapi
      url: https://api.va.gov/services/vba_documents/docs/v1/api
      version: "3.0"
  x-providerName: va.gov
  x-serviceName: benefits
tags:
  - description: VA Benefits document upload functionality
    name: VBA Documents
paths:
  /path:
    put:
      description: |
        Accepts document metadata, document binary, and attachment binaries. Full URL, including
        query parameters, provided from POST `/document_uploads`.

        ## Example Payload

        The following demonstrates a (redacted) multipart payload suitable for submitting to the PUT
        endpoint. Most programming languages should have provisions for assembling a multipart
        payload like this without having to do so manually.

        ```
        --17de1ed8f01442b2a2d7a93506314b76
        Content-Disposition: form-data; name="metadata"
        Content-Type: application/json

        {"veteranFirstName": "Jane",
        "veteranLastName": "Doe",
        "fileNumber": "012345678",
        "zipCode": "97202",
        "source": "MyVSO",
        "docType": "21-22"
        "businessLine": "CMP"}
        --17de1ed8f01442b2a2d7a93506314b76
        Content-Disposition: form-data; name="content"
        Content-Type: application/pdf

        <Binary PDF contents>
        --17de1ed8f01442b2a2d7a93506314b76
        Content-Disposition: form-data; name="attachment1"
        Content-Type: application/pdf

        <Binary PDF attachment contents>
        --17de1ed8f01442b2a2d7a93506314b76--
        ```

        This PUT request would have an overall HTTP Content-Type header:

        ```
        Content-Type: multipart/form-data; boundary=17de1ed8f01442b2a2d7a93506314b76
        ```

        Note that the Content-Disposition parameter "name" in each part must be the expected values
        "metadata", "content", "attachment1"..."attachmentN". The attachment attributes must be named 
        exactly as they are listed here (case sensitive), for example: "attachment_1" or "Attachment2"
        are invalid.

        This is an example curl command:

        ```
        curl -v -L -X PUT '<Location from \uploads>' -F 'metadata="{\"veteranFirstName\": \"Jane\",\"veteranLastName\": \"Doe\",\"fileNumber\": \"012345678\",\"zipCode\": \"97202\",\"source\": \"MyVSO\",\"docType\": \"21-22\",\"businessLine\": \"CMP\"}";type=application/json' -F 'content=@"content.pdf"' -F 'attachment1=@"file1.pdf"' -F 'attachment2=@"another_file.pdf"'
        ```
      operationId: putBenefitsDocumentUpload
      parameters:
        - description: Base64-encoded 128-bit MD5 digest of the message. Use for integrity control
          in: header
          name: Content-MD5
          required: false
          schema:
            format: md5
            type: string
      responses:
        "200":
          description: Document upload staged
        "401":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: Error detail
                    example: Unauthorized Request
                    type: string
                required:
                  - data
                type: object
          description: Unauthorized request
        "403":
          content:
            application/xml:
              schema:
                $ref: "#/components/schemas/DocumentUploadFailure"
          description: Document upload failed
        "422":
          content:
            application/json:
              schema:
                properties:
                  errors:
                    items:
                      $ref: "#/components/schemas/ErrorModel"
                    type: array
                required:
                  - errors
                type: object
          description: Unprocessable Entity
        "429":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: message
                    example: API rate limit exceeded
                    type: string
                required:
                  - data
                type: object
          description: Too many requests
        "500":
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 500
                    type: string
                  detail:
                    description: Human readable error detail. Only present if status = "error"
                    example: Internal server error
                    type: string
                  status:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 500
                    type: string
                  title:
                    description: Human readable title description.
                    example: Internal server error
                    type: string
                required:
                  - data
                type: object
          description: Internal server error
      summary: Accepts document upload.
      tags:
        - VBA Documents
  /uploads:
    post:
      operationId: postBenefitsDocumentUpload
      responses:
        "202":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/DocumentUploadPath"
                required:
                  - data
                type: object
          description: Accepted. Location generated
        "401":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: Error detail
                    example: Unauthorized Request
                    type: string
                required:
                  - data
                type: object
          description: Unauthorized request
        "403":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: Error detail
                    example: Invalid authentication credentials
                    type: string
                required:
                  - data
                type: object
          description: Forbidden
        "422":
          content:
            application/json:
              schema:
                properties:
                  errors:
                    items:
                      $ref: "#/components/schemas/ErrorModel"
                    type: array
                required:
                  - errors
                type: object
          description: Unprocessable Entity
        "429":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: message
                    example: API rate limit exceeded
                    type: string
                required:
                  - data
                type: object
          description: Too many requests
        "500":
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 500
                    type: string
                  detail:
                    description: Human readable error detail. Only present if status = "error"
                    example: Internal server error
                    type: string
                  status:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 500
                    type: string
                  title:
                    description: Human readable title description.
                    example: Internal server error
                    type: string
                required:
                  - data
                type: object
          description: Internal server error
      security:
        - apikey: []
      summary: Get a location for subsequent document upload PUT request
      tags:
        - VBA Documents
  /uploads/report:
    post:
      operationId: getBenefitsDocumentUploadStatusReport
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DocumentUploadStatusGuidList"
        description: List of GUIDs for which to retrieve current status
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/DocumentUploadStatusReport"
                required:
                  - data
                type: object
          description: Upload status report retrieved successfully
        "400":
          description: Bad Request - invalid or missing list of guids
        "401":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: Error detail
                    example: Unauthorized Request
                    type: string
                required:
                  - data
                type: object
          description: Unauthorized request
        "403":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: Error detail
                    example: Invalid authentication credentials
                    type: string
                required:
                  - data
                type: object
          description: Forbidden
        "422":
          content:
            application/json:
              schema:
                properties:
                  errors:
                    items:
                      $ref: "#/components/schemas/ErrorModel"
                    type: array
                required:
                  - errors
                type: object
          description: Unprocessable Entity
        "429":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: message
                    example: API rate limit exceeded
                    type: string
                required:
                  - data
                type: object
          description: Too many requests
        "500":
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 500
                    type: string
                  detail:
                    description: Human readable error detail. Only present if status = "error"
                    example: Internal server error
                    type: string
                  status:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 500
                    type: string
                  title:
                    description: Human readable title description.
                    example: Internal server error
                    type: string
                required:
                  - data
                type: object
          description: Internal server error
      security:
        - apikey: []
      summary: Get a bulk status report for a list of previous uploads
      tags:
        - VBA Documents
  /uploads/validate_document:
    post:
      description: |
        Using this endpoint will decrease the likelihood of errors associated with individual documents during
        the submission process. Validations performed:
        * Document is a valid PDF (Note: `Content-Type` header value must be "application/pdf")
        * Document does not have a user password (an owner password is acceptable)
        * File size does not exceed 100 MB
        * Page size does not exceed 21" x 21"

        Each PDF document is sent as a direct file upload. The request body should contain nothing other than the document in
        binary format. Binary multipart/form-data encoding is not supported. This endpoint does NOT validate metadata in JSON
        format.

        This endpoint does NOT initiate the claims intake process or submit data to that process. After using this endpoint,
        individual PDF documents can be combined and submitted as a payload using PUT `/path`.

        A `200` response confirms that the individual document provided passes the system requirements.

        A `422` response indicates one or more problems with the document that should be resolved before submitting it in the
        full document submission payload.
      operationId: postBenefitsDocumentUploadValidateDocument
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      attributes:
                        properties:
                          status:
                            example: valid
                            type: string
                        type: object
                      type:
                        description: schema type
                        example: documentValidation
                        type: string
                type: object
          description: Document passed system requirements
        "401":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: Error detail
                    example: Unauthorized Request
                    type: string
                required:
                  - data
                type: object
          description: Unauthorized request
        "403":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: Error detail
                    example: Invalid authentication credentials
                    type: string
                required:
                  - data
                type: object
          description: Forbidden
        "422":
          content:
            application/json:
              schema:
                properties:
                  errors:
                    items:
                      $ref: "#/components/schemas/DocumentValidationErrorModel"
                    type: array
                required:
                  - errors
                type: object
          description: Document did NOT pass system requirements
        "429":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: message
                    example: API rate limit exceeded
                    type: string
                required:
                  - data
                type: object
          description: Too many requests
        "500":
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 500
                    type: string
                  detail:
                    description: Human readable error detail. Only present if status = "error"
                    example: Internal server error
                    type: string
                  status:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 500
                    type: string
                  title:
                    description: Human readable title description.
                    example: Internal server error
                    type: string
                required:
                  - data
                type: object
          description: Internal server error
      summary: Validate an individual document against system file requirements
      tags:
        - VBA Documents
  "/uploads/{id}":
    get:
      operationId: getBenefitsDocumentUploadStatus
      parameters:
        - description: ID as returned by a previous create upload request
          example: 6d8433c1-cd55-4c24-affd-f592287a7572
          in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: "#/components/schemas/DocumentUploadStatus"
                required:
                  - data
          description: Upload status retrieved successfully
        "401":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: Error detail
                    example: Unauthorized Request
                    type: string
                required:
                  - data
                type: object
          description: Unauthorized request
        "403":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: Error detail
                    example: Invalid authentication credentials
                    type: string
                required:
                  - data
                type: object
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 404
                    type: string
                  detail:
                    description: Human readable error detail. Only present if status = "error"
                    example: The record identified by {{id}} could not be found
                    type: string
                  status:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 404
                    type: string
                  title:
                    description: Human readable title description.
                    example: Record not found
                    type: string
                required:
                  - data
                type: object
          description: Not found
        "429":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: message
                    example: API rate limit exceeded
                    type: string
                required:
                  - data
                type: object
          description: Too many requests
        "500":
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 500
                    type: string
                  detail:
                    description: Human readable error detail. Only present if status = "error"
                    example: Internal server error
                    type: string
                  status:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 500
                    type: string
                  title:
                    description: Human readable title description.
                    example: Internal server error
                    type: string
                required:
                  - data
                type: object
          description: Internal server error
      security:
        - apikey: []
      summary: Get status for a previous benefits document upload
      tags:
        - VBA Documents
  "/uploads/{id}/download":
    get:
      description: An endpoint that will allow you to see exactly what the server sees. We split apart all submitted docs and metadata and zip the file to make it available to you to help with debugging purposes. Files are deleted after 10 days. Only available in testing environments, not production.
      operationId: getBenefitsDocumentUploadDownload
      parameters:
        - description: ID as returned by a previous create upload request
          example: 6d8433c1-cd55-4c24-affd-f592287a7572
          in: path
          name: id
          required: true
          schema:
            format: uuid
            type: string
      responses:
        "200":
          content:
            application/zip:
              schema:
                example: Binary File
                format: binary
                type: string
          description: Zip file with the contents of your payload as parsed by our server
        "401":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: Error detail
                    example: Unauthorized Request
                    type: string
                required:
                  - data
                type: object
          description: Unauthorized request
        "403":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: Error detail
                    example: Invalid authentication credentials
                    type: string
                required:
                  - data
                type: object
          description: Forbidden
        "404":
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 404
                    type: string
                  detail:
                    description: Human readable error detail. Only present if status = "error"
                    example: The record identified by {{id}} could not be found
                    type: string
                  status:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 404
                    type: string
                  title:
                    description: Human readable title description.
                    example: Record not found
                    type: string
                required:
                  - data
                type: object
          description: Not found
        "429":
          content:
            application/json:
              schema:
                properties:
                  Message:
                    description: message
                    example: API rate limit exceeded
                    type: string
                required:
                  - data
                type: object
          description: Too many requests
        "500":
          content:
            application/json:
              schema:
                properties:
                  code:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 500
                    type: string
                  detail:
                    description: Human readable error detail. Only present if status = "error"
                    example: Internal server error
                    type: string
                  status:
                    description: |
                      Unambiguous status code. Only present if status = "error"

                      * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
                      * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
                      * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
                      * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
                      * `DOC105` - Invalid or unknown id
                      * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
                      * `DOC107` - Empty payload.
                      * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
                      * `DOC201` - Upload server error.
                      * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
                    example: 500
                    type: string
                  title:
                    description: Human readable title description.
                    example: Internal server error
                    type: string
                required:
                  - data
                type: object
          description: Internal server error
      security:
        - apikey: []
      summary: Download zip of "what the server sees"
      tags:
        - VBA Documents
components:
  examples: {}
  links: {}
  parameters: {}
  requestBodies: {}
  responses: {}
  schemas:
    DocumentUploadAttributes:
      properties:
        code:
          description: |
            Unambiguous status code. Only present if status = "error"

            * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
            * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
            * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
            * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
            * `DOC105` - Invalid or unknown id
            * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
            * `DOC107` - Empty payload.
            * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
            * `DOC201` - Upload server error.
            * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
          type: string
        detail:
          description: Human readable error detail. Only present if status = "error"
          type: string
        guid:
          description: The document upload identifier
          example: 6d8433c1-cd55-4c24-affd-f592287a7572
          format: uuid
          type: string
        location:
          description: Location to which to PUT document Payload
          example: https://sandbox-api.va.gov/services_user_content/vba_documents/{idpath}
          format: uri
          type: string
        status:
          description: |
            Document upload status.
          enum:
            - pending
            - uploaded
            - received
            - processing
            - success
            - vbms
            - error
          example: pending
          type: string
        updated_at:
          description: The last time the submission was updated
          example: 2018-07-30T17:31:15.958Z
          format: date-time
          type: string
        uploaded_pdf:
          description: Only populated after submission starts processing
          example: "null"
      required:
        - guid
        - status
    DocumentUploadFailure:
      description: Document upload failed
      properties:
        Code:
          description: Error code
          example: SignatureDoesNotMatch
          type: string
        Message:
          description: Error detail
          example: The request signature we calculated does not match the signature you provided. Check your key and signing method.
          type: string
      type: object
      xml:
        name: Error
    DocumentUploadMetadata:
      description: Identifying properties about the document payload being submitted
      properties:
        businessLine:
          description: |
            Optional parameter (can be missing or empty). The values are:<br><br>
            CMP - Compensation requests such as those related to disability, unemployment, and pandemic claims<br><br>
            PMC - Pension requests including survivor’s pension<br><br>
            INS - Insurance such as life insurance, disability insurance, and other health insurance<br><br>
            EDU - Education benefits, programs, and affiliations<br><br>
            VRE - Veteran Readiness & Employment such as employment questionnaires, employment discrimination, employment verification<br><br>
            BVA - Board of Veteran Appeals<br><br>
            FID - Fiduciary / financial appointee, including family member benefits<br><br>
            NCA - National Cemetery Administration<br><br>
            OTH - Other (this value if used, will be treated as CMP)<br>
          enum:
            - CMP
            - PMC
            - INS
            - EDU
            - VRE
            - BVA
            - FID
            - NCA
            - OTH
          example: CMP
          type: string
        docType:
          description: VBA form number of the document
          example: 21-22
          type: string
        fileNumber:
          description: The Veteran's file number is exactly 9 digits with no alpha characters, hyphens, spaces or punctuation. In most cases, this is the Veteran's SSN but may also be an 8 digit BIRL number. If no file number has been established or if it is unknown, the application should use the Veteran's SSN and the file number will be associated with the submission later in the process. Incorrect file numbers can cause delays.
          example: "999887777"
          pattern: ^\d{8,9}$
          type: string
        source:
          description: System, installation, or entity submitting the document
          example: MyVSO
          type: string
        veteranFirstName:
          description: Veteran first name. Cannot be missing or empty or longer than 50 characters. Only upper/lower case letters, hyphens(-), spaces and forward-slash(/) allowed.
          example: Jane
          pattern: ^[a-zA-Z\-\/\s]{1,50}$
          type: string
        veteranLastName:
          description: Veteran last name. Cannot be missing or empty or longer than 50 characters. Only upper/lower case letters, hyphens(-), spaces and forward-slash(/) allowed.
          example: Doe-Smith
          pattern: ^[a-zA-Z\-\/\s]{1,50}$
          type: string
        zipCode:
          description: Veteran zip code. Either five digits (XXXXX) or five digits then four digits separated by a hyphen (XXXXX-XXXX). Use '00000' for Veterans with non-US addresses.
          example: "20571"
          type: string
      required:
        - veteranFirstName
        - veteranLastName
        - fileNumber
        - zipCode
        - source
      type: object
    DocumentUploadPath:
      description: Status record for a previously initiated document submission.
      properties:
        attributes:
          $ref: "#/components/schemas/DocumentUploadAttributes"
        id:
          description: JSON API identifier
          example: 6d8433c1-cd55-4c24-affd-f592287a7572
          format: uuid
          type: string
        type:
          description: JSON API type specification
          example: document_upload
          type: string
      required:
        - id
        - type
        - attributes
    DocumentUploadStatus:
      description: Status record for a previously initiated document submission.
      properties:
        attributes:
          $ref: "#/components/schemas/DocumentUploadStatusAttributes"
        id:
          description: JSON API identifier
          example: 6d8433c1-cd55-4c24-affd-f592287a7572
          format: uuid
          type: string
        type:
          description: JSON API type specification
          example: document_upload
          type: string
      required:
        - id
        - type
        - attributes
    DocumentUploadStatusAttributes:
      properties:
        code:
          description: |
            Unambiguous status code. Only present if status = "error"

            * `DOC101` - Invalid multipart payload provided - not a multipart, or missing one or more required parts.
            * `DOC102` - Invalid metadata - not parseable as JSON, incorrect fields, etc.
            * `DOC103` - Invalid content - not parseable as PDF. Detail field will indicate which document or attachment part was affected.
            * `DOC104` - Upload rejected by upstream system. Processing failed and upload must be resubmitted. Detail field will indicate nature of rejection.
            * `DOC105` - Invalid or unknown id
            * `DOC106` - File size limit exceeded. Each document may be a maximum of 100MB.
            * `DOC107` - Empty payload.
            * `DOC108` - Maximum dimensions exceeded. Height and width must be less than 21 in x 21 in.
            * `DOC201` - Upload server error.
            * `DOC202` - Error during processing by upstream system. Processing failed and upload must be resubmitted. Detail field will provide additional details where available.
          type: string
        detail:
          description: Human readable error detail. Only present if status = "error"
          type: string
        guid:
          description: The document upload identifier
          example: 6d8433c1-cd55-4c24-affd-f592287a7572
          format: uuid
          type: string
        message:
          description: Human readable error description. Only present if status = "error"
          type: string
        status:
          description: |
            Document upload status.
          enum:
            - pending
            - uploaded
            - received
            - processing
            - success
            - vbms
            - error
          example: received
          type: string
        updated_at:
          description: The last time the submission was updated
          example: 2018-07-30T17:31:15.958Z
          format: date-time
          type: string
        uploaded_pdf:
          $ref: "#/components/schemas/PdfUploadAttributes"
      required:
        - guid
        - status
    DocumentUploadStatusGuidList:
      properties:
        ids:
          description: List of IDs for previous document upload submissions
          items:
            example: 6d8433c1-cd55-4c24-affd-f592287a7572
            format: uuid
            type: string
          maxItems: 1000
          minItems: 1
          type: array
      required:
        - ids
      type: object
    DocumentUploadStatusReport:
      items:
        $ref: "#/components/schemas/DocumentUploadStatus"
      type: array
    DocumentUploadSubmission:
      description: Record of requested document submission. Includes the location to which the document payload is to be uploaded
      properties:
        attributes:
          $ref: "#/components/schemas/DocumentUploadSubmissionAttributes"
        id:
          description: JSON API Identifier
          example: 6d8433c1-cd55-4c24-affd-f592287a7572
          format: uuid
          type: string
        type:
          description: JSON API type specification
          example: document_upload
          type: string
      required:
        - id
        - type
        - attributes
    DocumentUploadSubmissionAttributes:
      allOf:
        - required:
            - location
          type: object
        - $ref: "#/components/schemas/DocumentUploadStatusAttributes"
          properties:
            location:
              description: Location to which to PUT document Payload
              example: https://sandbox-api.va.gov/services_user_content/vba_documents/{idpath}
              format: uri
              type: string
    DocumentValidationErrorModel:
      description: Error returned from the document validation endpoint.
      properties:
        detail:
          description: |
            Error detail

            Possible values:
            * Document was not provided
            * Document is not a PDF
            * Document exceeds the file size limit of 100 MB
            * Document exceeds the page size limit of 21 in. x 21 in.
            * Document is locked with a user password
            * Document is not a valid PDF
          example: Document is locked with a user password
          type: string
        status:
          description: HTTP error code
          example: "422"
          type: string
        title:
          description: Error title
          example: Document failed validation
          type: string
      required:
        - title
        - detail
        - status
      type: object
    ErrorModel:
      description: Errors with some details for the given request
      properties:
        detail:
          description: A more detailed message about why an error occurred
          example: DOC104 - Upload rejected by upstream system. Processing failed and upload must be resubmitted
          type: string
        status:
          description: Standard HTTP Status returned with Error
          example: "422"
          format: int32
          type: integer
      required:
        - status
        - detail
    PdfDimensionAttributes:
      properties:
        height:
          description: The document height
          example: "11.0"
          type: integer
        oversized_pdf:
          description: Indicates if this is an oversized PDF (greater than 21x21)
          example: "false"
          type: boolean
        width:
          description: The document width
          example: "8.5"
          type: integer
      required:
        - height
        - width
        - oversized_pdf
    PdfUploadAttributes:
      properties:
        content:
          properties:
            attachments:
              items:
                properties:
                  dimensions:
                    $ref: "#/components/schemas/PdfDimensionAttributes"
                  page_count:
                    description: The number of pages in this attachment
                    example: "2"
                    type: integer
              type: array
            dimensions:
              $ref: "#/components/schemas/PdfDimensionAttributes"
            page_count:
              description: The total number of pages solely in this PDF document
              example: "1"
              type: integer
        total_documents:
          description: The total number of documents contained in this upload
          example: "2"
          type: integer
        total_pages:
          description: The total number of pages contained in this upload
          example: "3"
          type: integer
      required:
        - total_documents
        - total_pages
        - content
        - dimensions
        - attachments
  securitySchemes:
    apikey:
      in: header
      name: apikey
      type: apiKey
