openapi: 3.0.3
info:
  title: Garner Health Facilities Provider Annotations API
  version: v1.11.0
  license:
    name: Commercial
    url: https://getgarner.com
  description: "Garner's APIs power its core provider recommendation experience. These recommendations are based on over 60 billion\nanonymized health insurance claims that paint a clear picture of a patient's journey through the healthcare system. \n\nUsing these data, Garner evaluates whether physicians practice evidence-based medicine as defined by major,\nrespected healthcare journals. Garner has designed over 550 clinical and financial metrics that look closely\nat every decision a physician makes rather than relying on standard industry episode groupers. This results in\nrankings that are much more transparent and trustworthy and enable better-informed decisions for patients,\nphysicians, and payers.\n\n# Authentication: \n  \n## OAuth2.0\n\n*If you were provided a JWT at account setup rather than an API client id and client secret, please refer to instructions for [legacy token authentication.](#section/Authentication:/Legacy-token)*\n\nGarner APIs authenticate with OAuth 2.0 access tokens. You will be provided an API client ID and API client secret during account setup. \nThe client ID and client secret can be exchanged for an access token which in turn authenticates your app when making calls to Garner's APIs. \n\nTo obtain an access token, make a request to the `POST oauth2/token/` endpoint. In the request body, include the `client_id`, `client_secret`, \nand `grant_type=client_credentials`. This response will contain an `access_token`, the `token_type` which will always be \"Bearer\", \nand `expires_in` which is the lifetime in seconds of the token. \n\nThe access token can be used to authenticate with Garner's APIs. When making a request, provide the access token as a \nbearer token in the `Authorization` header. \n\nFor example, \n\n**JavaScript**\n```js\n/* Get the token */\nconst { access_token, token_type, expires_in } = await fetch('https://api.getgarner.com/oauth2/token', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n  body: new URLSearchParams({\n    grant_type: 'client_credentials',\n    client_id: '<YOUR_API_CLIENT_ID_HERE>',\n    client_secret: '<YOUR_API_CLIENT_SECRET_HERE>',\n  }),\n}).then(r => r.json());\n\n\n/* Use the token */\nconst { providers } = fetch(\n  'https://api.getgarner.com/providers',\n  {\n    method: 'GET',\n    headers: {'Authorization': `Bearer ${<YOUR_ACCESS_TOKEN_HERE>}`},\n    query: ...\n  },\n).then(response => response.json());\n\n``` \n**cURL**\n```sh\n# Get the token\ncurl --location 'https://api.garner.health/oauth2/token' \\\n--header 'Content-Type: application/x-www-form-urlencoded' \\\n--data-urlencode 'grant_type=client_credentials' \\\n--data-urlencode 'client_id=<YOUR_API_CLIENT_ID_HERE' \\\n--data-urlencode 'client_secret=<YOUR_API_CLIENT_SECRET_HERE>'\n\n# Use the token\ncurl -G https://api.getgarner.com/providers -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN_HERE>'\n```\n\n\n### Managing the access token\nThe access token will only be valid for 15 minutes. We recommend caching the token in your application so that it can be reused up to its expiration. This can be managed by the app programmatically by implementing a `GarnerTokenClient` class like the following:\n```typescript\nclass GarnerTokenClient {\n  /** Cached access token */\n  private currentToken: string | undefined;\n  /** Time at which the cached token expires */\n  private expirationTime: number | undefined;\n\n  /** \n  *  Fetches a new access token from the `POST /oauth2/token` endpoint,\n  *  then caches the token and its expiration time.\n  *  Returns a promise that resolves to the newly fetched access token\n  */\n  private async fetchNewToken(): Promise<string> {\n    const currentTime = Date.now();\n    const { access_token: accessToken, expires_in: expiresIn } = await fetch('https://api.getgarner.com/oauth2/token', {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },\n      body: new URLSearchParams({\n        grant_type: 'client_credentials',\n        client_id: '<YOUR_API_CLIENT_ID_HERE>',\n        client_secret: '<YOUR_API_CLIENT_SECRET_HERE>',\n      }),\n    }).then(r => r.json());\n    // Cache the access token\n    this.currentToken = accessToken;\n    // Set the expiration time as the current time plus the number of ms until the token expires. Subtract a 15 second buffer to account for lag.\n    this.expirationTime = (currentTime + expiresIn * 1000) - 15000; \n    return accessToken;\n  }\n\n  /** \n  *  Returns the cached access token if it is valid. \n  *  Otherwise, fetches a new token.\n  */\n  async getToken(): Promise<string> {\n    if (this.currentToken && this.expirationTime && Date.now() < this.expirationTime) {\n      return this.currentToken;\n    }\n    return await this.fetchNewToken();\n  }\n}\n```\n\nThen when making a request to Garner's APIs you can use the response of `getToken()` from an instance of the `GarnerTokenClient` class as your token.\n\nFor example, \n\n```typescript\nconst garnerTokenClient = new GarnerTokenClient();\n\nfetch('https://api.getgarner.com/providers',\n  {\n    method: 'GET',\n    headers: {'Authorization': `Bearer ${await garnerTokenClient.getToken()}`},\n    query: ...\n  },\n);\n\n```\n## Legacy token\n\n*If you were provided an API client id and client secret at account setup rather than a token, please refer to instructions for [OAuth2.0 authentication.](#section/Authentication:/OAuth2.0)*\n\nAuthenticating is done with an JSON Web Token (JWT) provided as a `Bearer` token to the `Authorization` header.\nYou will have received a token during account setup.\n\nFor example, \n```sh\ncurl -G https://api.getgarner.com -H 'Authorization: Bearer <YOUR_API_TOKEN_HERE>'\n```\n"
