Obtain production credentials for the Benefits Claims API via the VA Lighthouse developer portal (developer.va.gov); this API requires the Client Credentials Grant (CCG) OAuth flow with the claims.write scope.
Authenticate by posting a signed JWT client assertion to the VA token endpoint to receive a short-lived bearer token.
POST to /services/claims/v2/veterans/{veteranId}/claims with a JSON body containing the claimType (e.g., '526EZ'), serviceInformation, disabilities array (each with diagnosticCode and name), and veteran contact information.
Store the returned claimId; use GET /services/claims/v2/veterans/{veteranId}/claims/{claimId} to poll for status transitions such as 'CLAIM_RECEIVED', 'UNDER_REVIEW', 'GATHERING_OF_EVIDENCE', and 'COMPLETE'.
To submit supporting documents, use the Benefits Documents API (a companion API) to upload PDFs associated with the claimId; documents must be under the maximum file size and in accepted formats.
Monitor the claim status endpoint until a final status is reached; relay the final determination to the veteran or VSO representative.
Known gotchas
The Benefits Claims API auto-establishes claims in VBMS (Veterans Benefits Management System) directly — errors in submitted data can create real claims records in VA systems even in production; test thoroughly in sandbox first.
Only accredited Veterans Service Organizations (VSOs), attorneys, and claims agents are authorized to submit claims on a veteran's behalf; verify your organization's accreditation before seeking production access.
The veteranId parameter in the API path is the veteran's ICN (Integration Control Number), not their SSN or VA file number; obtain the ICN from the VA Identity Service if you do not already have it.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp