{"openapi":"3.0.1","info":{"title":"VA Loan Guaranty - Loan Review REST API","description":"

The Loan Review API lets lenders transmit post-close loan review related documents. This API lets lenders:

Background

Department of Veterans Affairs (VA) helps service members, Veterans, and eligible surviving spouses become homeowners. As part of our mission to serve Veterans, we provide a home loan guaranty benefit and other housing-related programs to help Veterans buy, build, repair, retain, or adapt a home for personal occupancy.

VA home loans are provided by private lenders, such as banks and mortgage companies. VA guarantees a portion of the loan, enabling the lender to provide Veterans with more favorable terms.

Today, lenders must login to WebLGY to manually upload documentation in support of a Full File Loan Review (FFLR) request.

The Loan Review API streamlines the submission of documentation in support of a Full File Loan Review (FFLR) request. The Loan Review API:

  1. Allows lenders to remain in their Loan Origination System (LOS) for these interactions with VA, and
  2. Reduces manual data entry, saving time and improving data accuracy.

Technical Overview

You can learn about how the VA Home Loan Guaranty process works by visiting the Home Loans Technology Knowledge Center website. Specific, detailed technical information related to this API can be found in our companion document.

Some endpoints limit the number of files a payload can contain, and you can find those limitations within the endpoint details. Size limits do apply:

There is also a validation to ensure the file type included in a file name matches the file type of the file being uploaded. (e.g., If the file type is PDF, the API will validate that the file is in PDF format.)

Authentication and Authorization

The authentication model for the Loan Review API is based on OAuth 2.0 / OpenID Connect and supports the client credentials grant.

Test Data

The database powering our sandbox environment is populated with Veteran and loan test data. Sandbox test data mimics real Veteran data but but contains no protected health information or personally identifiable information. The LIN in your API request must match the LIN captured in the UCD and ULAD XMLs. Detailed testing information can be found on the Technology Knowledge Center Loan Review API page.

","version":"26.2.1.0"},"servers":[{"url":"https://sandbox-api.va.gov/services/loan-review/{version}","description":"Sandbox","variables":{"version":{"default":"v1"}}},{"url":"https://api.va.gov/services/loan-review/{version}","description":"Production","variables":{"version":{"default":"v1"}}}],"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":{"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}"},"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}"},"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}"},"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}"},"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}"},"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}"},"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}"},"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}"},"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"}}}},"LgyFieldError":{"required":["message"],"type":"object","properties":{"message":{"type":"string"},"rejectedValue":{"type":"string"},"field":{"type":"string"}}},"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."},"LoanReviewExceptionResponse":{"type":"object","properties":{"timestamp":{"type":"integer","description":"The UNIX time representation of when the request was received by the server. See .","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."},"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."},"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."},"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."},"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":{"oauth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://staging-api.va.gov/oauth2/loan-guaranty/system/v1/token","scopes":{"system.loan-review.write":"Transmit loan review documents"}}}}}}}