{"openapi":"3.0.1","info":{"title":"Veteran Confirmation","description":"The Veteran Confirmation API returns whether a given person is `\"confirmed\"` or\n`\"not confirmed\"` as a [Title 38 Veteran](https://www.ecfr.gov/current/title-38).\nConfirming a Veteran's status can be useful for determining eligibility for\ndiscounts, services, preferential treatment, and certain jobs or education\nprograms.\n\nA Veteran is a person who served in the active military, naval, air, or space\nservice, and who was discharged or released under conditions other than\ndishonorable. Active duty service history in the Reserves and National Guard is\nconsidered active military service. Basic eligibility for VA benefits depends on\nthe type of military service performed, the duration of the service, and the\ncharacter of discharge or separation.\n\nA result of \"not confirmed\" does not necessarily mean that a person is\nnot a Veteran. A person may have served without being entitled to the VA\nbenefits of a Title 38 Veteran, or more research may be required to determine\ntheir status. If so, this API will return a status of \"not confirmed.\" Reasons\nfor this can include dishonorable character of service, insufficient length of\nactive duty service, dates of service, or disability details. For more\ninformation about interpreting a status of \"not confirmed\" and suggested\nfollow-up actions, see the not confirmed reasons section of this page.\n\n**Important:**\nThis API does not provide details about a person's service experience or\ninsight into why a person is `\"not confirmed\"` as a Title 38 Veteran. The\n[Veteran Service History and Eligibility API](https://developer.va.gov/explore/verification/docs/veteran_verification?version=current)\nhas different authentication methods and can provide additional information\nabout Veterans. Veterans can obtain additional information about their service\nhistory on [VA.gov](https://www.va.gov/).\n\n## Technical Overview\n\n### Not confirmed reasons\nIf the API returns a veteran_status of \"not confirmed\", it will also return\n one of the following ```not_confirmed_reason``` values:\n\n- ```PERSON_NOT_FOUND``` : The person was not found in VA source systems with\nthe provided information.\n    - **Suggested action**: Re-check information and try query again. Including\n    more demographic data for a Veteran increases the likelihood of finding\n    their records in VA source systems.\n- ```NOT_TITLE_38```: VA data sources indicate that the person does not have\nTitle 38 status.\n    - **Suggested action**: The person should contact VA if they believe they\n     should have Title 38 status.\n- ```MORE_RESEARCH_REQUIRED```: VA cannot confirm the person's Title 38 status\n with existing records.\n    - **Suggested action**: The Veteran should request a manual review from VA\n     if they believe that they should have Title 38 status.\n- ```ERROR```: One or more VA source systems is not available or returned\n an error response.\n    - **Suggested action**:  Run the request again.\n\n### Authentication and authorization\nThis API requires an API key together with identifiable information for\nthe person being confirmed. API requests are authorized with an API key\nprovided in an HTTP header named apikey.\n\n### Test data\nWe use mock test data in the sandbox environment. APIs accessed via the\nSandbox environment are using the same underlying logic as VA's production\nAPIs; only the underlying data store is different.\n\nUse these [test user attributes](https://developer.va.gov/explore/api/veteran-confirmation/test-users)\nin sandbox to populate the request body as only test users can return a\n`\"confirmed\"` response. In sandbox, only a test user's date of birth and\nzip code are used to identify a Veteran.\n\n","contact":{"name":"developer.va.gov"},"version":"0.0.2"},"servers":[{"url":"https://sandbox-api.va.gov/services/veteran-confirmation/{version}","description":"Sandbox","variables":{"version":{"default":"v1"}}},{"url":"https://api.va.gov/services/veteran-confirmation/{version}","description":"Production","variables":{"version":{"default":"v1"}}}],"tags":[{"name":"veteran_confirmation_status","description":"Veteran Confirmation - Veteran Status"}],"paths":{"/status":{"post":{"tags":["veteran_confirmation_status"],"summary":"Confirms an individual's Title 38 Veteran status.","description":"Confirm an individual's Title 38 Veteran status according to VA.\nThis endpoint accepts demographic information for the person to\nbe confirmed and matches it against VA records. If there are\ndifferences between the data entered and the data on file, a\nmatch to a person may not be found. If a successful match is\nidentified, Title 38 Veteran status is checked.\n\n- ```\"confirmed\"``` indicates Title 38 Veteran status.\n- ```\"not confirmed\"``` can mean several different things, depending on\nthe following not_confirmed_reason values:\n- ```PERSON_NOT_FOUND```: The person was not found in VA source systems\nwith the provided information. Including more demographic data\nfor a Veteran increases the likelihood of finding their records\nin VA source systems.\n- ```NOT_TITLE_38```: VA data sources indicate that the person does not\nhave Title 38 status.\n- ```MORE_RESEARCH_REQUIRED```: VA cannot confirm the person's Title 38\nstatus with existing records.\n- ```ERROR```: One or more VA source systems is not available or returned\nan error response.\n- If ```\"not confirmed\"``` is returned, it can help to try again with\ndifferent addresses or names or optional fields.\nIf needed, Veterans may update their profile with the VA on VA.gov.\n- The updated information will be available to this API immediately.\nAdditional field-level guidance is provided in the schema section\nof this documentation.\n","operationId":"POST:/status","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VeteranStatusRequest"},"example":{"firstName":"Alfredo","lastName":"Armstrong","birthDate":"1993-06-08","middleName":"M","gender":"M","streetAddressLine1":"17020 Tortoise St","city":"Round Rock","zipCode":"78664","state":"TX","country":"USA","homePhoneNumber":"555-555-5555","mothersMaidenName":"Smith","birthPlaceCity":"Johnson City","birthPlaceState":"MA","birthPlaceCountry":"USA"}}},"required":true},"responses":{"200":{"description":"Confirmation status successfully retrieved.\n\nPossible return values if Veteran is \"NOT CONFIRMED\":\n - ERROR\n - MORE_RESEARCH_REQUIRED\n - NOT_TITLE_38\n - PERSON_NOT_FOUND","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VeteranStatusConfirmation"},"example":{"id":"(REDACTED)","veteran_status":"confirmed","not_confirmed_reason":"null"}}}},"400":{"description":"Bad request - invalid or missing query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"},"example":{"errors":[{"title":"Missing parameter","detail":"The required parameter 'firstName', is missing","code":"108","status":"400"}]}}}},"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"}}}}},"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/APIError"},"example":{"errors":[{"title":"Internal server error","detail":"Internal server error","code":"500","status":"500"}]}}}},"502":{"description":"Bad Gateway - Call to upstream service failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/APIError"},"example":{"errors":[{"title":"Bad Gateway","detail":"Call to upstream service failed","code":"502","status":"502"}]}}}},"503":{"description":"We encountered a temporary error. Check back in the future.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizationError"},"example":{"errors":[{"title":"Service unavailable","detail":"An external service is unavailable.","code":"503","status":"503"}]}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}},"security":[{"apiKey":[]}]}}},"components":{"schemas":{"VeteranStatusRequest":{"required":["birthDate","city","country","firstName","lastName","state","streetAddressLine1","zipCode"],"type":"object","properties":{"gender":{"type":"string","description":"For gender, only 'm' or 'f' will help the search currently."},"firstName":{"type":"string"},"middleName":{"type":"string"},"lastName":{"type":"string","description":"Valid entries for the name fields include:\n- First character must be an alpha/letter character (upper or lowercase).\n- Upper and/or lower case letters\n- Spaces\n- Special characters:  forward slash /,  back slash \\\\,  hyphen -,  single quote\n(apostrophe) '\n- Consecutive special characters are not supported.\n- More than one name in a field. For example:\n      First name:   Margaret Mary\n- Names in the field can be separated by a space or a valid special character (forward\nslash /,  back slash \\\\,  hyphen -,  single quote (apostrophe) ').\n- Diacritical characters (i.e.,  ä: umlaught; é: accent) are not currently supported\nand will generate an error.\n- Numerical characters are not supported\n\nNote: If a veteran is not found, and the veteran name has special characters or even\nmultiple names, the veteran might be found in subsequent requests to veteran confirmation\nwith some changes to the names. For example, a submission of 'O'leary' can be can be\nchanged to 'oleary' and that could result in a match. Another example: Veteran's\nlast name is 'Smith-Jones', and a request with that exact last name doesn't\nresult in the veteran being found. You can try making another request but with\nthe following variations for the last\nname field:  'SmithJones', 'Smith Jones',  'Jones', 'Smith'.\n\nNote: Capitalization does not have an effect on whether or not a person is found. It\ndoesn't matter if someone sends \"John\" vs \"john\" for example.\n"},"zipCode":{"type":"string","description":"zip code can accept one to sixteen uppercase or lowercase letters, digits,\nspaces, or hyphens -.\n"},"city":{"type":"string","description":"City can accept one or more uppercase or lowercase letters, digits, spaces,\ncommas, apostrophes ', periods, back slashes \\\\, forward slashes /, or hyphens - .\n"},"state":{"type":"string","description":"State field can accept a string that starts with one or more uppercase or lowercase letters, followed by zero or more occurrences of a space or hyphen and one or more uppercase or lowercase letters."},"country":{"type":"string","description":"Country field can accept a string that starts with one or more uppercase or lowercase letters, followed by zero or more occurrences of a space or hyphen and one or more uppercase or lowercase letters."},"birthDate":{"type":"string","description":"Birth date can accept dates in YYYY-MM-DD format.","format":"date"},"streetAddressLine1":{"type":"string","description":"Address line 1 can accept one or more letters (uppercase or\nlowercase), digits, spaces, commas, hashes(#), apostrophes('),\nperiods(.), back slashes(\\\\), forward slashes(/), or hyphens(-).\n"},"streetAddressLine2":{"type":"string","description":"Address line 2 can accept one or more letters (uppercase or\nlowercase), digits, spaces, commas, hashes(#), apostrophes('),\nperiods(.), back slashes(\\\\), forward slashes(/), or hyphens(-).\n"},"streetAddressLine3":{"type":"string","description":"Address line 3 can accept one or more letters (uppercase or\nlowercase), digits, spaces, commas, hashes(#), apostrophes('),\nperiods(.), back slashes(\\\\), forward slashes(/), or hyphens(-).\n"},"homePhoneNumber":{"type":"string"},"mothersMaidenName":{"type":"string"},"birthPlaceCity":{"type":"string","description":"Birth place city can accept one or more uppercase or lowercase letters, digits,\nspaces, commas, apostrophes ', periods, back slashes \\\\,\nforward slashes /, or hyphens - .\n"},"birthPlaceState":{"type":"string","description":"Birth place state can accept, One or more uppercase or lowercase letters, digits, spaces, commas, apostrophes ', or hyphens -."},"birthPlaceCountry":{"type":"string","description":"Birth place country can accept, one or more uppercase or lowercase letters, digits, spaces, commas, apostrophes ', or hyphens -."}},"description":"- Use current residence address of the Veteran. Some unhoused Veterans can use a local USPS,\nsupport organization, or other location such as 'the corner of RTE512 and U.S.1'.\n- Aim to match the input against the Veteran's demographic information in their VA.gov profile.\n- Data in the request and the VA record is standardized using the same algorithm prior to\nmatching. If the data is close, and enough fields are provided, it will find the Veteran\nmost of the time.\n- If data submitted is not in sync with the Veteran's VA profile, it may be helpful to re-try\nthe request with a different address or name. The Veteran may need to update their\ninformation with the VA if they are not found or if their current data is not in sync.\n"},"VeteranStatusConfirmation":{"type":"object","properties":{"id":{"type":"string","description":"Non-identifying text string","example":"(REDACTED)","deprecated":true},"veteran_status":{"type":"string","description":"Whether the system could confirm the Veteran status of an individual based on traits\n","enum":["confirmed","not confirmed"]},"not_confirmed_reason":{"type":"string","description":"Defines reason for a not confirmed status response.\n  Possible values:\n   - ERROR\n   - MORE_RESEARCH_REQUIRED\n   - NOT_TITLE_38\n - PERSON_NOT_FOUND\n"}},"description":"Veteran status confirmation for an individual"},"APIError":{"type":"object","properties":{"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiErrorDetails"}}},"description":"API invocation or processing error"},"ApiErrorDetails":{"type":"object","properties":{"title":{"type":"string","example":"Error title"},"detail":{"type":"string","example":"Detailed error message"},"code":{"type":"string","example":"103"},"status":{"type":"string","example":"400"}}},"AuthorizationError":{"type":"object","properties":{"message":{"type":"string","example":"No API key found in request"}},"description":"API Platform authorization (API token) error"}},"securitySchemes":{"apiKey":{"type":"apiKey","name":"apiKey","in":"header"}}}}