openapi: 3.0.1
info:
  title: Address Validation 5103 Waiver loanReviewPublic API
  description: "The Address Validation API accepts and validates an address and standardizes it for mailing. It can also help you process an address by:\n* Inferring missing or incorrect address components\n* Supplementing an address with additional information, such as geocode, latitude and longitude, and postal service metadata (when available)\n## Technical Overview\nThe Address Validation API returns validated addresses as they appear in the USPS database for domestic addresses. It validates by separating the address into individual components and then providing component-level validation checks.\n\nThis API is certified by the United States Postal Service (USPS) Coding Accuracy Support System (CASS) and adheres to [United States Postal Service (USPS) Publication 28 standards](https://pe.usps.com/text/pub28/welcome.htm) for domestic, military, and US territory addresses.\n\nFor international addresses, validation relies on Universal Postal Union (UPU) standards. \n\n## Validation\nIf an address is found, it is considered valid based on metadata returned by the Address Validation service, such as the confidence score and the [Delivery Point Validation (DPV)](https://postalpro.usps.com/address-quality/dpv).\n\nIf an address is found, there are multiple checks performed on the validated address. The address can fail validation for a variety of reasons, such as the inability to deliver (for domestic mailing addresses) or the format. For specific reasons why an address failed, refer to the error messages returned.\n\nIf an address is not found, it automatically fails validation.\n\n## Address override indicator\nSometimes an entered address is accurate for a Veteran but does not pass validation rules. These instances can occur when an address is newer than what is in the CASS software or in regions where address data is less accurate.\n\nSystems can accept these addresses despite the lack of address validation by submitting an \"accepted address\" (usually confirmed by the Veteran) to the Contact Information API (see Requirements below). An address is considered accepted after the address has been sent to the validation API and has failed validation, but the Veteran has confirmed the address is correct as entered. The accepted address can then be passed to the Contact Information API using an address override indicator set to show that the validation was overridden. To set an override indicator, the original address and the `overrideValidationKey` returned in the validation API response must be provided to the Contact Information API, in order to prove that a validation attempt has been made before overriding.\n\n## Version Interoperability\n\nTo ensure interoperability between APIs and eliminate the need for transforming data as one API feeds into the other, we strongly recommend using versions of the following APIs that are compatible.\n\n|     <h3>If Using</h3>           | <h3>Then Use...</h3>                           |\n| :------------------------------:|:----------------------------------------------:|\n| Address Validation API v1/v2    | Contact Information API v1<br><br>Profile Service API v1/v2 |\n| Address Validation API v3       | Contact Information API v2<br><br>Profile Service API v3    |\n\n## Authorization\nAPI requests are authorized through a symmetric API token provided in an HTTP header with name apikey.\n\n**Important**: To get production access, you must either work for VA or have specific VA agreements in place. If you have questions, [contact us](https://developer.va.gov/support/contact-us)."
  license:
    name: Creative Commons
    url: https://developer.va.gov/terms-of-service
  version: '3'
servers:
- url: https://sandbox-api.va.gov/services/address-validation/{version}
  description: Sandbox
  variables:
    version:
      default: v3
- url: https://api.va.gov/services/address-validation/{version}
  description: Production
  variables:
    version:
      default: v3
security:
- apikey: []
tags:
- name: loanReviewPublic
  description: Loan Review Public Resource
paths:
  /transmit-documents:
    post:
      tags:
      - loanReviewPublic
      summary: Transmit documents for FFLR loan review
      description: This resource allows lenders to upload the post-close loan review package file along with final UCD/ULAD xmls. Only one loan review package file, one UCD xml, and one ULAD xml may be included.
      operationId: POST:/transmit-documents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoanReviewTransmitDocsRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanReviewTransmitDocsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
        '401':
          description: Unauthorized
          headers:
            WWW-Authenticate:
              description: Defines the authentication method that clients must use to gain access to the resource.
              style: simple
              schema:
                type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: Request size limit exceeded
        '415':
          description: Unsupported Media Type
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ExceptionResponse'
        '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/InternalError'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanReviewExceptionResponse'
        '503':
          description: Service Unavailable
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ExceptionResponse'
        '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:
        - system.loan-review.write
  /additional-documents:
    post:
      tags:
      - loanReviewPublic
      summary: Transmit additional documents for FFLR loan review
      description: The loan selected for post-close loan review that the lender is providing pdfs of additional documents not provided in the initial remittance of the loan for post-close loan review. Up to 5 PDFs may be included, ideally consolidated into one PDF when possible, where all files in the submission align to a single documentType (either 'LR File' or 'LR Deficiency'). Files of both types should not be included in the same additional-documents submission. Optionally, one UCD xml, and/or one ULAD xml may be included.
      operationId: POST:/additional-documents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoanReviewAdditionalDocsRequest'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanReviewTransmitDocsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdditionalDocBadRequest'
        '401':
          description: Unauthorized
          headers:
            WWW-Authenticate:
              description: Defines the authentication method that clients must use to gain access to the resource.
              style: simple
              schema:
                type: string
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdditionalDocForbidden'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdditionalDocNotFound'
        '413':
          description: Payload too large
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                example:
                  message: Request size limit exceeded
        '415':
          description: Unsupported Media Type
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ExceptionResponse'
        '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/AdditionalDocInternalError'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanReviewExceptionResponse'
        '503':
          description: Service Unavailable
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/ExceptionResponse'
        '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:
        - system.loan-review.write
