{"openapi":"3.0.0","info":{"title":"Legacy Appeals","version":"v0","contact":{"name":"developer.va.gov"},"description":"The Legacy Appeals API lets you retrieve a claimant's active legacy appeals, which are not part of the Appeals Modernization Act (AMA) process. Claimants may be Veterans or dependents of Veterans, such as spouses, children (biological and step), and parents (biological and foster).\n\nYou can use legacy appeals data to file a Notice of Disagreement. [Learn more about managing a legacy appeal](https://www.va.gov/decision-reviews/legacy-appeals/).\n\nTo check the status of all decision reviews or appeals for a specified individual, use the [Appeals Status API](/explore/api/appeals-status/docs).\n\n## Technical overview\n\n### Authentication and authorization\nThe authorization model for the Legacy Appeals API uses OAuth 2.0/OpenID Connect. The following models are supported:\n* [Authorization Code Grant (ACG)](/explore/api/legacy-appeals/authorization-code)\n* [Client Credentials Grant (CCG)](/explore/api/legacy-appeals/client-credentials)\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](/support/contact-us).\n\n### Test data\nOur sandbox environment is populated with [claimant test data](/explore/api/legacy-appeals/test-users) that can be used to test various response scenarios. This sandbox data contains no PII or PHI, but mimics real claimant account information.\n"},"tags":[{"name":"Legacy Appeals"}],"paths":{"/legacy-appeals":{"get":{"summary":"Returns eligible appeals in the legacy process for a claimant.","tags":["Legacy Appeals"],"operationId":"GET:/legacy-appeals","security":[{"productionOauth":["veteran/LegacyAppeals.read","representative/LegacyAppeals.read","system/LegacyAppeals.read"]},{"sandboxOauth":["veteran/LegacyAppeals.read","representative/LegacyAppeals.read","system/LegacyAppeals.read"]}],"description":"Returns eligible legacy appeals for a claimant.","parameters":[{"name":"icn","description":"Claimant's Integration Control Number (ICN). Optional when using a veteran-scoped token. Required when using a representative- or system-scoped token.","example":"1012832025V743496","schema":{"type":"string","pattern":"^[0-9]{10}V[0-9]{6}$"},"in":"query","required":false}],"responses":{"200":{"description":"Claimant's legacy appeals","content":{"application/json":{"examples":{"with a veteran-scoped token (no 'icn' parameter necessary)":{"value":{"data":[{"id":"2760964","type":"legacyAppeal","attributes":{"issues":[{"summary":"Service connection, pancreatitis"}],"veteranFullName":"Elda Z Quigley","decisionDate":"2021-05-04","latestSocSsocDate":"2021-06-12"}}]}},"with a representative-scoped token ('icn' parameter is necessary)":{"value":{"data":[{"id":"2760964","type":"legacyAppeal","attributes":{"issues":[{"summary":"Service connection, pancreatitis"}],"veteranFullName":"Elda Z Quigley","decisionDate":"2021-05-04","latestSocSsocDate":"2021-06-12"}}]}},"with a system-scoped token ('icn' parameter is necessary)":{"value":{"data":[{"id":"2760964","type":"legacyAppeal","attributes":{"issues":[{"summary":"Service connection, pancreatitis"}],"veteranFullName":"Elda Z Quigley","decisionDate":"2021-05-04","latestSocSsocDate":"2021-06-12"}}]}}},"schema":{"$ref":"#/components/schemas/legacyAppeals"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"example":{"errors":[{"title":"Not authorized","detail":"Not authorized","code":"401","status":"401"}]},"schema":{"$ref":"#/components/schemas/errorModel"}}}},"403":{"description":"Forbidden","content":{"application/json":{"example":{"errors":[{"title":"Forbidden","detail":"Invalid 'icn' parameter: claimants may access only their own records.","code":"403","status":"403"}]},"schema":{"$ref":"#/components/schemas/errorModel"}}}},"404":{"description":"Not Found","content":{"application/json":{"example":{"errors":[{"title":"Resource not found","detail":"A matching claimant was not found in our systems.","code":"404","status":"404"}]},"schema":{"$ref":"#/components/schemas/errorModel"}}}},"413":{"description":"Payload too large","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"Request size limit exceeded"}}}}},"422":{"description":"Unprocessable Content","content":{"application/json":{"examples":{"Invalid icn parameter":{"value":{"errors":[{"title":"Invalid pattern","detail":"'1234567890' did not match the defined pattern.","code":"143","source":{"parameter":"icn"},"status":"422","meta":{"regex":"^[0-9]{10}V[0-9]{6}$"}}]}},"Missing icn parameter with a representative-scoped token":{"value":{"errors":[{"title":"Missing required fields","detail":"One or more expected fields were not found.","code":"145","source":{"parameter":""},"status":"422","meta":{"missingFields":["icn"]}}]}},"Missing icn parameter with a system-scoped token":{"value":{"errors":[{"title":"Missing required fields","detail":"One or more expected fields were not found.","code":"145","source":{"parameter":""},"status":"422","meta":{"missingFields":["icn"]}}]}}},"schema":{"$ref":"#/components/schemas/errorModel"}}}},"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":{"example":{"errors":[{"title":"Internal server error","detail":"Internal server error","code":"500","status":"500"}]},"schema":{"$ref":"#/components/schemas/errorModel"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"example":{"errors":[{"title":"Service Unavailable","detail":"Received an unusable response from upstream service.","code":"503","status":"503"}]},"schema":{"$ref":"#/components/schemas/errorModel"}}}},"504":{"description":"Gateway Timeout","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"example":{"message":"The server took too long to respond"}}}}}}}}},"components":{"securitySchemes":{"productionOauth":{"type":"oauth2","description":"The authorization model for the Legacy Appeals API uses OAuth 2.0/OpenID Connect. The following models are supported: [Authorization Code Grant (ACG)](/explore/api/legacy-appeals/authorization-code) and [Client Credentials Grant (CCG)](/explore/api/legacy-appeals/client-credentials).","flows":{"authorizationCode":{"authorizationUrl":"https://api.va.gov/oauth2/appeals/v1/authorization","tokenUrl":"https://api.va.gov/oauth2/appeals/v1/token","scopes":{"veteran/LegacyAppeals.read":"Legacy appeals info","representative/LegacyAppeals.read":"Legacy appeals info"}},"clientCredentials":{"tokenUrl":"https://api.va.gov/oauth2/appeals/system/v1/token","scopes":{"system/LegacyAppeals.read":"Legacy appeals info"}}}},"sandboxOauth":{"type":"oauth2","description":"The authorization model for the Legacy Appeals API uses OAuth 2.0/OpenID Connect. The following models are supported: [Authorization Code Grant (ACG)](/explore/api/legacy-appeals/authorization-code) and [Client Credentials Grant (CCG)](/explore/api/legacy-appeals/client-credentials).","flows":{"authorizationCode":{"authorizationUrl":"https://sandbox-api.va.gov/oauth2/appeals/v1/authorization","tokenUrl":"https://sandbox-api.va.gov/oauth2/appeals/v1/token","scopes":{"veteran/LegacyAppeals.read":"Legacy appeals info","representative/LegacyAppeals.read":"Legacy appeals info"}},"clientCredentials":{"tokenUrl":"https://deptva-eval.okta.com/oauth2/auskff5o6xsoQVngk2p7/v1/token","scopes":{"system/LegacyAppeals.read":"Legacy appeals info"}}}}},"schemas":{"errorModel":{"required":["errors"],"properties":{"errors":{"type":"array","items":{"additionalProperties":false,"required":["title"],"properties":{"title":{"type":"string","description":"HTTP error title"},"detail":{"type":"string","description":"HTTP error detail"},"code":{"type":"string","description":"HTTP error code"},"source":{"type":"object","additionalProperties":false,"description":"Source of error","properties":{"pointer":{"type":"string","description":"Pointer to source of error"},"parameter":{"type":"string","description":"Invalid request parameter"},"header":{"type":"string","description":"Invalid header"}}},"status":{"type":"string","description":"HTTP error code"},"meta":{"type":"object","description":"Meta information","properties":{"missingFields":{"type":"array","items":{"type":"string"},"description":"List of missing fields"}}}}}}}},"legacyAppeal":{"properties":{"id":{"type":"string","description":"ID from VACOLS (Veteran Appeals Control and Locator Service)","example":"3085659"},"type":{"type":"string","description":"Appeal type","example":"legacyAppeal"},"attributes":{"type":"object","description":"Appeal attributes","properties":{"issues":{"type":"array","description":"Issues in the appeal","items":{"type":"object","properties":{"summary":{"type":"string","description":"Summary of a single issue","example":"Service connection, hearing loss"}}}},"veteranFullName":{"type":"string","description":"Claimant's full name","example":"Elda Z Quigley"},"decisionDate":{"nullable":true,"type":"string","format":"date","description":"Date of the appeal's original decision","example":"2021-05-04"},"latestSocSsocDate":{"nullable":true,"type":"string","format":"date","description":"Date of the appeal's most recent SOC/SSOC (Statement of Case/Supplemental Statement of Case)","example":"2021-06-12"}}}}},"legacyAppeals":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/legacyAppeal"}}}}}},"servers":[{"url":"https://sandbox-api.va.gov/services/appeals/legacy-appeals/{version}","description":"Sandbox","variables":{"version":{"default":"v0"}}},{"url":"https://api.va.gov/services/appeals/legacy-appeals/{version}","description":"Production","variables":{"version":{"default":"v0"}}}]}