From 1f5daadb62c61d89eb4e324b57361c22d1f98c99 Mon Sep 17 00:00:00 2001 From: Tyler Coleman Date: Wed, 30 Oct 2024 12:13:18 -0700 Subject: [PATCH] update poa docs to include dependent claimants --- .../app/swagger/claims_api/description/v1.md | 7 ++++ .../app/swagger/claims_api/description/v2.md | 8 +++++ .../app/swagger/claims_api/v1/swagger.json | 4 +-- .../swagger/claims_api/v2/dev/swagger.json | 6 ++-- .../claims_api/v2/production/swagger.json | 6 ++-- .../spec/requests/v1/forms/rswag_2122_spec.rb | 32 ++++++++++++++----- .../veterans/rswag_power_of_attorney_spec.rb | 24 ++++++++++++-- 7 files changed, 69 insertions(+), 18 deletions(-) diff --git a/modules/claims_api/app/swagger/claims_api/description/v1.md b/modules/claims_api/app/swagger/claims_api/description/v1.md index 5087e5c928d..2b8b575c8d1 100644 --- a/modules/claims_api/app/swagger/claims_api/description/v1.md +++ b/modules/claims_api/app/swagger/claims_api/description/v1.md @@ -21,6 +21,13 @@ The Benefits Claims API offers faster establishment and enhanced reporting for s Forms not supported by the Benefits Claims API are submitted using the [Benefits Intake API](https://developer.va.gov/explore/benefits/docs/benefits?version=current), which places uploaded PDFs into the Centralized Mail Portal to be manually processed. +## Appointing an accredited representative for dependents +Dependents of Veterans, such as spouses, children (biological and step), and parents (biological and foster) may be eligible for VA benefits and can request representation by an accredited representative. + +To file claims through an accredited representative, dependents must appoint their own. Once appointed, the representative will have power of attorney (POA) to assist with the dependentʼs VA claims. + +Before appointing a representative, the dependentʼs relationship to the Veteran must be established. If a new representative is being appointed, the dependentʼs relationship to the Veteran will be validated first. The representative will be appointed to the dependent, not the Veteran. + ## Technical Overview This API accepts a payload of requests and responses on a per-form basis, with the payload identifying the form and Veteran. Trackable responses provide a unique ID which is used with the appropriate GET endpoint to track a submission’s processing status. diff --git a/modules/claims_api/app/swagger/claims_api/description/v2.md b/modules/claims_api/app/swagger/claims_api/description/v2.md index 50f6fe94d65..01cacafb42d 100644 --- a/modules/claims_api/app/swagger/claims_api/description/v2.md +++ b/modules/claims_api/app/swagger/claims_api/description/v2.md @@ -12,6 +12,14 @@ The Benefits Claims API Version 2 lets internal consumers: You should use the [Benefits Claims API Version 1](https://developer.va.gov/explore/benefits/docs/claims?version=current) if you are a consumer outside of VA and do not have the necessary VA agreements to use this API. +## Appointing an accredited representative for dependents + +Dependents of Veterans, such as spouses, children (biological and step), and parents (biological and foster) may be eligible for VA benefits and can request representation by an accredited representative. + +To file claims through an accredited representative, dependents must appoint their own. Once appointed, the representative will have power of attorney (POA) to assist with the dependentʼs VA claims. + +Before appointing a representative, the dependentʼs relationship to the Veteran must be established. If a new representative is being appointed, the dependentʼs relationship to the Veteran will be validated first. The representative will be appointed to the dependent, not the Veteran. + ## Technical Overview This API accepts a payload of requests and responses with the payload identifying the claim and Veteran. Responses provide the submission’s processing status. Responses also provide a unique ID which can be used with the appropriate GET endpoint to return detailed, end-to-end claims status tracking.  diff --git a/modules/claims_api/app/swagger/claims_api/v1/swagger.json b/modules/claims_api/app/swagger/claims_api/v1/swagger.json index 39778110f32..c6150d03067 100644 --- a/modules/claims_api/app/swagger/claims_api/v1/swagger.json +++ b/modules/claims_api/app/swagger/claims_api/v1/swagger.json @@ -4,7 +4,7 @@ "title": "Benefits Claims", "version": "v1", "termsOfService": "https://developer.va.gov/terms-of-service", - "description": "This API automatically establishes and submits these VA forms.\n| Form number | Form name | Description |\n| :------------- | :----------: | -----------: |\n| [21-526EZ](https://www.va.gov/find-forms/about-form-21-526ez/) | Application for Disability Compensation and Related Compensation Benefits | Used to apply for VA disability compensation and related benefits. |\n| [21-0966](https://www.va.gov/find-forms/about-form-21-0966/) | Intent to File a Claim for Compensation and/or Pension, or Survivors Pension and/or DIC | Submits an intent to file to secure the earliest possible effective date for any retroactive payments. |\n| [21-22](https://www.va.gov/find-forms/about-form-21-22/) | Appointment of Veterans Service Organization as Claimant's Representative | Used to assign a Veterans Service Organization as a POA to help a Veteran with benefits or claims. |\n| [21-22a](https://www.va.gov/find-forms/about-form-21-22a/) | Appointment of Individual As Claimant's Representative | Used to assign an individual as a POA to help a Veteran with benefits or claims. |\n\nIt also lets Veterans or their authorized representatives:\n - Digitally submit supporting documentation for disability compensation claims\n - Retrieve information such as status for any claim, including pension and burial\n - Retrieve power of attorney (POA) status for individuals and Veterans Service Organizations (VSOs)\n - Retrieve intent to file status\n\n## Background\nThe Benefits Claims API offers faster establishment and enhanced reporting for several VA claims and forms. Using this API provides many benefits, such as:\n - Automatic claim and POA establishment\n - Direct establishment of disability compensation claims in Veterans Benefits Management System (VBMS) to avoid unnecessary manual processing and entry by Veteran Service Representatives (VSRs)\n - Faster claims processing by several days\n - End-to-end claims status and result tracking by claim ID\n\nForms not supported by the Benefits Claims API are submitted using the [Benefits Intake API](https://developer.va.gov/explore/benefits/docs/benefits?version=current), which places uploaded PDFs into the Centralized Mail Portal to be manually processed.\n\n## Technical Overview\nThis API accepts a payload of requests and responses on a per-form basis, with the payload identifying the form and Veteran. Trackable responses provide a unique ID which is used with the appropriate GET endpoint to track a submission’s processing status.\n\n### Attachment and file size limits\nThere is no limit on the number of files a payload can contain, but size limits do apply.\n - Uploaded documents cannot be larger than 11\" x 11\"\n - The entire payload cannot exceed 5 GB\n - No single file in a payload can exceed 100 MB\n\n### Authentication and authorization\nTo make an API request, follow our [authentication process](https://developer.va.gov/explore/api/benefits-claims/authorization-code) to receive an [OAuth token](https://oauth.net/2/).\n\n**Important:** To get production access using client credentials grant, you must either work for VA or have specific VA agreements in place. If you have questions, [contact us](https://developer.va.gov/support/contact-us).\n\n#### Representative authorization\nRepresentatives seeking authorization for a Veteran must first [authenticate](https://developer.va.gov/explore/api/benefits-claims/authorization-code) and then pass the Veteran’s information in the right header:\n - SSN in X-VA-SSN\n - First name in X-VA-First-Name\n - Last name in X-VA-Last-Name\n - Date of birth in X-VA-Birth-Date\n\nOmitting the information will cause the API to treat the representative as the claimant.\n\n#### Veteran authorization\nVeterans seeking authorization do not need to include headers such as X-VA-First-Name since the token authentication via ID.me, MyHealtheVet, or DSLogon provides this information.\n\n### POA Codes\nVeteran representatives receive their organization’s POA code. If they are the assigned POA for a Veteran, that Veteran will have a matching POA code. When a claim is submitted, this API verifies that the representative and Veteran codes match against each other and the codes in the [Office of General Council (OGC) Database](https://www.va.gov/ogc/apps/accreditation/index.asp).\n\nUse the [Power of Attorney endpoint](#operations-Power_of_Attorney-post2122) to assign or update POA status. A newly appointed representative may not be able to submit forms for a Veteran until a day after their POA code is first associated with the OGC data set.\n\n### Test data for sandbox environment use\n[Test data](https://github.com/department-of-veterans-affairs/vets-api-clients/blob/master/test_accounts.md) is used for all forms in the sandbox environment and for 21-526 submissions in the staging environment.\n\n### Claim and form processing\nClaims and forms are first submitted by this API and then established in VBMS. A 200 response means only that your claim or form was submitted successfully. To see if your submission is processed or has reached VBMS, you must check its status using the appropriate GET endpoint and the ID returned with your submission response.\n\nA “claim established” status means the claim has reached VBMS. In sandbox, submissions can take over an hour to reach “claim established” status. In production, this may take over two days.\n" + "description": "This API automatically establishes and submits these VA forms.\n| Form number | Form name | Description |\n| :------------- | :----------: | -----------: |\n| [21-526EZ](https://www.va.gov/find-forms/about-form-21-526ez/) | Application for Disability Compensation and Related Compensation Benefits | Used to apply for VA disability compensation and related benefits. |\n| [21-0966](https://www.va.gov/find-forms/about-form-21-0966/) | Intent to File a Claim for Compensation and/or Pension, or Survivors Pension and/or DIC | Submits an intent to file to secure the earliest possible effective date for any retroactive payments. |\n| [21-22](https://www.va.gov/find-forms/about-form-21-22/) | Appointment of Veterans Service Organization as Claimant's Representative | Used to assign a Veterans Service Organization as a POA to help a Veteran with benefits or claims. |\n| [21-22a](https://www.va.gov/find-forms/about-form-21-22a/) | Appointment of Individual As Claimant's Representative | Used to assign an individual as a POA to help a Veteran with benefits or claims. |\n\nIt also lets Veterans or their authorized representatives:\n - Digitally submit supporting documentation for disability compensation claims\n - Retrieve information such as status for any claim, including pension and burial\n - Retrieve power of attorney (POA) status for individuals and Veterans Service Organizations (VSOs)\n - Retrieve intent to file status\n\n## Background\nThe Benefits Claims API offers faster establishment and enhanced reporting for several VA claims and forms. Using this API provides many benefits, such as:\n - Automatic claim and POA establishment\n - Direct establishment of disability compensation claims in Veterans Benefits Management System (VBMS) to avoid unnecessary manual processing and entry by Veteran Service Representatives (VSRs)\n - Faster claims processing by several days\n - End-to-end claims status and result tracking by claim ID\n\nForms not supported by the Benefits Claims API are submitted using the [Benefits Intake API](https://developer.va.gov/explore/benefits/docs/benefits?version=current), which places uploaded PDFs into the Centralized Mail Portal to be manually processed.\n\n## Appointing an accredited representative for dependents\nDependents of Veterans, such as spouses, children (biological and step), and parents (biological and foster) may be eligible for VA benefits and can request representation by an accredited representative.\n\nTo file claims through an accredited representative, dependents must appoint their own. Once appointed, the representative will have power of attorney (POA) to assist with the dependentʼs VA claims.\n\nBefore appointing a representative, the dependentʼs relationship to the Veteran must be established. If a new representative is being appointed, the dependentʼs relationship to the Veteran will be validated first. The representative will be appointed to the dependent, not the Veteran.\n\n## Technical Overview\nThis API accepts a payload of requests and responses on a per-form basis, with the payload identifying the form and Veteran. Trackable responses provide a unique ID which is used with the appropriate GET endpoint to track a submission’s processing status.\n\n### Attachment and file size limits\nThere is no limit on the number of files a payload can contain, but size limits do apply.\n - Uploaded documents cannot be larger than 11\" x 11\"\n - The entire payload cannot exceed 5 GB\n - No single file in a payload can exceed 100 MB\n\n### Authentication and authorization\nTo make an API request, follow our [authentication process](https://developer.va.gov/explore/api/benefits-claims/authorization-code) to receive an [OAuth token](https://oauth.net/2/).\n\n**Important:** To get production access using client credentials grant, you must either work for VA or have specific VA agreements in place. If you have questions, [contact us](https://developer.va.gov/support/contact-us).\n\n#### Representative authorization\nRepresentatives seeking authorization for a Veteran must first [authenticate](https://developer.va.gov/explore/api/benefits-claims/authorization-code) and then pass the Veteran’s information in the right header:\n - SSN in X-VA-SSN\n - First name in X-VA-First-Name\n - Last name in X-VA-Last-Name\n - Date of birth in X-VA-Birth-Date\n\nOmitting the information will cause the API to treat the representative as the claimant.\n\n#### Veteran authorization\nVeterans seeking authorization do not need to include headers such as X-VA-First-Name since the token authentication via ID.me, MyHealtheVet, or DSLogon provides this information.\n\n### POA Codes\nVeteran representatives receive their organization’s POA code. If they are the assigned POA for a Veteran, that Veteran will have a matching POA code. When a claim is submitted, this API verifies that the representative and Veteran codes match against each other and the codes in the [Office of General Council (OGC) Database](https://www.va.gov/ogc/apps/accreditation/index.asp).\n\nUse the [Power of Attorney endpoint](#operations-Power_of_Attorney-post2122) to assign or update POA status. A newly appointed representative may not be able to submit forms for a Veteran until a day after their POA code is first associated with the OGC data set.\n\n### Test data for sandbox environment use\n[Test data](https://github.com/department-of-veterans-affairs/vets-api-clients/blob/master/test_accounts.md) is used for all forms in the sandbox environment and for 21-526 submissions in the staging environment.\n\n### Claim and form processing\nClaims and forms are first submitted by this API and then established in VBMS. A 200 response means only that your claim or form was submitted successfully. To see if your submission is processed or has reached VBMS, you must check its status using the appropriate GET endpoint and the ID returned with your submission response.\n\nA “claim established” status means the claim has reached VBMS. In sandbox, submissions can take over an hour to reach “claim established” status. In production, this may take over two days.\n" }, "tags": [ { @@ -8634,7 +8634,7 @@ ] } ], - "description": "The endpoint establishes POA for a representative.\nOnce ID.me authorizes the Veteran or VSO via OpenID, this endpoint requests the:\n\n - poaCode\n - Signature, which can be a:\n\n - Base64-encoded image or signature block, allowing the API to auto-populate\nand attach the VA 21-22 form to the request without requiring a PDF upload, or\n\n - PDF documentation of VA 21-22 form with an ink signature, attached using the PUT /forms/2122/{id} endpoint\n\n\nA 200 response means the submission was successful, but does not mean the POA is effective.\nCheck the status of a POA submission by using the GET /forms/2122/{id} endpoint.\n\n", + "description": "Signature images\n\n\n\nIf the request includes signature images for both the Veteran and the representative, the API will:\n\n - Generate VA Form 21-22 PDF for organizations or VA Form 21-22a PDF for individual representatives.\n\n - Automatically establish POA for the representative.\n\n\n\nThe signature can be provided in either of these formats:\n\n - Base64-encoded image or signature block. This allows the API to auto-populate and attach the VA Form\n 21-22 without requiring a manual PDF upload.\n\n - PDF of VA Form 21-22 with an ink signature. This should be attached using the PUT /forms/2122/{id}\n endpoint.\n\n\n\n If signature images are not included in the initial request, the response will return an id which must be\n used to submit the signed PDF via the PUT /forms/2122/{id} endpoint.\n\n\n\nDependent claimant information:\n\n - If dependent claimant information is included in the request, the dependent relationship will be\n validated.\n\n - In this case, the representative will be appointed to the dependent claimant, not the Veteran.\n\n\n\nResponse information:\n\n - A successful submission returns a 200 response, indicating that the request was successfully processed.\n\n - A 200 response does not confirm that the POA has been appointed.\n\n - To check the status of a POA submission, use the GET /forms/2122/{id} endpoint.\n\n", "parameters": [ { "in": "header", diff --git a/modules/claims_api/app/swagger/claims_api/v2/dev/swagger.json b/modules/claims_api/app/swagger/claims_api/v2/dev/swagger.json index 1cfab6991e9..b27e94b6378 100644 --- a/modules/claims_api/app/swagger/claims_api/v2/dev/swagger.json +++ b/modules/claims_api/app/swagger/claims_api/v2/dev/swagger.json @@ -3,7 +3,7 @@ "info": { "title": "Benefits Claims", "version": "v2", - "description": "## Background\n\nThe Benefits Claims API Version 2 lets internal consumers: \n\n- Retrieve existing claim information, including status, by claim ID\n- Automatically establish an Intent To File (21-0966) in VBMS\n- Automatically establish a disability compensation claim (21-526EZ) in VBMS\n- Digitally submit supporting documentation for disability compensation claims\n- Retrieve the active Power of Attorney organization of individual with power of attorney for a Veteran\n- Automatically establish a power of attorney appointment in VBMS for an accredited organization (VA Form 21-22).\n- Automatically establish a power of attorney appointment in VBMS for an accredited individual (VA Form 21-22a).\n\nYou should use the [Benefits Claims API Version 1](https://developer.va.gov/explore/benefits/docs/claims?version=current) if you are a consumer outside of VA and do not have the necessary VA agreements to use this API.\n \n## Technical Overview\n\nThis API accepts a payload of requests and responses with the payload identifying the claim and Veteran. Responses provide the submission’s processing status. Responses also provide a unique ID which can be used with the appropriate GET endpoint to return detailed, end-to-end claims status tracking. \n\nEnd-to-end claims tracking provides the status of claims as they move through the submission process, but does not return whether the claim was approved or denied. \n\n### Claim statuses\n\nClaims are first submitted by this API and then established in Veterans Benefits Management System (VBMS). A 200 response means that the claim was successfully submitted by the API. It does not mean VA has received the claim. Use the appropriate GET endpoint and the ID returned with your submission response to confirm the status of the submission. Statuses are:\n\n- Pending - the claim is successfully submitted for processing\n- Errored - the submission encountered upstream errors\n- Canceled - the claim was identified as a duplicate or another issue caused the claim to be canceled. For duplicate claims, the tracking of the claim's progress happens under a different Claim ID . \n\nOther statuses this API returns align with the [VA.gov](http://va.gov/) [claim status descriptions](https://www.va.gov/resources/what-your-claim-status-means/), which are:\n\n- Claim received\n- Initial review\n- Evidence gathering, review, and decision\n- Preparation for notification\n- Complete\n\n### Finding a Veteran's unique VA ID\n\nThis API uses a unique Veteran identifier to identify the subject of each API request. This Veteran identifier can be retrieved by passing the Veteran’s first name, last name, DOB, and SSN to the ‘/veteran-id’ endpoint. This identifier should then be used as the Veteran ID parameter in request URLs.\n\nNote: though Veteran identifiers are typically static, they may change over time. If a specific Veteran ID suddenly responds with a ‘404 not found’ error, the identifier may have changed. It’s a good idea to periodically check the identifier for each Veteran.\n\n### Authentication and authorization\n\nThe authentication model for the Benefits Claims Version 2 is based on OAuth 2.0 / OpenID Connect and supports the [client credentials grant](https://developer.va.gov/explore/authorization/docs/client-credentials?api=claims).\n\n**Important**: To get production access, you must either work for VA or have specific VA agreements in place. If you have questions, [contact us](https://developer.va.gov/support/contact-us).\n\n### Test data for sandbox environment use\n\nWe use mock [test data in the sandbox environment](https://github.com/department-of-veterans-affairs/vets-api-clients/blob/master/test_accounts.md). Sandbox test data and test users for the Benefits Claims API are valid for all versions of the API.\n" + "description": "## Background\n\nThe Benefits Claims API Version 2 lets internal consumers: \n\n- Retrieve existing claim information, including status, by claim ID\n- Automatically establish an Intent To File (21-0966) in VBMS\n- Automatically establish a disability compensation claim (21-526EZ) in VBMS\n- Digitally submit supporting documentation for disability compensation claims\n- Retrieve the active Power of Attorney organization of individual with power of attorney for a Veteran\n- Automatically establish a power of attorney appointment in VBMS for an accredited organization (VA Form 21-22).\n- Automatically establish a power of attorney appointment in VBMS for an accredited individual (VA Form 21-22a).\n\nYou should use the [Benefits Claims API Version 1](https://developer.va.gov/explore/benefits/docs/claims?version=current) if you are a consumer outside of VA and do not have the necessary VA agreements to use this API.\n \n## Appointing an accredited representative for dependents\n\nDependents of Veterans, such as spouses, children (biological and step), and parents (biological and foster) may be eligible for VA benefits and can request representation by an accredited representative.\n\nTo file claims through an accredited representative, dependents must appoint their own. Once appointed, the representative will have power of attorney (POA) to assist with the dependentʼs VA claims.\n\nBefore appointing a representative, the dependentʼs relationship to the Veteran must be established. If a new representative is being appointed, the dependentʼs relationship to the Veteran will be validated first. The representative will be appointed to the dependent, not the Veteran.\n\n## Technical Overview\n\nThis API accepts a payload of requests and responses with the payload identifying the claim and Veteran. Responses provide the submission’s processing status. Responses also provide a unique ID which can be used with the appropriate GET endpoint to return detailed, end-to-end claims status tracking. \n\nEnd-to-end claims tracking provides the status of claims as they move through the submission process, but does not return whether the claim was approved or denied. \n\n### Claim statuses\n\nClaims are first submitted by this API and then established in Veterans Benefits Management System (VBMS). A 200 response means that the claim was successfully submitted by the API. It does not mean VA has received the claim. Use the appropriate GET endpoint and the ID returned with your submission response to confirm the status of the submission. Statuses are:\n\n- Pending - the claim is successfully submitted for processing\n- Errored - the submission encountered upstream errors\n- Canceled - the claim was identified as a duplicate or another issue caused the claim to be canceled. For duplicate claims, the tracking of the claim's progress happens under a different Claim ID . \n\nOther statuses this API returns align with the [VA.gov](http://va.gov/) [claim status descriptions](https://www.va.gov/resources/what-your-claim-status-means/), which are:\n\n- Claim received\n- Initial review\n- Evidence gathering, review, and decision\n- Preparation for notification\n- Complete\n\n### Finding a Veteran's unique VA ID\n\nThis API uses a unique Veteran identifier to identify the subject of each API request. This Veteran identifier can be retrieved by passing the Veteran’s first name, last name, DOB, and SSN to the ‘/veteran-id’ endpoint. This identifier should then be used as the Veteran ID parameter in request URLs.\n\nNote: though Veteran identifiers are typically static, they may change over time. If a specific Veteran ID suddenly responds with a ‘404 not found’ error, the identifier may have changed. It’s a good idea to periodically check the identifier for each Veteran.\n\n### Authentication and authorization\n\nThe authentication model for the Benefits Claims Version 2 is based on OAuth 2.0 / OpenID Connect and supports the [client credentials grant](https://developer.va.gov/explore/authorization/docs/client-credentials?api=claims).\n\n**Important**: To get production access, you must either work for VA or have specific VA agreements in place. If you have questions, [contact us](https://developer.va.gov/support/contact-us).\n\n### Test data for sandbox environment use\n\nWe use mock [test data in the sandbox environment](https://github.com/department-of-veterans-affairs/vets-api-clients/blob/master/test_accounts.md). Sandbox test data and test users for the Benefits Claims API are valid for all versions of the API.\n" }, "tags": [ { @@ -14421,7 +14421,7 @@ } } ], - "description": "Updates current Power of Attorney for Veteran.", + "description": "Dependent Claimant Information:\n\n - If dependent claimant information is included in the request, the dependent relationship will be\n validated.\n\n - In this case, the representative will be appointed to the dependent claimant, not the Veteran.\n\n\n\nResponse Information:\n\n - A 202 response indicates that the submission was accepted.\n\n - To check the status of a POA submission, use GET /veterans/{veteranId}/power-of-attorney/{id} endpoint.\n\n", "responses": { "202": { "description": "Valid request response", @@ -15079,7 +15079,7 @@ "/veterans/{veteranId}/2122": { "post": { "summary": "Appoint an organization Power of Attorney for a Veteran.", - "description": "Updates current Power of Attorney for Veteran.", + "description": "Dependent Claimant Information:\n\n - If dependent claimant information is included in the request, the dependent relationship will be\n validated.\n\n - In this case, the representative will be appointed to the dependent claimant, not the Veteran.\n\n\n\nResponse Information:\n\n - A 202 response indicates that the submission was accepted.\n\n - To check the status of a POA submission, use GET /veterans/{veteranId}/power-of-attorney/{id} endpoint.\n\n", "tags": [ "Power of Attorney" ], diff --git a/modules/claims_api/app/swagger/claims_api/v2/production/swagger.json b/modules/claims_api/app/swagger/claims_api/v2/production/swagger.json index 23b6d23eabe..97e484bdf8b 100644 --- a/modules/claims_api/app/swagger/claims_api/v2/production/swagger.json +++ b/modules/claims_api/app/swagger/claims_api/v2/production/swagger.json @@ -3,7 +3,7 @@ "info": { "title": "Benefits Claims", "version": "v2", - "description": "## Background\n\nThe Benefits Claims API Version 2 lets internal consumers: \n\n- Retrieve existing claim information, including status, by claim ID\n- Automatically establish an Intent To File (21-0966) in VBMS\n- Automatically establish a disability compensation claim (21-526EZ) in VBMS\n- Digitally submit supporting documentation for disability compensation claims\n- Retrieve the active Power of Attorney organization of individual with power of attorney for a Veteran\n- Automatically establish a power of attorney appointment in VBMS for an accredited organization (VA Form 21-22).\n- Automatically establish a power of attorney appointment in VBMS for an accredited individual (VA Form 21-22a).\n\nYou should use the [Benefits Claims API Version 1](https://developer.va.gov/explore/benefits/docs/claims?version=current) if you are a consumer outside of VA and do not have the necessary VA agreements to use this API.\n \n## Technical Overview\n\nThis API accepts a payload of requests and responses with the payload identifying the claim and Veteran. Responses provide the submission’s processing status. Responses also provide a unique ID which can be used with the appropriate GET endpoint to return detailed, end-to-end claims status tracking. \n\nEnd-to-end claims tracking provides the status of claims as they move through the submission process, but does not return whether the claim was approved or denied. \n\n### Claim statuses\n\nClaims are first submitted by this API and then established in Veterans Benefits Management System (VBMS). A 200 response means that the claim was successfully submitted by the API. It does not mean VA has received the claim. Use the appropriate GET endpoint and the ID returned with your submission response to confirm the status of the submission. Statuses are:\n\n- Pending - the claim is successfully submitted for processing\n- Errored - the submission encountered upstream errors\n- Canceled - the claim was identified as a duplicate or another issue caused the claim to be canceled. For duplicate claims, the tracking of the claim's progress happens under a different Claim ID . \n\nOther statuses this API returns align with the [VA.gov](http://va.gov/) [claim status descriptions](https://www.va.gov/resources/what-your-claim-status-means/), which are:\n\n- Claim received\n- Initial review\n- Evidence gathering, review, and decision\n- Preparation for notification\n- Complete\n\n### Finding a Veteran's unique VA ID\n\nThis API uses a unique Veteran identifier to identify the subject of each API request. This Veteran identifier can be retrieved by passing the Veteran’s first name, last name, DOB, and SSN to the ‘/veteran-id’ endpoint. This identifier should then be used as the Veteran ID parameter in request URLs.\n\nNote: though Veteran identifiers are typically static, they may change over time. If a specific Veteran ID suddenly responds with a ‘404 not found’ error, the identifier may have changed. It’s a good idea to periodically check the identifier for each Veteran.\n\n### Authentication and authorization\n\nThe authentication model for the Benefits Claims Version 2 is based on OAuth 2.0 / OpenID Connect and supports the [client credentials grant](https://developer.va.gov/explore/authorization/docs/client-credentials?api=claims).\n\n**Important**: To get production access, you must either work for VA or have specific VA agreements in place. If you have questions, [contact us](https://developer.va.gov/support/contact-us).\n\n### Test data for sandbox environment use\n\nWe use mock [test data in the sandbox environment](https://github.com/department-of-veterans-affairs/vets-api-clients/blob/master/test_accounts.md). Sandbox test data and test users for the Benefits Claims API are valid for all versions of the API.\n" + "description": "## Background\n\nThe Benefits Claims API Version 2 lets internal consumers: \n\n- Retrieve existing claim information, including status, by claim ID\n- Automatically establish an Intent To File (21-0966) in VBMS\n- Automatically establish a disability compensation claim (21-526EZ) in VBMS\n- Digitally submit supporting documentation for disability compensation claims\n- Retrieve the active Power of Attorney organization of individual with power of attorney for a Veteran\n- Automatically establish a power of attorney appointment in VBMS for an accredited organization (VA Form 21-22).\n- Automatically establish a power of attorney appointment in VBMS for an accredited individual (VA Form 21-22a).\n\nYou should use the [Benefits Claims API Version 1](https://developer.va.gov/explore/benefits/docs/claims?version=current) if you are a consumer outside of VA and do not have the necessary VA agreements to use this API.\n \n## Appointing an accredited representative for dependents\n\nDependents of Veterans, such as spouses, children (biological and step), and parents (biological and foster) may be eligible for VA benefits and can request representation by an accredited representative.\n\nTo file claims through an accredited representative, dependents must appoint their own. Once appointed, the representative will have power of attorney (POA) to assist with the dependentʼs VA claims.\n\nBefore appointing a representative, the dependentʼs relationship to the Veteran must be established. If a new representative is being appointed, the dependentʼs relationship to the Veteran will be validated first. The representative will be appointed to the dependent, not the Veteran.\n\n## Technical Overview\n\nThis API accepts a payload of requests and responses with the payload identifying the claim and Veteran. Responses provide the submission’s processing status. Responses also provide a unique ID which can be used with the appropriate GET endpoint to return detailed, end-to-end claims status tracking. \n\nEnd-to-end claims tracking provides the status of claims as they move through the submission process, but does not return whether the claim was approved or denied. \n\n### Claim statuses\n\nClaims are first submitted by this API and then established in Veterans Benefits Management System (VBMS). A 200 response means that the claim was successfully submitted by the API. It does not mean VA has received the claim. Use the appropriate GET endpoint and the ID returned with your submission response to confirm the status of the submission. Statuses are:\n\n- Pending - the claim is successfully submitted for processing\n- Errored - the submission encountered upstream errors\n- Canceled - the claim was identified as a duplicate or another issue caused the claim to be canceled. For duplicate claims, the tracking of the claim's progress happens under a different Claim ID . \n\nOther statuses this API returns align with the [VA.gov](http://va.gov/) [claim status descriptions](https://www.va.gov/resources/what-your-claim-status-means/), which are:\n\n- Claim received\n- Initial review\n- Evidence gathering, review, and decision\n- Preparation for notification\n- Complete\n\n### Finding a Veteran's unique VA ID\n\nThis API uses a unique Veteran identifier to identify the subject of each API request. This Veteran identifier can be retrieved by passing the Veteran’s first name, last name, DOB, and SSN to the ‘/veteran-id’ endpoint. This identifier should then be used as the Veteran ID parameter in request URLs.\n\nNote: though Veteran identifiers are typically static, they may change over time. If a specific Veteran ID suddenly responds with a ‘404 not found’ error, the identifier may have changed. It’s a good idea to periodically check the identifier for each Veteran.\n\n### Authentication and authorization\n\nThe authentication model for the Benefits Claims Version 2 is based on OAuth 2.0 / OpenID Connect and supports the [client credentials grant](https://developer.va.gov/explore/authorization/docs/client-credentials?api=claims).\n\n**Important**: To get production access, you must either work for VA or have specific VA agreements in place. If you have questions, [contact us](https://developer.va.gov/support/contact-us).\n\n### Test data for sandbox environment use\n\nWe use mock [test data in the sandbox environment](https://github.com/department-of-veterans-affairs/vets-api-clients/blob/master/test_accounts.md). Sandbox test data and test users for the Benefits Claims API are valid for all versions of the API.\n" }, "tags": [ { @@ -13766,7 +13766,7 @@ } } ], - "description": "Updates current Power of Attorney for Veteran.", + "description": "Dependent Claimant Information:\n\n - If dependent claimant information is included in the request, the dependent relationship will be\n validated.\n\n - In this case, the representative will be appointed to the dependent claimant, not the Veteran.\n\n\n\nResponse Information:\n\n - A 202 response indicates that the submission was accepted.\n\n - To check the status of a POA submission, use GET /veterans/{veteranId}/power-of-attorney/{id} endpoint.\n\n", "responses": { "202": { "description": "Valid request response", @@ -14424,7 +14424,7 @@ "/veterans/{veteranId}/2122": { "post": { "summary": "Appoint an organization Power of Attorney for a Veteran.", - "description": "Updates current Power of Attorney for Veteran.", + "description": "Dependent Claimant Information:\n\n - If dependent claimant information is included in the request, the dependent relationship will be\n validated.\n\n - In this case, the representative will be appointed to the dependent claimant, not the Veteran.\n\n\n\nResponse Information:\n\n - A 202 response indicates that the submission was accepted.\n\n - To check the status of a POA submission, use GET /veterans/{veteranId}/power-of-attorney/{id} endpoint.\n\n", "tags": [ "Power of Attorney" ], diff --git a/modules/claims_api/spec/requests/v1/forms/rswag_2122_spec.rb b/modules/claims_api/spec/requests/v1/forms/rswag_2122_spec.rb index 545f0ac0e64..de48e14544b 100644 --- a/modules/claims_api/spec/requests/v1/forms/rswag_2122_spec.rb +++ b/modules/claims_api/spec/requests/v1/forms/rswag_2122_spec.rb @@ -50,14 +50,30 @@ consumes 'application/json' produces 'application/json' post_description = <<~VERBIAGE - The endpoint establishes POA for a representative. - Once ID.me authorizes the Veteran or VSO via OpenID, this endpoint requests the: - \n - poaCode\n - Signature, which can be a: - \n - Base64-encoded image or signature block, allowing the API to auto-populate - and attach the VA 21-22 form to the request without requiring a PDF upload, or - \n - PDF documentation of VA 21-22 form with an ink signature, attached using the PUT /forms/2122/{id} endpoint - \n\nA 200 response means the submission was successful, but does not mean the POA is effective. - Check the status of a POA submission by using the GET /forms/2122/{id} endpoint.\n + Signature images\n\n + + If the request includes signature images for both the Veteran and the representative, the API will:\n + - Generate VA Form 21-22 PDF for organizations or VA Form 21-22a PDF for individual representatives.\n + - Automatically establish POA for the representative.\n\n + + The signature can be provided in either of these formats:\n + - Base64-encoded image or signature block. This allows the API to auto-populate and attach the VA Form + 21-22 without requiring a manual PDF upload.\n + - PDF of VA Form 21-22 with an ink signature. This should be attached using the PUT /forms/2122/{id} + endpoint.\n\n + + If signature images are not included in the initial request, the response will return an id which must be + used to submit the signed PDF via the PUT /forms/2122/{id} endpoint.\n\n + + Dependent claimant information:\n + - If dependent claimant information is included in the request, the dependent relationship will be + validated.\n + - In this case, the representative will be appointed to the dependent claimant, not the Veteran.\n\n + + Response information:\n + - A successful submission returns a 200 response, indicating that the request was successfully processed.\n + - A 200 response does not confirm that the POA has been appointed.\n + - To check the status of a POA submission, use the GET /forms/2122/{id} endpoint.\n VERBIAGE description post_description diff --git a/modules/claims_api/spec/requests/v2/veterans/rswag_power_of_attorney_spec.rb b/modules/claims_api/spec/requests/v2/veterans/rswag_power_of_attorney_spec.rb index 37c169a0164..97d96e5ae6e 100644 --- a/modules/claims_api/spec/requests/v2/veterans/rswag_power_of_attorney_spec.rb +++ b/modules/claims_api/spec/requests/v2/veterans/rswag_power_of_attorney_spec.rb @@ -197,7 +197,17 @@ let(:veteranId) { '1013062086V794840' } # rubocop:disable RSpec/VariableName let(:Authorization) { 'Bearer token' } parameter SwaggerSharedComponents::V2.body_examples[:power_of_attorney_2122a] - description 'Updates current Power of Attorney for Veteran.' + post_description = <<~VERBIAGE + Dependent Claimant Information:\n + - If dependent claimant information is included in the request, the dependent relationship will be + validated.\n + - In this case, the representative will be appointed to the dependent claimant, not the Veteran.\n\n + + Response Information:\n + - A 202 response indicates that the submission was accepted.\n + - To check the status of a POA submission, use GET /veterans/{veteranId}/power-of-attorney/{id} endpoint.\n + VERBIAGE + description post_description let(:scopes) { %w[system/claim.read system/claim.write] } let(:poa_code) { '067' } let(:bgs_poa) { { person_org_name: "#{poa_code} name-here" } } @@ -345,7 +355,17 @@ path '/veterans/{veteranId}/2122' do post 'Appoint an organization Power of Attorney for a Veteran.' do - description 'Updates current Power of Attorney for Veteran.' + post_description = <<~VERBIAGE + Dependent Claimant Information:\n + - If dependent claimant information is included in the request, the dependent relationship will be + validated.\n + - In this case, the representative will be appointed to the dependent claimant, not the Veteran.\n\n + + Response Information:\n + - A 202 response indicates that the submission was accepted.\n + - To check the status of a POA submission, use GET /veterans/{veteranId}/power-of-attorney/{id} endpoint.\n + VERBIAGE + description post_description tags 'Power of Attorney' operationId 'post2122' security [