Veterans Affairs VSO Accredited Representatives API

openapi: 3.0.0
info:
  title: Appealable Issues VSO Accredited Representatives API
  version: v0
  contact:
    name: developer.va.gov
  description: "The Appealable Issues API lets you retrieve a list of a claimant’s appealable issues and any chains of preceding issues. Appealable issues are issues from claims about which VA has made a decision that may be eligible for appeal. Not all appealable issues are guaranteed to be eligible for appeal; for example, claimants may have another appeal in progress for an issue.\n\nTo check the status of all decision reviews and appeals for a specified individual, use the [Appeals Status API](https://developer.va.gov/explore/api/appeals-status/docs).\n\nTo file an appeal or decision review, use one of these APIs: \n* [Higher-Level Reviews API](https://developer.va.gov/explore/api/higher-level-reviews/docs)\n* [Notice of Disagreements API](https://developer.va.gov/explore/api/notice-of-disagreements/docs)\n* [Supplemental Claims API](https://developer.va.gov/explore/api/supplemental-claims/docs)\n\n## Technical overview\nThe Appealable Issues API pulls data from Caseflow, a case management system. It provides decision review and appeal data that can be used for submitting a Higher Level Review, Notice of Disagreement, or Supplemental Claim.\n\n### Authorization and Access\nThe authentication model for the Appealable Issues API uses OAuth 2.0/OpenID Connect. The following authorization models are supported:\n* [Authorization code flow](https://developer.va.gov/explore/api/appealable-issues/authorization-code)\n* [Client Credentials Grant (CCG)](https://developer.va.gov/explore/api/appealable-issues/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](https://developer.va.gov/support/contact-us).\n\n### Test data\n\nOur sandbox environment is populated with [Veteran test data](https://github.com/department-of-veterans-affairs/vets-api-clients/blob/master/test_accounts/appealable_issues_test_accounts.md) that can be used to test various response scenarios. This sandbox data contains no PII or PHI, but mimics real Veteran account information.\n"
servers:
- url: https://sandbox-api.va.gov/services/appeals/appealable-issues/{version}
  description: VA.gov API sandbox environment
  variables:
    version:
      default: v0
- url: https://api.va.gov/services/appeals/appealable-issues/{version}
  description: VA.gov API production environment
  variables:
    version:
      default: v0
tags:
- name: VSO Accredited Representatives
paths:
  /v0/vso_accredited_representatives:
    get:
      summary: Get a list of veteran service officers
      description: Retrieve accredited veteran service officers based on location, name, and type. Supports sorting and pagination.
      operationId: getVSOAccreditedRepresentatives
      tags:
      - VSO Accredited Representatives
      parameters:
      - in: query
        name: lat
        required: true
        schema:
          type: number
          format: float
          minimum: -90
          maximum: 90
        description: Latitude for the search location.
      - in: query
        name: long
        required: true
        schema:
          type: number
          format: float
          minimum: -180
          maximum: 180
        description: Longitude for the search location.
      - in: query
        name: type
        required: true
        schema:
          type: string
        description: Type of accredited representative (e.g., veteran_service_officer).
      - in: query
        name: distance
        schema:
          type: number
          format: integer
          enum:
          - 5
          - 10
          - 25
          - 50
          - 100
          - 200
        description: Search radius in miles.
      - in: query
        name: name
        schema:
          type: string
        description: Name to search for.
      - in: query
        name: org_name
        schema:
          type: string
        description: Name of the Veterans Service Organization (VSO). Must be an exact match.
      - in: query
        name: page
        schema:
          type: integer
          default: 1
        description: Page number for pagination.
      - in: query
        name: per_page
        schema:
          type: integer
          default: 10
        description: Number of results per page.
      - in: query
        name: sort
        schema:
          type: string
          enum:
          - distance_asc
          - first_name_asc
          - first_name_desc
          - last_name_asc
          - last_name_desc
          default: distance_asc
        description: Sorting order of the results.
      responses:
        '200':
          description: A list of accredited representatives
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VSORepresentative'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
components:
  schemas:
    BadRequestError:
      type: object
      properties:
        errors:
          type: object
          properties:
            title:
              type: string
              example: Invalid field value
            detail:
              type: string
              example: my_rep is not a valid value for type
            code:
              type: string
              example: '103'
            status:
              type: string
              example: '400'
    VSORepresentative:
      allOf:
      - $ref: '#/components/schemas/BaseRepresentative'
      - type: object
        properties:
          organization_names:
            type: array
            items:
              type: string
    InternalServerError:
      type: object
      properties:
        errors:
          type: object
          properties:
            title:
              type: string
              example: Internal server error
            detail:
              type: string
              example: Internal server error
            code:
              type: string
              example: '500'
            status:
              type: string
              example: '500'
  securitySchemes:
    bearer_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
    productionOauth:
      type: oauth2
      description: 'The authentication model for the Appealable Issues API uses OAuth 2.0/OpenID Connect. The following authorization models are supported: [Authorization code flow](https://developer.va.gov/explore/api/appealable-issues/authorization-code) and [Client Credentials Grant (CCG)](https://developer.va.gov/explore/api/appealable-issues/client-credentials).'
      flows:
        authorizationCode:
          authorizationUrl: https://api.va.gov/oauth2/appeals/v1/authorization
          tokenUrl: https://api.va.gov/oauth2/appeals/v1/token
          scopes:
            veteran/AppealableIssues.read: Appealable issues info
            veteran/appeals.read: Appeals info
            representative/AppealableIssues.read: Appealable issues info
            representative/appeals.read: Appeals info
        clientCredentials:
          tokenUrl: 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).
          scopes:
            system/AppealableIssues.read: Appealable issues info
            system/appeals.read: Appeals info
    sandboxOauth:
      type: oauth2
      description: 'The authentication model for the Appealable Issues API uses OAuth 2.0/OpenID Connect. The following authorization models are supported: [Authorization code flow](https://developer.va.gov/explore/api/appealable-issues/authorization-code) and [Client Credentials Grant (CCG)](https://developer.va.gov/explore/api/appealable-issues/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/AppealableIssues.read: Appealable issues info
            veteran/appeals.read: Appeals info
            representative/AppealableIssues.read: Appealable issues info
            representative/appeals.read: Appeals info
        clientCredentials:
          tokenUrl: https://deptva-eval.okta.com/oauth2/auskff5o6xsoQVngk2p7/v1/token
          scopes:
            system/AppealableIssues.read: Appealable issues info
            system/appeals.read: Appeals info