components:
  schemas:
    AdditionalDocNotFound:
      example: "{\n  \"timestamp\" : 1544224725393,\n  \"status\" : 404,\n  \"lgyRequestUuid\" : \"d9fb08f3c9f9a084\",\n  \"errors\" : [ {\n    \"message\" : \"LIN 202060874991 not found.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  } ]\n}"
    LoanReviewTransmitDocsRequest:
      required:
      - loanIdentifier
      - loanReviewPackageFile
      - xmlUCDBase64
      - xmlULADBase64
      type: object
      properties:
        loanIdentifier:
          pattern: '[\d]{12}'
          type: string
          description: The twelve digit VA Loan Identification Number (LIN) without dashes on the loan selected for loan review for which the lender is providing documents for. This number is generated for a prospective loan and provided to the lender when the VA appraisal or IRRRL is ordered through WebLGY.
          example: '101010101010'
        loanReviewPackageFile:
          type: string
          description: Base 64 encoded PDF of the documents required by VA to conduct its post-close loan review. Documents should be lumped together into a single PDF in the stacking order and submitted in this field. Only one file may be included.
          example: dGVzdHN0cmluZw==
        xmlUCDBase64:
          type: string
          description: The final Uniform Closing Dataset conformant XML for the loan whose documents are being remitted for VA post-close loan review expressed in MISMO Residential Reference model version 3.3. Only one file may be included.
          example: dGVzdHN0cmluZw==
        xmlULADBase64:
          type: string
          description: The final Uniform Loan Application Dataset conformant XML for the loan whose documents are being remitted for VA post-close loan review expressed in MISMO Residential Reference model version 3.4. Only one file may be included.
          example: dGVzdHN0cmluZw==
        filename:
          type: string
          description: The name of the file. If one is not provided, it will be automatically assigned.
          example: Evidence.pdf
      description: Request payload interface for lender to transmit documents of a loan selected for post-close loan review, including the final UCD and ULAD XMLs.
    NotFound:
      example: "{\n  \"timestamp\" : 1544224725393,\n  \"status\" : 404,\n  \"lgyRequestUuid\" : \"d9fb08f3c9f9a084\",\n  \"errors\" : [ {\n    \"message\" : \"LIN 202060874991 not found.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  } ]\n}"
    ExceptionResponse:
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
        status:
          type: integer
          format: int32
        lgyRequestUuid:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/LgyFieldError'
    Forbidden:
      example: "{\n  \"timestamp\" : 1544224725393,\n  \"status\" : 403,\n  \"lgyRequestUuid\" : \"d9fb08f3c9f9a084\",\n  \"errors\" : [ {\n    \"message\" : \"Your account was deactivated due to inactivity for 90 days or more. To reactivate your account, please work with your Lender Admin to have your Account reactivated.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  } ]\n}"
    LoanReviewExceptionResponse:
      type: object
      properties:
        timestamp:
          type: integer
          description: The UNIX time representation of when the request was received by the server. See <https://en.wikipedia.org/wiki/Unix_time>.
          format: int64
          example: 1544224725393
        status:
          type: integer
          description: The HTTP response status code. May be removed in future versions of the API.
          format: int32
        lgyRequestUuid:
          type: string
          description: A unique request ID generated by the server. The primary purpose of this ID is forensic log investigation.
          example: a4c1b87031473607
        errors:
          type: array
          description: Collection of errors which were identified during the processing of the loan documents being remitted to VA to conduct a post-close review that are transmitted within the LoanReviewFieldError container under LoanReviewExceptionResponse schema.
          items:
            $ref: '#/components/schemas/LoanReviewFieldError'
      description: Response payload if errors are identified during the processing of the loan documents being remitted to VA to conduct a post-close review.
    BadRequest:
      example: "{\n  \"timestamp\" : 1544224725393,\n  \"status\" : 400,\n  \"lgyRequestUuid\" : \"d9fb08f3c9f9a084\",\n  \"errors\" : [ {\n    \"message\" : \"The UCD XML provided is not valid.\",\n    \"rejectedValue\" : \"dGVzdHN0cmluZw==\",\n    \"field\" : \"newLoan.ucdXmlBase64\"\n  }, {\n    \"message\" : \"The ULAD XML provided is not valid.\",\n    \"rejectedValue\" : \"dGVzdHN0cmluZw==\",\n    \"field\" : \"newLoan.uladXmlBase64\"\n  }, {\n    \"message\" : \"The request does not contain a UCD.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"UCD failed to upload because LIN is missing or does not match. Please ensure that the LOAN_IDENTIFIER field is present in the XML and has the correct LIN\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"ULAD failed to upload because LIN is missing or does not match. Please ensure that the LOAN_IDENTIFIER field is present in the XML and has the correct LIN\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"The request does not contain a ULAD.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"The request does not contain a LR File.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"The file size must not be greater than 524288000B\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"Documentation has already been uploaded. Please use the Additional Documents API if you wish to upload more.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"Internal Error - Unable to process UCD\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"Internal Error - Unable to process ULAD\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"Internal Error - Unable to process LR file.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"LIN provided is not ready for FFLR processing.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"The file {name} was not successfully submitted.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"The UCD XML Should only contain one LOAN element\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"The ULAD XML Should only contain one LOAN element\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  } ]\n}"
    AdditionalDocBadRequest:
      example: "{\n  \"timestamp\" : 1544224725393,\n  \"status\" : 400,\n  \"lgyRequestUuid\" : \"d9fb08f3c9f9a084\",\n  \"errors\" : [ {\n    \"message\" : \"The UCD XML provided is not valid.\",\n    \"rejectedValue\" : \"dGVzdHN0cmluZw==\",\n    \"field\" : \"newLoan.ucdXmlBase64\"\n  }, {\n    \"message\" : \"The ULAD XML provided is not valid.\",\n    \"rejectedValue\" : \"dGVzdHN0cmluZw==\",\n    \"field\" : \"newLoan.uladXmlBase64\"\n  }, {\n    \"message\" : \"The request does not contain a UCD.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"UCD failed to upload because LIN is missing or does not match. Please ensure that the LOAN_IDENTIFIER field is present in the XML and has the correct LIN\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"ULAD failed to upload because LIN is missing or does not match. Please ensure that the LOAN_IDENTIFIER field is present in the XML and has the correct LIN\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"The request does not contain a ULAD.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"The request does not contain a LR File.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"The file size must not be greater than 524288000B\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"Internal Error - Unable to process UCD\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"Internal Error - Unable to process ULAD\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"Too many files in the request. Please provide five files or less in the request.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"Internal Error - Unable to process LR file.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"Please provide at least one additional document in the request.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"Initial documentation has not been uploaded. Please use the Loan Review API before adding additional documentation.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"LIN provided is not ready for FFLR processing.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"The UCD XML Should only contain one LOAN element\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  }, {\n    \"message\" : \"The ULAD XML Should only contain one LOAN element\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  } ]\n}"
    AdditionalDocInternalError:
      example: "{\n  \"timestamp\" : 1544224725393,\n  \"status\" : 500,\n  \"lgyRequestUuid\" : \"d9fb08f3c9f9a084\",\n  \"errors\" : [ {\n    \"message\" : \"Internal Error - An unexpected error occurred\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  } ]\n}"
    AdditionalDocument:
      required:
      - description
      - documentType
      - fileType
      - lrFileBase64
      - name
      type: object
      properties:
        name:
          type: string
          description: Name of the additional document being provided to VA to conduct their Loan Review.
          example: abcd.pdf
        description:
          type: string
          description: Description of the additional document being provided to VA to conduct their Loan Review.
          example: Description of the additional document being provided to the VA to conduct their full file loan review
        documentType:
          pattern: LR File|LR Deficiency
          type: string
          description: General type of the document being submitted.
          example: LR File or LR Deficiency
        fileType:
          pattern: PDF
          type: string
          description: File type of the additional document being provided to VA to conduct their Loan Review. All documents provided to the VA for post-close loan review must be PDF.
          example: PDF
        lrFileBase64:
          type: string
          description: Base 64 encoded PDF of the document being provided for VA to conduct post-close loan review on the loan.
          example: dGVzdHN0cmluZw==
      description: Additional loan review document being provided by the lender.
    AdditionalDocForbidden:
      example: "{\n  \"timestamp\" : 1544224725393,\n  \"status\" : 403,\n  \"lgyRequestUuid\" : \"d9fb08f3c9f9a084\",\n  \"errors\" : [ {\n    \"message\" : \"Your account was deactivated due to inactivity for 90 days or more. To reactivate your account, please work with your Lender Admin to have your Account reactivated.\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  } ]\n}"
    InternalError:
      example: "{\n  \"timestamp\" : 1544224725393,\n  \"status\" : 500,\n  \"lgyRequestUuid\" : \"d9fb08f3c9f9a084\",\n  \"errors\" : [ {\n    \"message\" : \"Internal Error - An unexpected error occurred\",\n    \"rejectedValue\" : null,\n    \"field\" : null\n  } ]\n}"
    LoanReviewTransmitDocsResponse:
      type: object
      properties:
        success:
          type: boolean
          description: True if document transmission was successful or else false.
          example: true
      description: Response payload for lender to transmit documents of a loan selected for review.
    LgyFieldError:
      required:
      - message
      type: object
      properties:
        message:
          type: string
        rejectedValue:
          type: string
        field:
          type: string
    LoanReviewFieldError:
      required:
      - message
      type: object
      properties:
        message:
          type: string
          description: Detailed description of the error identified during the processing of the loan documents being remitted to VA to conduct a post-close review.
          example: Resource not found.
        rejectedValue:
          type: string
          description: The rejected value for a specific field prompting an error during the processing of the loan documents being remitted to VA to conduct a post-close review.
          example: '101010101010'
        field:
          type: string
          description: The field with a rejected value prompting an error during the processing of the loan documents being remitted to VA to conduct a post-close review.
          example: Loan Identifier
      description: Collection of errors which were identified during the processing of the loan documents being remitted to VA to conduct a post-close review that are transmitted within the LoanReviewFieldError container under LoanReviewExceptionResponse schema.
    LoanReviewAdditionalDocsRequest:
      required:
      - loanIdentifier
      type: object
      properties:
        loanIdentifier:
          pattern: '[\d]{12}'
          type: string
          description: The twelve digit VA Loan Identification Number (LIN) without dashes on the loan selected for loan review for which the lender is providing additional documents for. This number is generated for a prospective loan and provided to the lender when the VA appraisal or IRRRL is ordered through WebLGY.
          example: '101010101010'
        xmlUCDBase64:
          type: string
          description: The updated final Uniform Closing Dataset conformant XML for the loan whose documents are being remitted for VA post-close loan review expressed in MISMO Residential Reference model version 3.3. If the UCD is identical to the UCD provided with initial Loan Review document submission, there is no need to include it. Only one file may be included.
          example: dGVzdHN0cmluZw==
        xmlULADBase64:
          type: string
          description: The updated final Uniform Loan Application Dataset conformant XML for the loan whose documents are being remitted for VA post-close loan review expressed in MISMO Residential Reference model version 3.4. If the ULAD is identical to the ULAD provided with initial Loan Review document submission, there is no need to include it. Only one file may be included.
          example: dGVzdHN0cmluZw==
        additionalDocuments:
          type: array
          description: A collection of additional loan review documents being provided by the lender within the additionalDocuments container under the LoanReviewAdditionalDocsRequest schema. Up to 5 PDFs may be included, ideally consolidated into one PDF when possible, where all files in the submission align to a single documentType (either 'LR File' or 'LR Deficiency'). Files of both types should not be included in the same additional documents submission.
          items:
            $ref: '#/components/schemas/AdditionalDocument'
      description: Request payload interface for lender to transmit additional documents of a loan selected for post-close loan review, optionally including updated UCD and ULAD XMLs.
  securitySchemes:
    apikey:
      type: apiKey
      name: apikey
      in: header