{"openapi":"3.0.1","info":{"title":"VA Letter Generator API","description":"The VA Letter Generator API lets Veterans and their eligible dependents\ngenerate and download official VA letters with watermarks and logos.\nVeterans and their dependents may only generate and download letters\nfor which they are eligible. The letters will be populated with the\nVeteran's or eligible dependent's address, Veteran service details,\nand the Veteran's or dependent's benefits information when returned.\n\nThe letters that can be returned to a\nVeteran or dependent based on their eligibility are:\n\n* Service verification\n* Commissary access (including short term access)\n* Benefit verification\n* Proof of service\n* Medicare Part D\n* Minimum essential coverage\n* Civil service\n* VA benefit summary and award\n* VA benefit summary and award for dependents\n* Foreign Medical Program benefits authorization\n\n## Technical overview\nThe VA Letter Generator API uses a Veteran's or dependent's ICN to\ndetermine what letters they are eligible for and then generates\nthose letters.\nWhen using this API, keep in mind that:\n\n*  Letters generated are not retained by VA. If the Veteran or a\ndependent needs a replacement letter or if their eligibility changes,\nthey will need to generate a new letter.\n* Newly generated letters may differ from previously generated ones\nbecause this API returns only the most up-to-date information about\na Veteran and their dependents.\n* If the Veteran or eligible dependent needs to update their address,\nthey may do so through their [VA Profile](https://www.va.gov/sign-in/?oauth=false).\nUpdates are immediately available for this API.\n* Users having trouble downloading letters generated from this API should\ndownload the most recent version of Adobe Acrobat.\n* If a va_eauth_service_transaction_id was sent, the header of all API\nresponses (including error messages) will include it.\n\n### Authentication and Authorization\nThe authentication model for the VA Letter Generator API is based\non OAuth 2.0 / OpenID Connect and supports\n[client credentials grant](https://developer.va.gov/explore/authorization/docs/client-credentials?api=va_letter_generator).\n\n**Important**: To get production access using client credentials grant, you\nmust either work for VA or have specific VA agreements in place. If\nyou have questions, [contact us](https://developer.va.gov/support/contact-us).\n\n### Test data\n\nUse [test data](https://developer.va.gov/explore/api/va-letter-generator/test-users)\nto validate your application's integration with our API in the sandbox\nenvironment. Sandbox test data contains no PII or PHI but mimics\nVeterans' and dependents' addresses and benefits information.\n","contact":{"name":"VA.gov"},"version":"0.0.1"},"servers":[{"url":"https://sandbox-api.va.gov/services/va-letter-generator/{version}","description":"Sandbox","variables":{"version":{"default":"v1"}}},{"url":"https://api.va.gov/services/va-letter-generator/{version}","description":"Production","variables":{"version":{"default":"v1"}}}],"paths":{"/eligible-letters":{"get":{"tags":["Letters"],"summary":"Returns a list of letters that a Veteran or a dependent is eligible for.","description":"  The endpoint also returns the specific data that will be populated\n  within each eligible letter. This includes, if relevant:\n\n\n  * Veteran's or dependent's address\n  * Veteran service details\n  * Benefits information the Veteran or dependent is eligible for\n  * Survivor benefits awarded\n\n  If the API is able to determine eligibility for some but not all letters because\n  a partner is down, the list of letters for which a Veteran or dependent is\n  determined to be eligible will be returned, along with a\n  \"letterGeneration.letterEligibilityError\" message.\n","operationId":"GET:/eligible-letters","parameters":[{"name":"icn","in":"query","description":"MPI ICN","required":true,"schema":{"maxLength":17,"minLength":17,"pattern":"^\\d{10}V\\d{6}$","type":"string","example":"1000000000V100000"}}],"responses":{"200":{"description":"A Response which indicates a successful Request. The Response may contain \"messages\" that could describe warnings or further information.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LettersResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"type":"string","example":{"message":"Invalid authentication credentials"}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"string","example":{"message":"You cannot consume this service"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserNotFound"}}}},"406":{"description":"Not Acceptable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotAcceptable"}}}},"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":{"$ref":"#/components/schemas/UnprocessableEntity"}}}},"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/InternalServerError"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}},"security":[{"OAuth":[]}]}},"/letter-contents/{letterType}":{"get":{"tags":["Letters"],"summary":"Generates JSON-formatted letter content by letter type.","description":"Returns the descriptions and content of letters a Veteran or dependent is eligible for in JSON format.\n| If the GET /eligible-letters endpoint returns | Generate the letter contents with these query parameters |\n| --- | --- |\n| hasServiceConnectedDisabilities | serviceConnectedDisabilities |\n| serviceConnectedPercentage | serviceConnectedEvaluation |\n| hasNonServiceConnectedPension | nonServiceConnectedPension |\n| monthlyAwardAmount<br />And<br />awardEffectiveDate | monthlyAward |\n| hasIndividualUnemployabilityGranted | unemployable |\n| hasSpecialMonthlyCompensation | specialMonthlyCompensation |\n| hasAdaptedHousing | adaptedHousing |\n| hasChapter35Eligibility | chapter35Eligibility |\n| hasDeathResultOfDisability | deathResultOfDisability |\n| hasSurvivorsPensionAward | survivorsAward |\n","operationId":"GET:/letter-contents/{letterType}","parameters":[{"name":"letterType","in":"path","description":"Letter Type","required":true,"schema":{"maxLength":64,"type":"string","description":"Possible values: BENEFIT_SUMMARY, BENEFIT_SUMMARY_DEPENDENT, BENEFIT_VERIFICATION, CIVIL_SERVICE, COMMISSARY, COMMISSARY_SHORT_TERM, PROOF_OF_SERVICE, SERVICE_VERIFICATION, MEDICARE_PARTD, MINIMUM_ESSENTIAL_COVERAGE","example":"BENEFIT_SUMMARY"}},{"name":"icn","in":"query","description":"MPI ICN","required":true,"schema":{"maxLength":17,"minLength":17,"pattern":"^\\d{10}V\\d{6}$","type":"string","example":"1000000000V100000"}},{"name":"militaryService","in":"query","description":"Include military service","schema":{"type":"boolean","example":false,"default":true}},{"name":"serviceConnectedDisabilities","in":"query","description":"Include service connected disabilities","schema":{"type":"boolean","example":false,"default":true}},{"name":"serviceConnectedEvaluation","in":"query","description":"Include service connected evaluation","schema":{"type":"boolean","example":false,"default":true}},{"name":"nonServiceConnectedPension","in":"query","description":"Include non-service connected pension","schema":{"type":"boolean","example":false,"default":true}},{"name":"monthlyAward","in":"query","description":"Include monthly award","schema":{"type":"boolean","example":false,"default":true}},{"name":"unemployable","in":"query","description":"Include unemployable data","schema":{"type":"boolean","example":false,"default":true}},{"name":"specialMonthlyCompensation","in":"query","description":"Include special monthly compensation","schema":{"type":"boolean","example":false,"default":true}},{"name":"adaptedHousing","in":"query","description":"Include adapted housing","schema":{"type":"boolean","example":false,"default":true}},{"name":"chapter35Eligibility","in":"query","description":"Include chapter 35 eligibility","schema":{"type":"boolean","example":false,"default":true}},{"name":"deathResultOfDisability","in":"query","description":"Include death result of disability","schema":{"type":"boolean","example":false,"default":true}},{"name":"survivorsAward","in":"query","description":"Include survivors pension award","schema":{"type":"boolean","example":false,"default":true}}],"responses":{"201":{"description":"Json representation of a letter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LetterContentsResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"type":"string","example":{"message":"Invalid authentication credentials"}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"string","example":{"message":"You cannot consume this service"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserNotFound"}}}},"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":{"$ref":"#/components/schemas/UnprocessableEntity"}}}},"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/InternalServerError"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}},"security":[{"OAuth":[]}]}},"/letters/{letterType}/letter":{"get":{"tags":["Letters"],"summary":"Generates PDF letters by letter type.","description":"Returns the letters a Veteran or dependent is eligible for, with watermarks and logo, in PDF format.\n| If the GET /eligible-letters endpoint returns | Generate the letter with these query parameters |\n| --- | --- |\n| hasServiceConnectedDisabilities | serviceConnectedDisabilities |\n| serviceConnectedPercentage | serviceConnectedEvaluation |\n| hasNonServiceConnectedPension | nonServiceConnectedPension |\n| monthlyAwardAmount<br />And<br />awardEffectiveDate | monthlyAward |\n| hasIndividualUnemployabilityGranted | unemployable |\n| hasSpecialMonthlyCompensation | specialMonthlyCompensation |\n| hasAdaptedHousing | adaptedHousing |\n| hasChapter35Eligibility | chapter35Eligibility |\n| hasDeathResultOfDisability | deathResultOfDisability |\n| hasSurvivorsPensionAward | survivorsAward |\n","operationId":"GET:/letters/{letterType}/letter","parameters":[{"name":"letterType","in":"path","description":"Letter Type","required":true,"schema":{"maxLength":64,"type":"string","description":"Possible values: BENEFIT_SUMMARY, BENEFIT_SUMMARY_DEPENDENT, BENEFIT_VERIFICATION, CIVIL_SERVICE, COMMISSARY, COMMISSARY_SHORT_TERM, PROOF_OF_SERVICE, SERVICE_VERIFICATION, MEDICARE_PARTD, MINIMUM_ESSENTIAL_COVERAGE","example":"BENEFIT_SUMMARY"}},{"name":"icn","in":"query","description":"MPI ICN","required":true,"schema":{"maxLength":17,"minLength":17,"pattern":"^\\d{10}V\\d{6}$","type":"string","example":"1000000000V100000"}},{"name":"militaryService","in":"query","description":"Include military service","schema":{"type":"boolean","example":false,"default":true}},{"name":"serviceConnectedDisabilities","in":"query","description":"Include service connected disabilities","schema":{"type":"boolean","example":false,"default":true}},{"name":"serviceConnectedEvaluation","in":"query","description":"Include service connected evaluation","schema":{"type":"boolean","example":false,"default":true}},{"name":"nonServiceConnectedPension","in":"query","description":"Include non-service connected pension","schema":{"type":"boolean","example":false,"default":true}},{"name":"monthlyAward","in":"query","description":"Include monthly award","schema":{"type":"boolean","example":false,"default":true}},{"name":"unemployable","in":"query","description":"Include unemployable data","schema":{"type":"boolean","example":false,"default":true}},{"name":"specialMonthlyCompensation","in":"query","description":"Include special monthly compensation","schema":{"type":"boolean","example":false,"default":true}},{"name":"adaptedHousing","in":"query","description":"Include adapted housing","schema":{"type":"boolean","example":false,"default":true}},{"name":"chapter35Eligibility","in":"query","description":"Include chapter 35 eligibility","schema":{"type":"boolean","example":false,"default":true}},{"name":"deathResultOfDisability","in":"query","description":"Include death result of disability","schema":{"type":"boolean","example":false,"default":true}},{"name":"survivorsAward","in":"query","description":"Include survivors pension award","schema":{"type":"boolean","example":false,"default":true}}],"responses":{"201":{"description":"Actual PDF File, application/pdf","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest"}}}},"401":{"description":"Not authorized","content":{"application/json":{"schema":{"type":"string","example":{"message":"Invalid authentication credentials"}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"string","example":{"message":"You cannot consume this service"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserNotFound"}}}},"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":{"$ref":"#/components/schemas/UnprocessableEntity"}}}},"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/InternalServerError"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}},"security":[{"OAuth":[]}]}}},"components":{"schemas":{"BadRequest":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type.","example":"https://example.net/validation-error"},"title":{"type":"string","description":"A short, human-readable summary of the problem type.","example":"Invalid field value"},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem.","format":"int32","example":400},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem.","example":"This error occurred because of..."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.","example":"e6d1119e-dc91-4b4d-b583-0f309de0807b"}},"example":{"type":"https://api.va.gov/services/letters/v1/api-schema/errors/constraint-violation","title":"Invalid field value","status":400,"detail":"Data in request is malformed"}},"BenefitInformation":{"type":"object","properties":{"serviceConnectedPercentage":{"type":"integer","format":"int32","example":2},"awardEffectiveDateTime":{"type":"string","format":"date-time","example":"2016-02-04T17:51:56Z"},"monthlyAwardAmount":{"$ref":"#/components/schemas/MonetaryAmount"},"serviceConnectedDisabilities":{"type":"boolean","example":true},"nonServiceConnectedPension":{"type":"boolean","example":false},"individualUnemployabilityGranted":{"type":"boolean","example":false},"chapter35Eligibility":{"type":"boolean","example":true},"specialMonthlyCompensation":{"type":"boolean","example":false},"adaptedHousing":{"type":"boolean","example":false},"chapter35EligibilityDateTime":{"type":"string","format":"date-time","example":"2016-02-04T17:51:56Z"},"hasDeathResultOfDisability":{"type":"boolean","example":false},"hasSurvivorsIndemnityCompensationAward":{"type":"boolean","example":false},"hasSurvivorsPensionAward":{"type":"boolean","example":false}}},"InternalServerError":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type.","example":"https://example.net/validation-error"},"title":{"type":"string","description":"A short, human-readable summary of the problem type.","example":"Invalid field value"},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem.","format":"int32","example":400},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem.","example":"This error occurred because of..."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.","example":"e6d1119e-dc91-4b4d-b583-0f309de0807b"}},"example":{"type":"https://api.va.gov/services/letters/errors/generic/internal-server-error","title":"Internal Server Error","status":500,"detail":"Internal Server Error","instance":"e6d1119e-dc91-4b4d-b583-0f309de0807b"}},"Letter":{"type":"object","properties":{"letterName":{"type":"string","example":"Benefit Summary Dependent"},"letterType":{"type":"string","description":"Possible values: BENEFIT_SUMMARY, BENEFIT_SUMMARY_DEPENDENT, BENEFIT_VERIFICATION, CIVIL_SERVICE, COMMISSARY, COMMISSARY_SHORT_TERM, PROOF_OF_SERVICE, SERVICE_VERIFICATION, MEDICARE_PARTD, MINIMUM_ESSENTIAL_COVERAGE","example":"BENEFIT_SUMMARY_DEPENDENT"}}},"LetterContent":{"type":"object","properties":{"contentKey":{"type":"string","example":"gross-benefit"},"contentTitle":{"type":"string","example":"Gross Benefit Amount"},"content":{"type":"string","example":"$1,288.03"}}},"LetterContentsResponse":{"type":"object","properties":{"letterDescription":{"type":"string","example":"This letter shows the benefits you're receiving from VA. The letter also shows your benefit gross amount (the amount before anything is taken out) and net amount (the amount after deductions are taken out), your benefit effective date, and your disability rating."},"letterContent":{"type":"array","items":{"$ref":"#/components/schemas/LetterContent"}}}},"LetterDestination":{"required":["addressLine1"],"type":"object","properties":{"country":{"type":"string","example":"USA"},"addressLine1":{"type":"string","example":"2476 MAIN STREET"},"addressLine2":{"type":"string","example":"STE # 12"},"addressLine3":{"type":"string","example":"West"},"city":{"type":"string","example":"RESTON"},"state":{"type":"string","example":"VA"},"zipCode":{"type":"string","example":"12345"},"fullName":{"type":"string","example":"John A Smith"}}},"LettersResponse":{"required":["benefitInformation","letterDestination","letters","messages","militaryServices"],"type":"object","properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"letters":{"type":"array","items":{"$ref":"#/components/schemas/Letter"}},"letterDestination":{"$ref":"#/components/schemas/LetterDestination"},"militaryServices":{"type":"array","items":{"$ref":"#/components/schemas/MilitaryService"}},"benefitInformation":{"$ref":"#/components/schemas/BenefitInformation"}}},"Message":{"type":"object","properties":{"key":{"type":"string","example":"letterGeneration.letterEligibilityError"},"text":{"type":"string","example":"string"},"severity":{"type":"string","example":"WARN","enum":["FATAL","ERROR","WARN","INFO"]}}},"MilitaryService":{"type":"object","properties":{"branch":{"type":"string","example":"Army"},"characterOfService":{"maxLength":28,"type":"string","example":"HONORABLE","enum":["HONORABLE","OTHER_THAN_HONORABLE","UNDER_HONORABLE_CONDITIONS","GENERAL","UNCHARACTERIZED","UNCHARACTERIZED_ENTRY_LEVEL","DISHONORABLE"]},"releasedDateTime":{"type":"string","format":"date-time","example":"2016-02-04T17:51:56Z"},"enteredDateTime":{"type":"string","format":"date-time","example":"2016-02-04T17:51:56Z"}}},"MonetaryAmount":{"type":"object","properties":{"value":{"type":"number","format":"double","example":2673},"currency":{"type":"string","example":"USD"}}},"NotAcceptable":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type.","example":"https://example.net/validation-error"},"title":{"type":"string","description":"A short, human-readable summary of the problem type.","example":"Invalid field value"},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem.","format":"int32","example":400},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem.","example":"This error occurred because of..."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.","example":"e6d1119e-dc91-4b4d-b583-0f309de0807b"}},"example":{"type":"https://api.va.gov/services/letters/v1/api-schema/errors/not-acceptable","title":"Media type not acceptable","status":406,"detail":"Could not find acceptable representation","instance":"e6d1119e-dc91-4b4d-b583-0f309de0807b"}},"UnprocessableEntity":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type.","example":"https://example.net/validation-error"},"title":{"type":"string","description":"A short, human-readable summary of the problem type.","example":"Invalid field value"},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem.","format":"int32","example":400},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem.","example":"This error occurred because of..."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.","example":"e6d1119e-dc91-4b4d-b583-0f309de0807b"},"debuggingPayload":{"type":"string","description":"Encrypted message to assist with debugging that occur while generating letters.","example":"VkEgUHJvZmlsZSBDb250YWN0IEluZm9ybWF0aW9uIF..."}},"example":{"type":"https://api.va.gov/services/va-letter-generator/errors/va-profile/address-exception","title":"Va Profile address invalid","status":422,"detail":"No zipCode5 provided for domestic address","instance":"e6d1119e-dc91-4b4d-b583-0f309de0807b"}},"UserNotFound":{"type":"object","properties":{"type":{"type":"string","description":"A URI reference that identifies the problem type.","example":"https://example.net/validation-error"},"title":{"type":"string","description":"A short, human-readable summary of the problem type.","example":"Invalid field value"},"status":{"type":"integer","description":"The HTTP status code generated by the origin server for this occurrence of the problem.","format":"int32","example":400},"detail":{"type":"string","description":"A human-readable explanation specific to this occurrence of the problem.","example":"This error occurred because of..."},"instance":{"type":"string","description":"A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.","example":"e6d1119e-dc91-4b4d-b583-0f309de0807b"}},"example":{"type":"https://api.va.gov/services/va-letter-generator/errors/generic/not-found","title":"Person for ICN not found","status":404,"detail":"No data found for ICN","instance":"e6d1119e-dc91-4b4d-b583-0f309de0807b"}}},"securitySchemes":{"OAuth":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.va.gov/oauth2/veteran-letters/system/v1/token","scopes":{"letters.read":"The veteran's access to letters that provide verification of eligibility for their benefits."}}}}}}}