VA Lighthouse Path API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Benefits Intake Path API
  description: The Benefits Intake API enables authorized third-party systems, such as those used by Veteran Service Organizations (VSOs), agencies, and Veterans, to digitally submit documents for VA benefits claims directly to the claims intake process of the Veterans Benefits Administration (VBA).
  contact:
    name: va.gov
servers:
- url: https://sandbox-api.va.gov/services/vba_documents/{version}
  description: Sandbox
  variables:
    version:
      default: v1
- url: https://api.va.gov/services/vba_documents/{version}
  description: Production
  variables:
    version:
      default: v1
basePath: /services/vba_documents/v1
consumes:
- application/json
produces:
- application/json
tags:
- name: Path
paths:
  /path:
    put:
      tags:
      - Path
      responses:
        '200':
          description: Document upload staged
        '401':
          description: Authorization information not provided
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: No API key found in request
        '403':
          description: Invalid authorization
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: You cannot consume this service
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: Request size limit exceeded
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                required:
                - errors
                properties:
                  errors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ErrorModel'
        '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:
                type: object
                required:
                - data
                properties:
                  title:
                    description: Human readable title description.
                    type: string
                    example: Internal server error
                  detail:
                    description: Human readable error detail. Only present if status = "error"
                    type: string
                    example: Internal server error
                  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 78 in x 101 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
                    example: 500
                  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 78 in x 101 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
                    example: 500
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: The server took too long to respond
      summary: Accepts document upload
      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


        --17de1ed8f01442b2a2d7a93506314b76

        Content-Disposition: form-data; name="attachment1"

        Content-Type: application/pdf


        --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 '''' -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: PUT:/path
      parameters:
      - name: Content-MD5
        in: header
        description: Base64-encoded 128-bit MD5 digest of the message. Use for integrity control
        required: false
        schema:
          type: string
          format: md5
components:
  schemas:
    ErrorModel:
      description: Errors with some details for the given request
      required:
      - status
      - detail
      properties:
        status:
          type: integer
          format: int32
          example: '422'
          description: Standard HTTP Status returned with Error
        detail:
          type: string
          example: DOC104 - Upload rejected by upstream system. Processing failed and upload must be resubmitted
          description: A more detailed message about why an error occurred
  securitySchemes:
    apikey:
      type: apiKey
      name: apikey
      in: header