servers:
- url: https://api.getgarner.com
security:
- ApiToken: []
tags:
- name: Provider Annotations
paths:
  /provider-annotations/{provider_id}:
    parameters:
    - $ref: '#/components/parameters/acceptVersion'
    post:
      operationId: CreateProviderAnnotations
      summary: Annotate a Provider record for accuracy
      parameters:
      - name: provider_id
        in: path
        required: true
        schema:
          type: string
        description: The Garner ID for the provider.
        example: p.f3ac4f1a01275ca68e6c932ad4722491
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAnnotation.RequestBody'
      responses:
        '200':
          description: Created annotations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAnnotation.ResponseBody'
        '422':
          description: Annotation field not supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
      tags:
      - Provider Annotations
components:
  schemas:
    CreateAnnotation.ResponseBody:
      type: object
      properties:
        count:
          type: number
          description: Number of annotations created
          example: 1
      required:
      - count
      additionalProperties: false
      description: Returns number of annotations created
    CreateAnnotationParams:
      type: object
      properties:
        locationId:
          type: string
          description: id of the provider's location
          example: c52305b90e2a5ce08ce6f0a621acd22f
        annotations:
          type: array
          items:
            $ref: '#/components/schemas/Annotation'
          description: List of annotations for the provider record
          example:
          - field: phoneNumber
            isCorrect: false
            value: 2121126544
            correctedValue: 2121126542
      required:
      - locationId
      - annotations
      additionalProperties: false
    AnnotationField:
      type: string
      enum:
      - specialty
      - phoneNumber
      - firstName
      - lastName
      - locationName
      - gender
      - credentials
      - faxNumber
      - street1
      - street2
      - city
      - state
      - zipCode
    ServiceError:
      type: object
      properties:
        requestId:
          type: number
        message:
          type: string
        data:
          type: object
          additionalProperties: true
      required:
      - message
      additionalProperties: false
    Annotation:
      type: object
      properties:
        field:
          $ref: '#/components/schemas/AnnotationField'
          description: key of the field to be annotated
          example: phoneNumber
        value:
          anyOf:
          - type: string
          - type: object
            additionalProperties:
              type: string
          description: value of the field that is being annotated. It can either be a string or an object.
          example: 2121126544
        isCorrect:
          type: boolean
          description: indicates whether the current value is correct or incorrect
          example: false
        correctedValue:
          anyOf:
          - type: string
          - type: object
            additionalProperties:
              type: string
          description: Corrected value of the annotated field
          example: 2121126542
      required:
      - field
      - value
      - isCorrect
      additionalProperties: false
    CreateAnnotation.RequestBody:
      $ref: '#/components/schemas/CreateAnnotationParams'
  parameters:
    acceptVersion:
      name: Accept-Version
      in: header
      required: true
      schema:
        type: integer
        enum:
        - 1
      description: The API major version.
  securitySchemes:
    ApiToken:
      type: http
      scheme: bearer
      bearerFormat: API_TOKEN