1: Finding the pharmacy itself

Overview

The getRetailPharmacies endpoint retrieves a list of retail pharmacies based on location criteria (zipcode or city/state combination).

Query Parameters

The endpoint accepts the following query parameters:

Parameter	Type	Required	Description
`qType`	String	Yes	Determines the search type. Must be either `'city'` or any other value (defaults to zipcode search)
`zipcode`	String	Conditional*	Required when `qType` is not `'city'`. The zipcode to search for pharmacies
`city`	String	Conditional*	Required when `qType` is `'city'`. The city name to search for pharmacies (case-insensitive)
`state`	String	Conditional*	Required when `qType` is `'city'`. The state abbreviation or name to search for pharmacies

Note: Either zipcode OR (city + state) must be provided based on the qType parameter.

Request Examples

Search by Zipcode

GET /pharmacy/actions/getRetailPharmacies?qType=zipcode&zipcode=10001

GET /pharmacy/actions/getRetailPharmacies?zipcode=10001

Search by City and State

GET /pharmacy/actions/getRetailPharmacies?qType=city&city=New York&state=NY

Response Format

Success Response

Status Code: 200 OK

Response Body:

[
  {
    "id": "phr::<guid>",
    "name": "CVS Pharmacy",
    "pharmacyAddress": {
      "address1": "123 Main St",
      "address2": "Suite 100",
      "city": "New York",
      "state": "NY",
      "zipcode": "10001",
      "phone": "212-555-1234"
    },
    "pharmacyType": "Retail",
    "status": "active",
    "createdAt": "2023-01-15T10:30:00.000Z",
    "updatedAt": "2023-01-15T10:30:00.000Z"
  },
  {
    "id": "phr::<guid>",
    "name": "Walgreens",
    "pharmacyAddress": {
      "address1": "456 Broadway",
      "address2": null,
      "city": "New York",
      "state": "NY",
      "zipcode": "10001",
      "phone": "212-555-5678"
    },
    "pharmacyType": "Retail",
    "status": "active",
    "createdAt": "2023-01-16T14:20:00.000Z",
    "updatedAt": "2023-01-16T14:20:00.000Z"
  }
]

Response Fields

Field	Type	Description
`id`	String	Unique identifier for the retail pharmacy
`name`	String	Name of the pharmacy
`pharmacyAddress`	Object	Address information object
`pharmacyAddress.address1`	String	Primary street address
`pharmacyAddress.address2`	String \| null	Secondary address (suite, unit, etc.)
`pharmacyAddress.city`	String	City name
`pharmacyAddress.state`	String	State abbreviation or name
`pharmacyAddress.zipcode`	String	ZIP/postal code
`pharmacyAddress.phone`	String	Phone number
`pharmacyType`	String	Type of pharmacy (e.g., "Retail", "Specialty")
`status`	String	Status of the pharmacy (e.g., "active")
`createdAt`	String (ISO 8601)	Timestamp when the record was created
`updatedAt`	String (ISO 8601)	Timestamp when the record was last updated

Error Responses

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Authentication required"
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An error occurred while processing your request"
}

Notes

The search is case-insensitive for city names
The endpoint returns an empty array [] if no pharmacies match the search criteria
All pharmacies returned have pharmacyType: "Retail" by default
The status field defaults to "active" for active pharmacies

2: Setting Patient's Retail Pharmacy

Overview

The retailPharmacy field allows you to associate a patient with their preferred retail pharmacy. This information is used for prescription fulfillment and other pharmacy-related operations.

Endpoints for Setting Retail Pharmacy

There are two main endpoints that allow setting the retailPharmacy field on a patient:

Request Body:

{
  "retailPharmacy": "phr::<guid>"
}

The retailPharmacy field accepts a retail pharmacy ID (string). You can obtain pharmacy IDs by searching for pharmacies using the Get Retail Pharmacies endpoint (see below).

Example Request:

PUT /ias/patients/patient_xyz789
Content-Type: application/json
Authorization: Bearer <affiliate_token>

{
  "retailPharmacy": "phr::<guid>"
}

Success Response (200 OK):

{
  "id": "patient_xyz789",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "retailPharmacy": {
    "id": "phr::<guid>",
    "name": "CVS Pharmacy",
    "pharmacyAddress": {
      "address1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "zipcode": "10001",
      "phone": "212-555-1234"
    },
    "pharmacyType": "Retail",
    "status": "active"
  },
}