### Handle API Errors - JSON Examples Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi These JSON examples illustrate common error responses from the API, including resource not found (404), payload too large (413), too many requests (429), and gateway timeout (504). Each error includes a status code, title, and a detailed description. ```json { "errors": [ { "status": "404", "title": "Resource not found", "detail": "Could not find Power of Attorney Request with id: 12e13134-7229-4e44-90ae-bcea2a4525fa" } ] } ``` ```json { "message": "Request size limit exceeded" } ``` ```json { "message": "API rate limit exceeded" } ``` ```json { "message": "The server took too long to respond" } ``` -------------------------------- ### Claim Submission Schema - Example JSON Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi An example JSON structure for submitting a benefits claim. It outlines required fields like claimant details, service information, and claim specifics. This schema is crucial for ensuring data integrity and successful claim processing. ```json { "data": { "type": "claim", "attributes": { "claimantCertification": true, "claimNotes": "Additional notes about the claim.", "separationSeverancePay": { "datePaymentReceived": "2023-10-26", "branchOfService": "Army", "preTaxAmountReceived": 1000 }, "directDeposit": { "accountNumber": "1234567890", "accountType": "CHECKING", "financialInstitutionName": "Example Bank", "routingNumber": "012345678" } } } } ``` -------------------------------- ### Retrieve Intent to File - GET Request Example Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi This example demonstrates how to make a GET request to retrieve a claimant's last active Intent to File submission for a specific benefit type. It requires the veteran's ID and the benefit type (compensation, pension, or survivor) as path parameters. The response includes details about the Intent to File, such as its creation and expiration dates, and its status. ```http GET https://api.va.gov/internal/v2/veterans/1012667145V762142/intent-to-file/compensation Authorization: Bearer ``` -------------------------------- ### Claims API 5103 Schema Example Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi An example schema for the Claims API, specifically for tracking item IDs. This JSON structure defines the expected format for data related to tracked items. ```json { "data": { "type": "form/5103", "attributes": { "trackedItemIds": [ 1234 ] } } } ``` -------------------------------- ### VA Form 21-22 Response Example - Not Found Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi An example of a 'Resource not found' error response when attempting to process VA Form 21-22. This error typically occurs if the specified representative or POA code does not exist in the system. ```json { "errors": [ { "status": "404", "title": "Resource not found", "detail": "Could not find an Accredited Representative with registration number: 999999999999 and poa code: 083" } ] } ``` -------------------------------- ### Example Claim Submission Payload Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi An example JSON payload for submitting a claim using the Benefits Claims v2 API. It includes various sections like veteran identification, change of address, toxic exposure details, disabilities, treatments, service information, and direct deposit. ```json { "data": { "type": "form/526", "attributes": { "claimProcessType": "STANDARD_CLAIM_PROCESS", "claimNotes": "Some things that are important to know, and are not included in any other place.", "veteranIdentification": { "serviceNumber": "123456789", "veteranNumber": { "telephone": "5555555555" }, "mailingAddress": { "addressLine1": "123 Main Street", "addressLine2": "Unit 1", "addressLine3": "Room 2", "city": "Schenectady", "state": "NY", "country": "USA", "zipFirstFive": "12345", "zipLastFour": "1234" }, "emailAddress": { "email": "valid@somedomain.com", "agreeToEmailRelatedToClaim": true }, "currentVaEmployee": false }, "changeOfAddress": { "typeOfAddressChange": "TEMPORARY", "addressLine1": "456 Main Street", "addressLine2": "Unit 3", "addressLine3": "Room 4", "city": "Schenectady", "state": "NY", "country": "USA", "zipFirstFive": "12345", "zipLastFour": "9897", "dates": { "beginDate": "2025-06-04", "endDate": "2026-06-04" } }, "homeless": { "currentlyHomeless": { "homelessSituationOptions": "OTHER", "otherDescription": "Other living situation" }, "pointOfContact": "John Doe", "pointOfContactNumber": { "telephone": "5555555555" } }, "toxicExposure": { "gulfWarHazardService": { "servedInGulfWarHazardLocations": "NO" }, "herbicideHazardService": { "servedInHerbicideHazardLocations": "YES", "otherLocationsServed": "Other locations served", "serviceDates": { "beginDate": "1972-05", "endDate": "1980-10" } }, "additionalHazardExposures": { "additionalExposures": [ "OTHER" ], "specifyOtherExposures": "Agent Orange", "exposureDates": { "beginDate": "1972-05", "endDate": "1980-10" } }, "multipleExposures": [ { "hazardExposedTo": "Agent Orange", "exposureLocation": "Vietnam", "exposureDates": { "beginDate": "1972-05", "endDate": "1973-01" } }, { "hazardExposedTo": "Agent Orange", "exposureLocation": "Vietnam", "exposureDates": { "beginDate": "1979-04", "endDate": "1980-10" } } ] }, "disabilities": [ { "name": "Diabetes", "exposureOrEventOrInjury": "Agent Orange", "serviceRelevance": "Service in Vietnam War", "approximateDate": "1975-05", "disabilityActionType": "NEW", "isRelatedToToxicExposure": true }, { "name": "Hearing Loss", "exposureOrEventOrInjury": "Noise", "serviceRelevance": "Heavy equipment operator in service", "approximateDate": "1968-07", "disabilityActionType": "INCREASE", "classificationCode": "8987", "ratedDisabilityId": "1234567", "diagnosticCode": 5678, "isRelatedToToxicExposure": false } ], "treatments": [ { "beginDate": "2021-04", "treatedDisabilityNames": [ "Diabetes" ], "center": { "name": "ATLANTA VA MEDICAL CENTER", "state": "GA", "city": "ATLANTA" } }, { "beginDate": "1996-03", "treatedDisabilityNames": [ "Hearing Loss" ], "center": { "name": "ATLANTA VA MEDICAL CENTER", "state": "GA", "city": "ATLANTA" } } ], "serviceInformation": { "alternateNames": [ "Jon Doe", "Jane Doe" ], "servicePeriods": [ { "serviceBranch": "Air Force", "serviceComponent": "Active", "activeDutyBeginDate": "1964-11-14", "activeDutyEndDate": "1980-10-30", "separationLocationCode": "98289" } ], "servedInActiveCombatSince911": "NO", "reservesNationalGuardService": { "component": "National Guard", "obligationTermsOfService": { "beginDate": "1990-11-24", "endDate": "1995-11-17" }, "unitName": "National Guard Unit Name", "unitAddress": "1243 Main Street", "unitPhone": { "areaCode": "555", "phoneNumber": "5555555" }, "receivingInactiveDutyTrainingPay": "YES" }, "confinements": [ { "approximateBeginDate": "1970-06-11", "approximateEndDate": "1970-09-11" } ] }, "servicePay": { "receivingMilitaryRetiredPay": "NO", "futureMilitaryRetiredPay": "YES", "futureMilitaryRetiredPayExplanation": "Explanation of future military retired pay", "militaryRetiredPay": { "branchOfService": "Air Force", "monthlyAmount": 240 }, "retiredStatus": "PERMANENT_DISABILITY_RETIRED_LIST", "favorMilitaryRetiredPay": false, "receivedSeparationOrSeverancePay": "YES", "separationSeverancePay": { "datePaymentReceived": "2018-07-31", "branchOfService": "Air Force", "preTaxAmountReceived": 179 }, "favorTrainingPay": false }, "directDeposit": { "accountNumber": "123123123123", "accountType": "CHECKING", "financialInstitutionName": "Chase", "routingNumber": "123456789" }, "claimantCertification": true } } } ``` -------------------------------- ### Resource Not Found Error Response - JSON Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi Example JSON response for a 404 Not Found error, indicating that the requested resource could not be located. ```json { "errors": [ { "status": "404", "title": "Resource not found", "detail": "Could not find Power of Attorney with id: -1" } ] } ``` -------------------------------- ### Power of Attorney Request Decision Schema and Example Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi Defines the schema for a Power of Attorney Request Decision, specifying required attributes like decision and representativeId. Includes an example of an 'ACCEPTED' decision. ```json { "$schema": "http://json-schema.org/draft-07/schema#", "description": "Power Of Attorney Request Decision", "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "additionalProperties": false, "required": [ "attributes" ], "properties": { "attributes": { "type": "object", "additionalProperties": false, "required": [ "decision", "representativeId" ], "properties": { "decision": { "type": "string", "description": "The decision of the request.", "enum": [ "ACCEPTED", "DECLINED" ] }, "declinedReason": { "type": "string", "description": "The reason for declining the request.", "nullable": true }, "representativeId": { "type": "string", "description": "The unique identifier of the requestʼs representative." } } } } } ], "example": { "data": { "attributes": { "decision": "ACCEPTED", "representativeId": "12345678", "declinedReason": null } } } } ``` -------------------------------- ### Example Resource Not Found Error Response (API) Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi This JSON shows a 'Resource not found' error, indicating that a requested resource, such as a Veteran ID, could not be located by the API. ```json { "errors": [ { "title": "Resource not found", "detail": "Veteran ID not found" } ] } ``` -------------------------------- ### Example Valid Intent to File Response (API) Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi This JSON structure represents a successful validation of an Intent to File for a veteran's claim. It confirms that the submitted data is 'valid'. ```json { "data": { "type": "intent_to_file_validation", "attributes": { "status": "valid" } } } ``` -------------------------------- ### API Error Response - Resource Not Found (404) Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi Example of a 404 Not Found error response, typically returned when a specific resource, such as a Power of Attorney request, cannot be located by its ID. ```json { "errors": [ { "status": "404", "title": "Resource not found", "detail": "Could not find Power of Attorney request with id: 348fa995-5b29-4819-91af-13f1bb3c7d77" } ], "schema_validation_error": { "summary": "Schema validation error", "value": { "errors": [ { "status": "404", "title": "Resource not found", "detail": "Could not find Power of Attorney request with id: 348fa995-5b29-4819-91af-13f1bb3c7d77" } ] } } } ``` -------------------------------- ### VA Form 21-22 Response Example - Success Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi Example of a successful response when submitting VA Form 21-22. It includes the unique identifier for the organization, its type, and attributes such as the POA code, name, and phone number. ```json { "data": { "id": "fa2aaf33-2b73-4c3b-9d67-2f2b1f05ac22", "type": "organization", "attributes": { "code": "083", "name": "083 - DISABLED AMERICAN VETERANS", "phoneNumber": "555-555-5555" } } } ``` -------------------------------- ### Example JSON Response for Power of Attorney Search Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi This JSON snippet demonstrates the structure of a successful response when searching for power of attorney requests. It includes details about the veteran, claimant, address, representative, and status of the request. It also outlines the schema for these objects. ```json { "data": [ { "id": null, "type": "power-of-attorney-request", "attributes": { "veteran": { "firstName": "[Vet First Name]", "middleName": null, "lastName": "[Vet Last Name]" }, "claimant": { "firstName": "[Claimant First Name]", "lastName": "[Claimant Last Name]" }, "address": { "city": "Charlottesville", "stateCode": null, "zipCode": "00123", "countryCode": "USA" }, "representative": { "poaCode": "083" }, "receivedDate": "2012-11-23T16:49:16-06:00", "actionedDate": "2024-05-25T13:45:00-05:00", "status": "New", "declinedReason": null, "consentAddressChange": true, "recordConsent": true } }, { "id": null, "type": "power-of-attorney-request", "attributes": { "veteran": { "firstName": "first", "middleName": null, "lastName": "last" }, "claimant": { "firstName": null, "lastName": null }, "address": { "city": "USAG J", "stateCode": null, "zipCode": "01234", "countryCode": "USA" }, "representative": { "poaCode": "002" }, "receivedDate": "2013-01-14T08:50:17-06:00", "actionedDate": "2013-01-14T08:50:17-06:00", "status": "New", "declinedReason": null, "consentAddressChange": true, "recordConsent": true } }, { "id": null, "type": "power-of-attorney-request", "attributes": { "veteran": { "firstName": "first", "middleName": null, "lastName": "last" }, "claimant": { "firstName": null, "lastName": null }, "address": { "city": "Bourges", "stateCode": null, "zipCode": "00123", "countryCode": "France" }, "representative": { "poaCode": "002" }, "receivedDate": "2013-01-14T08:51:25-06:00", "actionedDate": "2013-01-14T08:51:25-06:00", "status": "New", "declinedReason": null, "consentAddressChange": true, "recordConsent": true } } ], "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "type", "attributes" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "power-of-attorney-request" ] }, "attributes": { "type": "object", "required": [ "veteran", "claimant", "representative" ], "properties": { "veteran": { "type": "object", "properties": { "firstName": { "description": "First name for the veteran.", "type": "string" }, "lastName": { "description": "Last name for the veteran. ", "type": "string" }, "middleName": { "description": "Middle name for the veteran.", "type": "string" } } }, "claimant": { "type": "object", "properties": { "firstName": { "description": "First name for the dependent claimant.", "type": "string" }, "lastName": { "description": "Last name for the dependent claimant.", "type": "string" }, "middleName": { "description": "Middle name for the dependent claimant.", "type": "string" } } }, "address": { "city": { "type": "string" }, "country": { "type": "string" }, "militaryPo": { "type": "string" }, "militaryPostalCode": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" } }, "representative": { "type": "object", "properties": { "poaCode": { "type": "string" }, "vsoUserEmail": { "type": "string" }, "vsoUserFirstName": { "type": "string" }, "vsoUserLastName": { "type": "string" } } }, "receivedDate": { "description": "Date the request for representation was established.", "type": "string", "format": "date-time" }, "actionedDate": { "description": "Date the request for representation was accepted or declined by a representative.", "type": "string", "format": "date-time" }, "status": { "description": "Status of the request for representation.", "type": "string" }, "declinedReason": { "description": "Reason for declining the request for representation.", "type": "string" }, "consentAddressChange": { "description": "Authorization for Representative to Act on Claimant's Behalf to Change Claimant's Address.", "type": "boolean", "enum": [ true, false ] }, "recordConsent": { "description": "Authorization for Representative's Access to Records Protected by Section 7332, Title 38, U.S.C.", "type": "boolean", "enum": [ true, false ] } } } } } } } } } ``` -------------------------------- ### Validate Power of Attorney Request (VA Form 21-22) - POST Request Example Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi Example of a POST request to validate the establishment of an organization as a claimant's accredited representative for VA Form 21-22. This endpoint checks if the submission would be valid. ```http POST /veterans/{veteranId}/2122/validate HTTP/1.1 Host: api.va.gov Authorization: Bearer Content-Type: application/json { "data": { "attributes": { "decision": "ACCEPTED", "representativeId": "12345678", "declinedReason": null } } } ``` -------------------------------- ### POST /websites/api_va_gov_internal_benefits-claims_v2 Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi Submit a new benefits claim with comprehensive veteran and service information. ```APIDOC ## POST /websites/api_va_gov_internal_benefits-claims_v2 ### Description This endpoint allows for the submission of a new veteran benefits claim. It supports detailed information including personal identification, service history, disabilities, treatments, and specific exposure details. ### Method POST ### Endpoint /websites/api_va_gov_internal_benefits-claims_v2 ### Parameters #### Request Body - **data** (object) - Required - The main payload for the claim submission. - **type** (string) - Required - Must be 'form/526'. - **attributes** (object) - Required - Contains all claim-related attributes. - **claimProcessType** (string) - Required - Type of claim process, e.g., 'STANDARD_CLAIM_PROCESS'. - **claimNotes** (string) - Optional - Additional notes for the claim. - **veteranIdentification** (object) - Required - Information about the veteran. - **serviceNumber** (string) - Optional - Veteran's service number. - **veteranNumber** (object) - Optional - Veteran's identification numbers. - **telephone** (string) - Optional - Veteran's phone number. - **internationalTelephone** (string) - Optional - Veteran's international phone number. - **mailingAddress** (object) - Required - Veteran's mailing address. - **addressLine1** (string) - Required - First line of the address. - **addressLine2** (string) - Optional - Second line of the address. - **addressLine3** (string) - Optional - Third line of the address. - **city** (string) - Required - City of the address. - **state** (string) - Required - State of the address. - **country** (string) - Required - Country of the address. - **zipFirstFive** (string) - Required - First five digits of the ZIP code. - **zipLastFour** (string) - Optional - Last four digits of the ZIP code. - **emailAddress** (object) - Optional - Veteran's email address. - **email** (string) - Required - Email address. - **agreeToEmailRelatedToClaim** (boolean) - Required - Agreement to receive claim-related emails. - **currentVaEmployee** (boolean) - Required - Indicates if the veteran is a current VA employee. - **changeOfAddress** (object) - Optional - Details about a change of address. - **typeOfAddressChange** (string) - Required - Type of address change (e.g., 'TEMPORARY'). - **addressLine1** (string) - Required - First line of the new address. - **addressLine2** (string) - Optional - Second line of the new address. - **addressLine3** (string) - Optional - Third line of the new address. - **city** (string) - Required - City of the new address. - **state** (string) - Required - State of the new address. - **country** (string) - Required - Country of the new address. - **zipFirstFive** (string) - Required - First five digits of the new ZIP code. - **zipLastFour** (string) - Optional - Last four digits of the new ZIP code. - **dates** (object) - Required - Dates for the address change. - **beginDate** (string) - Required - Start date (YYYY-MM-DD). - **endDate** (string) - Required - End date (YYYY-MM-DD). - **homeless** (object) - Optional - Information about homelessness. - **isCurrentlyHomeless** (boolean) - Required - Indicates if currently homeless. - **currentlyHomeless** (object) - Required if `isCurrentlyHomeless` is true. - **homelessSituationOptions** (string) - Required - Description of the homeless situation. - **otherDescription** (string) - Optional - Further details if 'OTHER' is selected. - **isAtRiskOfBecomingHomeless** (boolean) - Required - Indicates if at risk of becoming homeless. - **pointOfContact** (string) - Optional - Name of a point of contact. - **pointOfContactNumber** (object) - Optional - Phone number of the point of contact. - **telephone** (string) - Optional - Phone number. - **internationalTelephone** (string) - Optional - International phone number. - **toxicExposure** (object) - Optional - Details about toxic exposures. - **gulfWarHazardService** (object) - Optional - Details about Gulf War hazard service. - **servedInGulfWarHazardLocations** (string) - Required - Indicates if served in specific locations ('YES'/'NO'). - **serviceDates** (object) - Required if `servedInGulfWarHazardLocations` is 'YES'. - **beginDate** (string) - Required - Start date (YYYY-MM). - **endDate** (string) - Required - End date (YYYY-MM). - **herbicideHazardService** (object) - Optional - Details about herbicide hazard service. - **servedInHerbicideHazardLocations** (string) - Required - Indicates if served in specific locations ('YES'/'NO'). - **otherLocationsServed** (string) - Optional - Other locations served. - **serviceDates** (object) - Required if `servedInHerbicideHazardLocations` is 'YES'. - **beginDate** (string) - Required - Start date (YYYY-MM). - **endDate** (string) - Required - End date (YYYY-MM). - **additionalHazardExposures** (object) - Optional - Details about other additional hazard exposures. - **additionalExposures** (array of strings) - Required - List of additional exposures. - **specifyOtherExposures** (string) - Optional - Details for other specified exposures. - **exposureDates** (object) - Optional - Dates of exposure. - **beginDate** (string) - Required - Start date (YYYY-MM). - **endDate** (string) - Required - End date (YYYY-MM). - **multipleExposures** (array of objects) - Optional - List of multiple specific exposures. - **hazardExposedTo** (string) - Required - Type of hazard exposed to. - **exposureLocation** (string) - Required - Location of exposure. - **exposureDates** (object) - Required - Dates of exposure. - **beginDate** (string) - Required - Start date (YYYY-MM). - **endDate** (string) - Required - End date (YYYY-MM). - **disabilities** (array of objects) - Required - List of claimed disabilities. - **name** (string) - Required - Name of the disability. - **exposureOrEventOrInjury** (string) - Optional - Type of event leading to disability. - **serviceRelevance** (string) - Optional - Relevance of the disability to service. - **approximateDate** (string) - Optional - Approximate date of onset (YYYY-MM or YYYY-MM-DD). - **disabilityActionType** (string) - Required - Action type for the disability (e.g., 'NEW'). - **classificationCode** (string) - Optional - Classification code for the disability. - **ratedDisabilityId** (string) - Optional - Identifier for a rated disability. - **diagnosticCode** (integer) - Optional - Diagnostic code for the disability. - **isRelatedToToxicExposure** (boolean) - Optional - Indicates if related to toxic exposure. - **secondaryDisabilities** (array of objects) - Optional - List of secondary disabilities. - **name** (string) - Required - Name of the secondary disability. - **exposureOrEventOrInjury** (string) - Optional - Type of event leading to secondary disability. - **serviceRelevance** (string) - Optional - Relevance of the secondary disability to service. - **disabilityActionType** (string) - Required - Action type for the secondary disability. - **approximateDate** (string) - Optional - Approximate date of onset (YYYY-MM or YYYY-MM-DD). - **classificationCode** (string) - Optional - Classification code for the secondary disability. - **treatments** (array of objects) - Optional - List of treatments received. - **beginDate** (string) - Required - Start date of treatment (YYYY-MM). - **treatedDisabilityNames** (array of strings) - Required - Names of disabilities treated. - **center** (object) - Required - Treatment center details. - **name** (string) - Required - Name of the center. - **city** (string) - Required - City of the center. - **state** (string) - Required - State of the center. - **serviceInformation** (object) - Required - Information about military service. - **alternateNames** (array of strings) - Optional - Any alternate names used during service. - **servicePeriods** (array of objects) - Required - Periods of service. - **serviceBranch** (string) - Required - Branch of service. - **serviceComponent** (string) - Required - Component of service (e.g., 'Active'). - **activeDutyBeginDate** (string) - Required - Start date of active duty (YYYY-MM-DD). - **activeDutyEndDate** (string) - Required - End date of active duty (YYYY-MM-DD). - **servedInActiveCombatSince911** (string) - Optional - Indicates if served in active combat since 9/11 ('YES'/'NO'). - **reservesNationalGuardService** (object) - Optional - Details about reserve or National Guard service. - **component** (string) - Required - Component of service. - **obligationTermsOfService** (object) - Optional - Terms of obligation. - **beginDate** (string) - Required - Start date (YYYY-MM-DD). - **endDate** (string) - Required - End date (YYYY-MM-DD). - **unitName** (string) - Optional - Name of the unit. - **unitAddress** (string) - Optional - Address of the unit. - **unitPhone** (object) - Optional - Phone number of the unit. - **areaCode** (string) - Optional - Area code. - **phoneNumber** (string) - Optional - Phone number. - **receivingInactiveDutyTrainingPay** (string) - Optional - Indicates if receiving pay ('YES'/'NO'). - **confinements** (array of objects) - Optional - Periods of confinement. - **approximateBeginDate** (string) - Required - Approximate start date (YYYY-MM-DD or YYYY-MM). - **approximateEndDate** (string) - Required - Approximate end date (YYYY-MM-DD or YYYY-MM). - **servicePay** (object) - Optional - Information about military retired pay. - **receivingMilitaryRetiredPay** (string) - Optional - Indicates if receiving retired pay ('YES'/'NO'). - **futureMilitaryRetiredPay** (string) - Optional - Indicates if expecting future retired pay ('YES'/'NO'). - **futureMilitaryRetiredPayExplanation** (string) - Optional - Explanation for future retired pay. - **militaryRetiredPay** (object) - Optional - Details of current military retired pay. - **branchOfService** (string) - Required - Branch of service. - **monthlyAmount** (number) - Required - Monthly retired pay amount. - **retiredStatus** (string) - Optional - Retired status (e.g., 'PERMANENT_DISABILITY_RETIRED_LIST'). - **favorMilitaryRe** (string) - Optional - Field related to military retirement preference. - **claimantCertification** (boolean) - Required - Certification by the claimant. ### Request Example ```json { "data": { "type": "form/526", "attributes": { "claimProcessType": "STANDARD_CLAIM_PROCESS", "veteranIdentification": { "mailingAddress": { "addressLine1": "1234 Couch Street", "city": "Portland", "state": "OR", "country": "USA", "zipFirstFive": "12345" }, "currentVaEmployee": false }, "disabilities": [ { "name": "hearing loss", "serviceRelevance": "Heavy equipment operator in service", "approximateDate": "2017-07", "disabilityActionType": "NEW" } ], "serviceInformation": { "servicePeriods": [ { "serviceBranch": "Air Force", "serviceComponent": "Active", "activeDutyBeginDate": "2015-11-14", "activeDutyEndDate": "2018-11-30" } ] }, "claimantCertification": true } } } ``` ### Response #### Success Response (200) - **data** (object) - Information about the submitted claim. - **id** (string) - Unique identifier for the claim. - **type** (string) - Type of resource, e.g., 'claims'. - **attributes** (object) - Attributes of the submitted claim. - **confirmationNumber** (string) - Confirmation number for the claim. - **submittedAt** (string) - Timestamp of submission (ISO 8601 format). #### Response Example ```json { "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "type": "claims", "attributes": { "confirmationNumber": "CF123456789", "submittedAt": "2023-10-27T10:30:00Z" } } } ``` ``` -------------------------------- ### VA Form 21-22 Response Example - Unprocessable Entity Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi This example demonstrates an 'Unprocessable Entity' response, indicating issues with the submitted data for VA Form 21-22. The errors detail missing required keys like 'poaCode' or 'registrationNumber', or undefined properties. ```json { "errors": [ { "title": "Unprocessable entity", "detail": "The property /serviceOrganization did not contain the required key poaCode", "status": "422", "source": { "pointer": "data/attributes/serviceOrganization" } }, { "title": "Unprocessable entity", "detail": "The property /serviceOrganization did not contain the required key registrationNumber", "status": "422", "source": { "pointer": "data/attributes/serviceOrganization" } }, { "title": "Unprocessable entity", "detail": "The property / did not contain the required key veteran", "status": "422", "source": { "pointer": "data/attributes/" } }, { "title": "Unprocessable entity", "detail": "The property /serviceOrganization/withoutPoaCode is not defined on the schema. Additional properties are not allowed", "status": "422", "source": { "pointer": "data/attributes/serviceOrganization/withoutPoaCode" } } ] } ``` -------------------------------- ### Service Information Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi This section details how to provide service information for a benefits claim, including service periods, alternate names, and combat service details. ```APIDOC ## Service Information ### Description This section allows for the inclusion of detailed service information for a veteran's claim. This includes service periods, any alternate names the veteran served under, and specific details about their service, such as combat experience and reserve or National Guard status. ### Endpoint `/websites/api_va_gov_internal_benefits-claims_v2` (Implicitly part of a larger claim submission flow) ### Parameters #### Request Body (within the main claim submission payload) - **alternateNames** (array[string]) - Optional - List any other names under which the Veteran served, if applicable. Max items: 100. - **servicePeriods** (array[object]) - Required - Identifies the Service dates and Branch the Veteran served in. Minimum items: 1. - **serviceBranch** (string) - Required - Branch of service during period. Example: "Air Force". Max length: 1000. - **serviceComponent** (string) - Required - Enum: ["Active", "Reserves", "National Guard"] - **activeDutyBeginDate** (string) - Required - Date started active duty. Must be in the past. Format: YYYY-MM-DD. Example: "2018-06-06" - **activeDutyEndDate** (string) - Required - Date Completed Active Duty. If in the future, 'separationLocationCode' is required. Cannot be more than 180 days in the future, unless past service is also included. Format: YYYY-MM-DD. Example: "2018-06-06" - **separationLocationCode** (string) - Optional - Location code for the facility the Veteran plans to separate from. Code must match values from the Benefits Reference Data API. Example: "98283" - **servedInActiveCombatSince911** (string) - Optional - Did Veteran serve in a combat zone since 9-11-2001? Enum: ["YES", "NO"]. Example: "YES" - **reservesNationalGuardService** (object) - Optional - Details specific to Reserves or National Guard service. - **component** (string) - Optional - Enum: ["Reserves", "National Guard"] - **obligationTermsOfService** (object) - Optional - If included, 'beginDate' and 'endDate' are required. - **beginDate** (string) - Optional - Format: YYYY-MM-DD. Example: "2018-06-06" - **endDate** (string) - Optional - Format: YYYY-MM-DD. Example: "2018-06-06" - **unitName** (string) - Optional - Max length: 1000. - **unitAddress** (string) - Optional - Max length: 1000. - **unitPhone** (object) - Optional - **areaCode** (string) - Optional - Max length: 3. Example: "555" - **phoneNumber** (string) - Optional - Max length: 20. Example: "5555555" - **receivingInactiveDutyTrainingPay** (string) - Optional - Enum: ["YES", "NO"]. Example: "YES" - **federalActivation** (object) - Optional - If present, 'reservesNationalGuardService.obligationTermsOfService.beginDate', 'reservesNationalGuardService.obligationTermsOfService.endDate', and 'reservesNationalGuardService.unitName' are required. - **activationDate** (string) - Optional - Date cannot be in the future and must be after the earliest servicePeriod.activeDutyBeginDate. Format: YYYY-MM-DD. Example: "2018-06-06" - **anticipatedSeparationDate** (string) - Optional - Date must be in the future. Format: YYYY-MM-DD. Example: "2018-06-06" - **confinements** (array[object]) - Optional - Details about periods of confinement during service. ### Response (Responses would be part of the overall claim submission confirmation or error handling) ### Request Example ```json { "servicePeriods": [ { "serviceBranch": "Air Force", "serviceComponent": "Active", "activeDutyBeginDate": "2015-01-15", "activeDutyEndDate": "2019-01-14" } ], "servedInActiveCombatSince911": "YES", "reservesNationalGuardService": { "component": "National Guard", "unitName": "123rd Maintenance Company", "obligationTermsOfService": { "beginDate": "2019-02-01", "endDate": "2025-02-01" } } } ``` ``` -------------------------------- ### Claimant Certification and Notes Source: https://api.va.gov/internal/docs/benefits-claims/v2/openapi This section covers the claimant's certification and optional notes for a benefits claim. ```APIDOC ## POST /benefits/claims/v2/certification ### Description Submit claimant certification and optional notes for a benefits claim. ### Method POST ### Endpoint /benefits/claims/v2/certification ### Parameters #### Request Body - **claimantCertification** (boolean) - Required - Claimant certifies and authorizes release of information. Defaults to false. - **claimNotes** (string) - Optional - An optional notes section for the claim. Max length: 4000. ### Request Example ```json { "claimantCertification": true, "claimNotes": "Some things that are important to know." } ``` ### Response #### Success Response (200) - **status** (string) - Indicates the success of the operation. #### Response Example ```json { "status": "SUCCESS" } ``` ```