openapi: 3.0.0
info:
  title: Pharmacy API
  description: API reference for pharmacies to integrate with PHIL.
  version: 1.0.0
tags:
  - name: Partner APIs
    description: Your APIs.
  - name: Request and Response Data
    description: Details on request and response data.
security:
  - ApiKeyAuth: []
  - BearerTokenAuth: []
paths:
  /v1/transfer:
    post:
      operationId: rx-transfer
      summary: Prescription Transfer
      tags:
        - Partner APIs
      description: >-
        PHIL will perform a prescription transfer request to a partner pharmacy
        to transfer ownership of a prescription. This endpoint specifies the
        request we will send and the response that we expect to get back.
      requestBody:
        $ref: '#/components/requestBodies/TransferRequest'
      responses:
        '200':
          $ref: '#/components/responses/TransferResponse'
        '400':
          $ref: '#/components/responses/TransferResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        The API key must be included in the Authorization header with the prefix
        'philKey'. For example: `Authorization: philKey YOUR_API_KEY`.
    BearerTokenAuth:
      type: http
      scheme: bearer
      description: >-
        Token must be included in the Authorization header with the prefix
        'Bearer'. For example: `Authorization: Bearer <token>`.
  requestBodies:
    TransferRequest:
      description: A JSON object containing transfer request information
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransferRequest'
          examples:
            Transfer Request:
              $ref: '#/components/examples/TransferRequest'
  responses:
    TransferResponse:
      description: Partner has received request or completed transfer.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransferResponse'
          examples:
            Transfer Request Received:
              $ref: '#/components/examples/TransferReceived'
            Transfer Request Confirmed:
              $ref: '#/components/examples/TransferConfirmed'
            Missing Info Transfer Error:
              $ref: '#/components/examples/MissingInfoTransferError'
            Invalid Info Transfer Error:
              $ref: '#/components/examples/InvalidInfoTransferError'
            Duplicate Request Transfer Error:
              $ref: '#/components/examples/DuplicateRequestTransferError'
            Rx Expired Transfer Error:
              $ref: '#/components/examples/RxExpiredTransferError'
            Spec Mismatch Transfer Error:
              $ref: '#/components/examples/SpecMismatchTransferError'
            Other Transfer Error:
              $ref: '#/components/examples/OtherTransferError'
  examples:
    TransferRequest:
      value:
        metadata:
          requestID: 6a742tg3aof9f94t35270
          requestTimestamp: '2024-09-11T12:12:00Z'
          patientReferenceID: 9as1tg3aofr5ata5cs84
        patient:
          name:
            firstName: John
            middleName: null
            lastName: Doe
            prefix: null
            suffix: Jr.
          dateOfBirth: '1992-03-20'
          gender: M
          address:
            addressLine1: 410 Terry Ave N
            addressLine2: null
            city: Seattle
            state: WA
            postalCode: '74729'
            countryCode: US
          email: patient@example.com
          contactInfo:
            countryCode: '+1'
            phoneNumber: '3231234532'
          allergyDetails:
            allergiesDescriptor: KNOWN_ALLERGIES_INCLUDED
            allergies:
              - Peanuts
              - soybeans
              - crustacean shellfish
        prescriber:
          dea: F91234563
          npi: '0987654321'
          name:
            firstName: Dorothy
            middleName: Andrews
            lastName: Stevens
            prefix: Dr.
            suffix: null
          address:
            addressLine1: 5372 W Common St
            addressLine2: Ste 210
            city: Seattle
            state: WA
            postalCode: '74729'
            countryCode: US
          faxNumber: '7732229999'
          email: doctor@example.com
          contactInfo: null
        prescription:
          rxNumber: rx1234
          prescribedNDC: '82667090002'
          dispensedNDC: null
          medicationName: TYRVAYA® (VARENICLINE SOLUTION) NASAL SPRAY 0.03 MG
          drugForm: Nasal spray
          drugStrength: 0.03 MG
          daysSupply: 30
          dawCode: 1
          icdCode: null
          sig: TAKE 1 TABLET DAILY|TOME 1 TABLETA AL DIA
          faxImageURL: null
          quantityWritten: 8.4
          quantityDispensed: 8.4
          refillsAuthorized: 5
          refillsRemaining: 3
          canSubstitute: false
          firstFilledDate: null
          lastFilledDate: null
          writtenDate: '2024-09-11T12:00:00Z'
          expirationDate: '2025-09-11T12:00:00Z'
        sendingPharmacy:
          dea: 1M34URHXA
          npi: '0987654321'
          name: PhilRx, LLC
          address:
            addressLine1: 1234 Common St
            addressLine2: null
            city: Scottsdale
            state: AZ
            postalCode: '12345'
            countryCode: US
          pharmacist:
            firstName: Kyle
            middleName: null
            lastName: Abrams
            prefix: null
            suffix: null
          email: phil-user@phil.us
          contactInfo:
            countryCode: '+1'
            phoneNumber: '3433548364'
        receivingPharmacy:
          npi: '1234567890'
          name: ABC Pharmacy
          dea: CW1184915
          address:
            addressLine1: 123 Turn st
            addressLine2: null
            city: Atlanta
            state: GA
            postalCode: '12346'
            countryCode: US
          pharmacist:
            firstName: Georgina
            middleName: null
            lastName: Kade
            prefix: null
            suffix: null
          email: partner-user@partner.com
          contactInfo:
            countryCode: '+1'
            phoneNumber: '4347231846'
        primaryInsurance:
          planName: 0600CASHPAY
          cardHolderID: '44444444'
          cardHolderName:
            firstName: John
            middleName: null
            lastName: Doe
            prefix: null
            suffix: Jr.
          groupNumber: GROUP1234332
          bin: '600428'
          pcn: '06000001'
          personCode: null
        secondaryInsurance: null
    TransferConfirmed:
      description: >-
        This is an synchronous response indicating that the request was fully
        processed and transferred. This can be returned immediately as response
        for the transfer request or later on via the callback API.
      value:
        requestID: 6a742tg3aof9f94t35270
        metadata:
          referenceID: a83sad719545352gsv721
          responseType: CONFIRMED
          responseID: 32803hfas13dth82a4712
          responseTimestamp: '2024-09-11T13:55:00Z'
        prescription:
          rxNumber: rx1234
          prescribedNDC: '82667090002'
          dispensedNDC: null
          medicationName: TYRVAYA® (VARENICLINE SOLUTION) NASAL SPRAY 0.03 MG
          drugForm: EA
          drugStrength: 0.03 MG
          daysSupply: 30
          dawCode: 1
          icdCode: null
          sig: TAKE 1 TABLET DAILY|TOME 1 TABLETA AL DIA
          faxImageURL: null
          quantityWritten: 8.4
          quantityDispensed: 8.4
          refillsAuthorized: 5
          refillsRemaining: 3
          canSubstitute: false
          firstFilledDate: null
          lastFilledDate: null
          writtenDate: '2024-09-11T12:00:00Z'
          expirationDate: '2025-09-11T12:00:00Z'
    TransferReceived:
      description: >-
        This is an ansynchronous response indicating that the transfer request
        was received but not fully processed and transferred. A callback to
        confirm that the transfer request has been fully processed is expected.
      value:
        requestID: 6a742tg3aof9f94t35270
        metadata:
          referenceID: a83sad719545352gsv721
          responseType: RECEIVED
          responseID: ga1t6291sg6310374gs73
          responseTimestamp: '2024-09-11T12:26:00Z'
    InvalidInfoTransferError:
      description: >-
        This is an ansynchronous response indicating that the transfer request
        was could not be processed.
      value:
        requestID: 6a742tg3aof9f94t35270
        metadata:
          referenceID: a83sad719545352gsv721
          responseType: ERROR
          responseID: ga1t6291sg6310374gs73
          responseTimestamp: '2024-09-11T12:26:00Z'
        error:
          type: INVALID_INFO
          description: quantityDispensed amount exceeds the refillsRemaining
    DuplicateRequestTransferError:
      description: >-
        This is an ansynchronous response indicating that the transfer request
        was could not be processed.
      value:
        requestID: 6a742tg3aof9f94t35270
        metadata:
          referenceID: a83sad719545352gsv721
          responseType: ERROR
          responseID: ga1t6291sg6310374gs73
          responseTimestamp: '2024-09-11T12:26:00Z'
        error:
          type: DUPLICATE_REQUEST
          description: prescription already exists
    RxExpiredTransferError:
      description: >-
        This is an ansynchronous response indicating that the transfer request
        was could not be processed.
      value:
        requestID: 6a742tg3aof9f94t35270
        metadata:
          referenceID: a83sad719545352gsv721
          responseType: ERROR
          responseID: ga1t6291sg6310374gs73
          responseTimestamp: '2024-09-11T12:26:00Z'
        error:
          type: RX_EXPIRED
          description: prescription already expired
    SpecMismatchTransferError:
      description: >-
        This is an ansynchronous response indicating that the transfer request
        was could not be processed.
      value:
        requestID: 6a742tg3aof9f94t35270
        metadata:
          referenceID: a83sad719545352gsv721
          responseType: ERROR
          responseID: ga1t6291sg6310374gs73
          responseTimestamp: '2024-09-11T12:26:00Z'
        error:
          type: SPEC_MISMATCH
          description: prescriber does not match the expected specs
    MissingInfoTransferError:
      description: >-
        This is an ansynchronous response indicating that the transfer request
        was could not be processed.
      value:
        requestID: 6a742tg3aof9f94t35270
        metadata:
          referenceID: a83sad719545352gsv721
          responseType: ERROR
          responseID: ga1t6291sg6310374gs73
          responseTimestamp: '2024-09-11T12:26:00Z'
        error:
          type: MISSING_INFO
          description: prescription daysSupply is required
    OtherTransferError:
      description: >-
        This is an ansynchronous response indicating that the transfer request
        was could not be processed.
      value:
        requestID: 6a742tg3aof9f94t35270
        metadata:
          referenceID: a83sad719545352gsv721
          responseType: ERROR
          responseID: ga1t6291sg6310374gs73
          responseTimestamp: '2024-09-11T12:26:00Z'
        error:
          type: OTHER
          description: could not process transfer request
  schemas:
    TransferRequest:
      type: object
      x-tags:
        - Request and Response Data
      properties:
        metadata:
          $ref: '#/components/schemas/RequestMetadata'
        patient:
          $ref: '#/components/schemas/Patient'
        prescriber:
          $ref: '#/components/schemas/Prescriber'
        prescription:
          $ref: '#/components/schemas/Prescription'
        sendingPharmacy:
          $ref: '#/components/schemas/Pharmacy'
        receivingPharmacy:
          $ref: '#/components/schemas/Pharmacy'
        primaryInsurance:
          $ref: '#/components/schemas/Insurance'
        secondaryInsurance:
          $ref: '#/components/schemas/Insurance'
      required:
        - metadata
        - patient
        - prescriber
        - prescription
        - sendingPharmacy
        - receivingPharmacy
        - primaryInsurance
        - secondaryInsurance
    TransferResponse:
      type: object
      x-tags:
        - Request and Response Data
      properties:
        requestID:
          type: string
          description: the requestID from the request metadata
        metadata:
          allOf:
            - type: object
              properties:
                responseType:
                  $ref: '#/components/schemas/ResponseType'
            - $ref: '#/components/schemas/ResponseMetadata'
        error:
          $ref: '#/components/schemas/Error'
        prescription:
          $ref: '#/components/schemas/Prescription'
      required:
        - requestID
        - metadata
    Address:
      type: object
      properties:
        addressLine1:
          type: string
          minLength: 1
          maxLength: 40
        addressLine2:
          description: Use only when needed and AddressLine1 has been used
          type: string
          nullable: true
          minLength: 1
          maxLength: 40
        city:
          type: string
          minLength: 1
          maxLength: 35
        state:
          type: string
          description: 2-letter code for the state
          minLength: 2
          maxLength: 2
          example: WA
        postalCode:
          type: string
          description: 5-digit or 9-digit postalCode
          example:
            - 74729
            - 74729-0140
        countryCode:
          type: string
          minLength: 1
          maxLength: 2
      required:
        - addressLine1
        - addressLine2
        - city
        - state
        - postalCode
        - countryCode
    AllergyDetails:
      type: object
      properties:
        allergiesDescriptor:
          type: string
          enum:
            - KNOWN_ALLERGIES_INCLUDED
            - NO_KNOWN_ALLERGIES
            - NOT_AVAILABLE
        allergies:
          type: array
          description: a list of allergy descriptions
          minItems: 0
          items:
            type: string
      required:
        - allergiesDescriptor
        - allergies
    ContactInfo:
      type: object
      nullable: true
      properties:
        countryCode:
          type: string
          description: phone number coutry code
          example: '+1'
        phoneNumber:
          type: string
          description: 10-digit phone number
          pattern: ^\d{10}$
          example: '3231234532'
      required:
        - countryCode
        - phoneNumber
    Error:
      type: object
      description: required if response type is an error
      properties:
        type:
          $ref: '#/components/schemas/ErrorType'
        description:
          type: string
          example: quantityDispensed amount exceeds the refillsRemaining
    ErrorType:
      type: string
      enum:
        - MISSING_INFO
        - INVALID_INFO
        - RX_EXPIRED
        - SPEC_MISMATCH
        - DUPLICATE_REQUEST
        - OTHER
      example: INVALID_INFO
      description: |
        Specifies the error types:
          * MISSING_INFO - missing required field
          * INVALID_INFO - the data does not match the expected value (e.g. no refills remaining, etc.)
          * RX_EXPIRED - the prescription is expired
          * SPEC_MISMATCH - the data fields does not match the expected specifications
          * DUPLICATE_REQUEST - a request has already been submitted
          * OTHER 
    Insurance:
      type: object
      nullable: true
      properties:
        planName:
          type: string
          description: Patient insurance plan name
        cardHolderID:
          type: string
          description: Patient insurance ID number
          minLength: 1
          maxLength: 35
        cardHolderName:
          $ref: '#/components/schemas/Name'
        groupNumber:
          type: string
          description: Patient insurance group number
          nullable: true
        bin:
          nullable: true
          description: Patient insurance bin
          type: string
        pcn:
          nullable: true
          description: Patient insurance PCN
          type: string
        personCode:
          description: Patient insurance person code
          type: string
          pattern: ^\d{3}$
          nullable: true
      required:
        - planName
        - cardHolderID
        - cardHolderName
        - groupNumber
        - bin
        - pcn
        - personCode
    RequestMetadata:
      type: object
      additionalProperties: true
      description: additional information about the request and response data
      properties:
        requestID:
          type: string
          description: unique identifier for an API request
        patientReferenceID:
          type: string
          description: unique identifier for our patient profile
        requestTimestamp:
          type: string
          format: date-time
          description: timestamp for the API request.
        retryCount:
          type: integer
          description: number of times that this request has been retried
      required:
        - requestID
        - patientReferenceID
        - requestTimestamp
    ResponseMetadata:
      type: object
      additionalProperties: true
      description: additional information about the request and response data
      properties:
        referenceID:
          type: string
          description: unique identifier for the prescription.
        responseID:
          type: string
          description: unique identifier for an API response.
        responseTimestamp:
          type: string
          format: date-time
          description: timestamp for the API response.
      required:
        - responseType
        - referenceID
        - responseID
        - responseTimestamp
    Name:
      type: object
      properties:
        lastName:
          type: string
          minLength: 1
          maxLength: 35
        firstName:
          type: string
          minLength: 1
          maxLength: 35
        middleName:
          type: string
          minLength: 1
          maxLength: 35
          nullable: true
        prefix:
          type: string
          minLength: 1
          maxLength: 10
          nullable: true
        suffix:
          type: string
          minLength: 1
          maxLength: 10
          nullable: true
      required:
        - firstName
        - lastName
        - middleName
        - prefix
        - suffix
    Patient:
      type: object
      description: Patient details
      properties:
        name:
          $ref: '#/components/schemas/Name'
        dateOfBirth:
          type: string
          format: date
          example: '1992-03-20'
        gender:
          type: string
          description: |
            Code identifying the sex of the individual.:
              * M - Male
              * F - Female
              * U - Not specified or unknown
          enum:
            - M
            - F
            - U
        address:
          $ref: '#/components/schemas/Address'
        email:
          nullable: true
          type: string
          format: email
          example: patient@example.com
        contactInfo:
          $ref: '#/components/schemas/ContactInfo'
        allergyDetails:
          $ref: '#/components/schemas/AllergyDetails'
      required:
        - name
        - dateOfBirth
        - gender
        - address
        - email
        - contactInfo
        - allergyDetails
    Pharmacy:
      type: object
      description: >-
        pharamcy details used for sending pharmacy (PHIL) or receiving pharmacy
        (partner pharmacies)
      properties:
        dea:
          type: string
          description: DEA registration number
          nullable: true
        npi:
          type: string
          description: a 10-digit identifier for the pharmacy
        name:
          type: string
          description: pharamcy name
        pharmacist:
          $ref: '#/components/schemas/Name'
        address:
          $ref: '#/components/schemas/Address'
        email:
          type: string
          format: email
          example: pharmacy@example.com
        contactInfo:
          $ref: '#/components/schemas/ContactInfo'
      required:
        - dea
        - npi
        - name
        - pharmacist
        - address
        - email
        - contactInfo
    Prescriber:
      type: object
      description: >-
        a licensed healthcare professional who authorized the prescription for
        the patient
      properties:
        dea:
          nullable: true
          type: string
          description: DEA registration number
        npi:
          type: string
          description: a 10-digit identifier for the pharmacy
        name:
          $ref: '#/components/schemas/Name'
        address:
          $ref: '#/components/schemas/Address'
        faxNumber:
          type: string
          description: prescriber fax number
          nullable: true
        email:
          nullable: true
          type: string
          format: email
          example: doctor@example.com
        contactInfo:
          $ref: '#/components/schemas/ContactInfo'
      required:
        - dea
        - npi
        - name
        - address
        - faxNumber
        - email
        - contactInfo
    Prescription:
      type: object
      properties:
        rxNumber:
          description: a unique number that identifies the prescription
          type: string
        prescribedNDC:
          description: a uniqie 11-digit code that identifies the prescribed medication
          type: string
          minLength: 1
          maxLength: 11
          example: '47335050696'
        dispensedNDC:
          description: >-
            a uniqie 11-digit code that identifies the medication to be
            dispensed. If the same as prescribedNDC, value will be null. 
          type: string
          minLength: 1
          maxLength: 11
          nullable: true
        medicationName:
          description: prescribed medication name
          type: string
        drugForm:
          description: prescribed medication form (capsules, tablets, ointment, etc.)
          type: string
        drugStrength:
          description: prescribed medication strength
          type: string
          example: 0.03 MG
        daysSupply:
          description: prescribed days of supply
          type: integer
          example: 30
        dawCode:
          description: dispense as written
          type: integer
          minimum: 0
          maximum: 9
          nullable: true
        sig:
          description: >-
            prescription sig to specify how much, how often, and how to take a
            medication
          type: string
        faxImageURL:
          description: transfer fax image URL
          type: string
          nullable: true
        quantityWritten:
          description: prescription medication quantity written
          type: number
          example: 8.4
        quantityDispensed:
          description: >-
            Prescription quantity that we want dispensed for each order (may be
            different than what's written)
          type: number
        refillsAuthorized:
          description: >-
            the number of prescription refills originally written, including
            first fill
          type: integer
        refillsRemaining:
          description: the number of subsequent refills remaining on the prescription
          type: integer
        writtenDate:
          description: Prescription written date
          type: string
          format: date-time
          example: '2024-09-11T12:00:00.000Z'
        firstFilledDate:
          description: prescription first filled date
          type: string
          format: date-time
          nullable: true
        lastFilledDate:
          description: prescription last filled date
          type: string
          format: date-time
          nullable: true
        expirationDate:
          description: date the prescription expires
          type: string
          format: date-time
          example: '2025-09-15T12:00:00.000Z'
        canSubstitute:
          description: whether or not prescription can be substituted for another
          type: boolean
        icdCode:
          type: string
          description: a standardized code assigned to diagnose medical conditions
          nullable: true
      required:
        - rxNumber
        - prescribedNDC
        - dispensedNDC
        - medicationName
        - drugForm
        - drugStrength
        - daysSupply
        - dawCode
        - icdCode
        - sig
        - faxImageURL
        - quantityWritten
        - quantityDispensed
        - refillsAuthorized
        - refillsRemaining
        - writtenDate
        - firstFilledDate
        - lastFilledDate
        - expirationDate
        - canSubstitute
    ResponseType:
      type: string
      enum:
        - RECEIVED
        - CONFIRMED
        - ERROR
      description: |
        Specifies the response types:
          * RECEIVED - the request has been received, but not yet processed. Requires a follow-up callback to confirm that the request has been completed. For more information, see [Callbacks](/guides/callbacks).
          * CONFIRMED - the request is completed and has been fully processed.
          * ERROR - the request to was unsuccessful.
