NAV
elixir

Introduction

Welcome to the ScriptDrop Omni API.

Authentication

Authentication is performed using an API key and secret and sent using the Authorization header with the Basic realm.

To authorize, use this code:

api_key = "pk_myapikey1234"
api_secret = "tesk_myapisecret1234"

encoded_authorization = Base.url_encode64("#{api_key}:#{api_secret}")

authorization_header = "Basic #{encoded_authorization}"

ScriptDrop uses API keys to allow access to the API. Please contact our support team for API keys.

ScriptDrop expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Basic encoded_authorization

Omni V2

Create a Request

url = "https://api.scriptdrop.co/omni/v2/requests"

headers = [
  {"Authorization", "Basic encoded_authorization"},
  {"Content-type", "application/json"}
]

request_params = %{
  "identifier" => "WAHTP",
  "external_reference_number" => "238947",
  "pharmacy" => %{
      "ncpdp" => "1234567"
  },
  "support_instructions" => "Pharmacy says Rx will be ready for pickup by 4pm today",
  "temperature_control" => "refrigerated",
  "delivery_fee" => 4.99,
  "dropoff" => %{
    "name" => "John Doe",
    "phone_number" => "1115550000",
    "address" => %{
      "street1" => "1230 Street",
      "street2" => "Apt 3",
      "city" => "Columbus",
      "state" => "OH",
      "zipcode" => "43210"
    },
    "leave_at_door_consent" => false,
    "signature_required" => true,
    "courier_delivery_notes" => "Please knock loudly upon arrival, patient is hard of hearing"
  },
  "patient" => %{
    "first_name" => "John",
    "last_name" => "Doe",
    "gender" => "male",
    "date_of_birth" => "1960-02-01"
  },
  "prescription_items" => [
    %{
      "medication_name" => "Sulfonylureas",
      "ndc" => "00169413013",
      "prescriber_npi" => "1288877367",
      "number" => "0010140712",
      "days_supply" => 30,
      "fill_quantity" => 30,
      "fill_number" => 1,
      "date_of_service" => "2025-01-29",
      "patient_responsibility" => 5
    },
    %{
      "medication_name" => "Albuterol",
      "ndc" => "00137893013",
      "prescriber_npi" => "1288877367",
      "number" => "0098790712",
      "days_supply" => 10,
      "fill_quantity" => 5,
      "fill_number" => 2,
      "date_of_service" => "2025-01-29",
      "patient_responsibility" => 7.49
    }
  ],
  "other_items" => [
      %{
        "description" => "OTC eye drops",
        "upc" => "123456789905",
        "sku" => "ABCD0123-4567",
        "quantity" => 1,
        "patient_responsibility" => 7.95
      }
  ],
  "payment_contact" => %{
    "mobile_phone_number" => "1116660000",
    "email" => "john.doe@someemail.com"
   }
}

HTTPoison.start()
HTTPoison.post(url, Jason.encode!(omni_request_params), headers)

The above command returns JSON structured like this:

{
  "request": {
    "id": "1234",
    "external_reference_number": "238947",
    "courier_company": null,
    "status": "request_received",
    "status_detail": null,
    "creation_occurred_at": "2025-01-30T015:00:00Z",
    "picked_up": false,
    "pickup_occurred_at": null,
    "delivery": null,
    "cancelled": false,
    "cancellation_occurred_at": null,
    "delivery_eta": "2025-01-31T10:00:00Z - 2025-01-31T14:00:00Z"
  }
}

Sample Dropoff with Full Address:

{
    "name" => "John Doe",
    "phone_number" => "1115550000",
    "address" => %{
      "street1" => "1230 Street",
      "street2" => "Apt 3",
      "city" => "Columbus",
      "state" => "OH",
      "zipcode" => "43210"
    },
    "leave_at_door_consent" => false,
    "signature_required" => true,
    "courier_delivery_notes" => "Please knock loudly upon arrival, patient is hard of hearing"
  }

Sample Dropoff with Google Place ID:

{
    "name" => "John Doe",
    "phone_number" => "1115550000",
    "address" => %{
      "google_place_id" => "ChIJIYo9-12OOIgRR9WiX1nG0V0"
    },
    "leave_at_door_consent" => false,
    "signature_required" => true,
    "courier_delivery_notes" => "Please knock loudly upon arrival, patient is hard of hearing"
  }

This endpoint creates a new Omni request.

HTTP Request

POST https://api.scriptdrop.co/omni/v2/requests

Body Parameters

Name Type Required Length Description Example
identifier String true Unique program id provided by ScriptDrop. program0
external_reference_number String true max: 255 Reference number used to identify the request from an external system. 123456
pharmacy Pharmacy true Pharmacy details.
support_instructions String false max: 280 Instructions visible only to ScriptDrop support staff to assist with delivery Prescription will be ready for pickup by 2pm today
temperature_control String false Defaults to none. Indicates whether this item requires temperature control. Can be one of none, refrigerated, or frozen. none
delivery_fee Decimal false A delivery fee associated with the delivery. Defaults to: 0. The patient will be required to pay this amount prior to receiving the delivery. 4.99
pickup Pickup Required if pickup location is not provided pharmacy. Pickup details.
dropoff Dropoff true Dropoff details.
patient Patient true Patient details.
prescription_items Prescription Item Required if 'other_items' not provided. If prescriptions are being delivered in addition to other items, please provide both item types. Array of prescriptions being delivered.
other_items Other Item Required if 'prescription_items' not provided. If other items are being delivered in addition to prescriptions, please provide both item types. Array of non-prescription items being delivered. Syringes, Ibuprofen etc.
payment_contact PaymentContact Required if there are any fees or copays that must be paid prior to delivery. Information required to collect any fees or copays associated with the request.

Pharmacy Parameters

Name Type Required Length Description Example
ncpdp String true is: 7 Pharmacy NCPDP 7266390

Pickup Parameters

Name Type Required Length Description Example
name String true max: 71 In cases where the pickup location is an individual, this should be the first and last name of the person. Otherwise, enter the name of the pickup location. XYZ Pharmacy
phone_number String true is: 10 Phone number of the pickup individual or location. 4198733289
address Address true Request pickup address.

Dropoff Parameters

Name Type Required Length Description Example
name String true max: 71 The name of the request recipient. In cases where the patient is the recipient, this should be the first and last name of the patient. Jane Doe
phone_number String true is: 10 Phone number for the request recipient. 5139890037
address Address, Google Place Address true Request dropoff address. Can take a full address OR a Google place id.
leave_at_door_consent Boolean true Indicates whether or not the the patient has provided consent for the courier to leave the delivery at the patient’s door in case patient is not home at time of delivery. false
signature_required Boolean Required if leave_at_door_consent is false Indicates whether or not a signature is required for delivery. Defaults to false if leave_at_door_consent is true. true
courier_delivery_notes String false max: 280 Instructions visible to the courier to assist with the delivery’s drop-off. (Gate codes, where to leave the delivery, etc.) Please knock loudly; patient hard of hearing.

Sample Dropoff with Full Address

%{
  "dropoff" => %{
    "name" => "JOHN DOE",
    "phone_number" => "1115550000",
    "address" => %{
      "street1" => "1230 Street",
      "street2" => "Apt 3",
      "city" => "Columbus",
      "state" => "OH",
      "zipcode" => "43210"
    }
    "leave_at_door_consent" => false,
    "signature_required" => true,
    "courier_delivery_notes" => "Please knock loudly patient hard of hearing."
}

Sample Dropoff with Google Place ID

%{
  "dropoff" => %{
    "name" => "JOHN DOE",
    "phone_number" => "1115550000",
    "address" => %{
      "google_place_id" => "ChIJIYo9-12OOIgRR9WiX1nG0V0"
    }
}

Address Parameters

Name Type Required Length Description
street1 String true max: 255 Street
street2 String false max: 255 Street2
city String true max: 255 City
state String true max: 2 Two-letter state abbreviation
zipcode String true is: 5 or is: 9 Zipcode

Alternate Address Parameters (FOR DROPOFF ONLY)

Name Type Required Length Description
google_place_id String true max: 255 A Google place id

Patient Parameters

Name Type Required Length Description
first_name String true max: 30 Patient's first name.
last_name String true max: 40 Patient's. last name
gender String false Patient's gender. Can be one of: male, female, unspecified.
date_of_birth ISO 8601 date string true Patient's date of birth.

Prescription Item Parameters

Name Type Required Length Description Example
ndc String false is: 11 National Drug Code 00169413013
medication_name String true Name of dispensed medication Albuterol
prescriber_npi String false is: 10 Prescriber's NPI 1288877367
number String false max: 255 Rx number 0010140712
days_supply Integer false Days supply. 30
fill_quantity Decimal false Fill quantity. 30
fill_number Integer false Fill number. 1
date_of_service ISO 8601 date string false Date of service for the prescription. Example: "2025-01-28" 2025-01-30
patient_responsibility Decimal false Copay amount due from the patient prior to delivery. Defaults to: 0. The patient will be required to pay this amount prior to receiving the delivery. 5

Other Item Parameters

Name Type Required Length Description Example
description String true max: 255 Description of the item being delivered. OTC eye drops
upc String false is: 12 UPC 123456789905
sku String false SKU ABCD0123-4567
quantity Integer false Quantity being delivered 1
patient_responsibility Decimal false Other amount due from the patient prior to delivery. Defaults to: 0. The patient will be required to pay this amount prior to receiving the delivery. 7.95

Payment Contact Parameters

Name Type Required Length Description Example
mobile_phone_number String true is: 10 Phone number used to communicate links and reminders regarding payment. 5134563737
email String false max: 255 Email used to communicate links and reminders regarding payment. jane.doe@exampleemail.com

200 Response Schema

See the 200 Response Schema under Get a Request.

Error Response

See Errors

Cancel a Request

url = "https://api.scriptdrop.co/omni/v2/requests/1235"

headers = [
  {"Authorization", "Basic encoded_authorization"},
]

HTTPoison.start()
HTTPoison.delete(url, headers)

On success the above command returns no response body

Example error response for attempted cancellation of Omni request with orders in uncancellable status:

{
  "error": {
    "id": "1235",
    "type": "unable_to_cancel",
    "message": "Orders are not in a cancellable status."
  }
}

This endpoint cancels an Omni request and any associated orders that are in a cancellable status.

HTTP Request

DELETE https://api.scriptdrop.co/omni/v2/requests/:id

URL Parameters

Parameter Description
:id The ID of the request to delete

Success Response

HTTP status code 204

Error Response

See Errors

Get a Request

url = "https://api.scriptdrop.co/omni/v2/requests/1236"

headers = [
  {"Authorization", "Basic encoded_authorization"},
  {"Content-type", "application/json"}
]

HTTPoison.start()
HTTPoison.get(url, headers)

JSON returned for a new Omni request:

{
  "request": {
    "id": "1234",
    "external_reference_number": "238947",
    "courier_company": null,
    "status": "request_received",
    "status_detail": null,
    "creation_occurred_at": "2025-01-30T015:00:00Z",
    "picked_up": false,
    "pickup_occurred_at": null,
    "delivery": null,
    "cancelled": false,
    "cancellation_occurred_at": null,
    "delivery_eta": "2025-01-31T10:00:00Z - 2025-01-31T14:00:00Z"
  }
}

JSON returned for an omni request that has been submitted to the courier for pickup:

{
  "request": {
    "id": "1234",
    "external_reference_number": "238947",
    "courier_company": "Roadie",
    "status": "request_in_progress",
    "status_detail": "submitted_to_courier",
    "creation_occurred_at": "2025-01-30T015:00:00Z",
    "picked_up": false,
    "pickup_occurred_at": null,
    "delivery": null,
    "cancelled": false,
    "cancellation_occurred_at": null,
    "delivery_eta": "2025-01-31T10:00:00Z - 2025-01-31T14:00:00Z"
  }
}

JSON returned for an omni request that has been picked up by the courier and is en route to delivery:

{
  "request": {
    "id": "1234",
    "external_reference_number": "238947",
    "courier_company": "Roadie",
    "status": "request_in_progress",
    "status_detail": "picked_up",
    "creation_occurred_at": "2025-01-30T015:00:00Z",
    "picked_up": true,
    "pickup_occurred_at": "2025-01-30T015:40:00Z",
    "delivery": null,
    "cancelled": false,
    "cancellation_occurred_at": null,
    "delivery_eta": "2025-01-31T16:10:00Z"
  }
}

JSON returned for an omni request that has been successfully delivered to the patient with a signature:

{
  "request": {
    "id": "1234",
    "external_reference_number": "238947",
    "courier_company": "Roadie",
    "status": "request_complete",
    "status_detail": null,
    "creation_occurred_at": "2025-01-30T015:00:00Z",
    "picked_up": true,
    "pickup_occurred_at": "2025-01-30T015:30:00Z",
    "delivery": {
      "occurred_at": "2025-01-30T015:50:00Z",
      "signature_url": "https://example.com/238947",
      "photo_url": "https://example.com/238948",
      "signed_by": "John Doe",
      "relationship": "Patient",
      "other_relationship_description": null,
      "recipient_identification": null
    },
    "cancelled": false,
    "cancellation_occurred_at": null,
    "delivery_eta": null
  }
}

JSON returned for an omni request that has failed delivery:

{
  "request": {
    "id": "1234",
    "external_reference_number": "238947",
    "courier_company": "Roadie",
    "status": "request_incomplete",
    "status_detail": "patient_not_home",
    "creation_occurred_at": "2025-01-30T015:00:00Z",
    "picked_up": true,
    "pickup_occurred_at": "2025-01-30T015:30:00Z",
    "delivery": {
      "occurred_at": "2025-01-30T015:50:00Z",
      "failure_reason": "Patient Not Home"
    },
    "cancelled": false,
    "cancellation_occurred_at": null,
    "delivery_eta": null
  }
}

JSON returned for an omni request that has been cancelled by the requestor:

{
  "request": {
    "id": "1234",
    "external_reference_number": "238947",
    "courier_company": "Roadie",
    "status": "request_cancelled",
    "status_detail": null,
    "creation_occurred_at": "2025-01-30T015:00:00Z",
    "picked_up": false,
    "pickup_occurred_at": null,
    "delivery": null,
    "cancelled": true,
    "cancellation_occurred_at": "2025-01-30T017:20:00Z",
    "delivery_eta": null
  }
}

This endpoint retrieves a specific request.

HTTP Request

GET https://api.scriptdrop.co/omni/v2/requests/:id

URL Parameters

Parameter Description
:id The ID of the request to retrieve

200 Request Response Schema

Name Type Description
request Request Request details

Request Parameters

Name Type Description
id String ID of the request
external_reference_number String Reference number used to identify the request from an external system.
courier_company String Name of the courier company assigned to the order
status String Request’s current status.
status_detail String Details of the request’s current status.
creation_occured_at ISO 8601 timestamp Timestamp indicating when the request was created.
picked_up Boolean Indicating whether or not the request has been picked up by the courier.
pickup_occurred_at ISO 8601 timestamp Timestamp indicating when courier pickup occurred.
delivery Delivery Details about when the order was delivered
cancelled Boolean Indicating whether or not the request has been cancelled.
cancellation_occurred_at ISO 8601 timestamp Timestamp indicating when the request was cancelled.
delivery_eta String A string containing the delivery date with the estimated time or time range. Delivery etas are not included if the request has been cancelled or already completed.

Delivery

Note: The status field should be referenced for the current status of the order.

Name Type Description
occurred_at ISO 8601 timestamp Timestamp indicating when delivery occurred.
signature_url String URL that can be used to download the signature image. The URL is only authenticated for a brief period of time. A new URL will be provided on each request. Only present when delivery was successful.
photo_url String URL that can be used to download the delivery image. The URL is authenticated for 48 hours. A new URL will be provided on each request. Only present when delivery was successful and a photo was obtained.
signed_by String Name of recipient who signed for the delivery. Only present when the delivery was successful.
relationship String Description of the relationship between the patient and recipient. Only present when the delivery was successful for sameday orders.
other_relationship_description String Description of the relationship between the patient and recipient. Only present when order.delivery.relationship is Other for sameday orders.
failure_reason String Reason why the delivery failed. Only present when the delivery was unsuccessful.
recipient_identification RecipientIdentification Information regarding identification of the recipient at the point of delivery.

Recipient Identification

Name Type Description
number String Identifier captured. Example: driver license number.
type String Human readable description of the type of identification collected at point of delivery.
qualifier String Qualifier corresponding to type. See the Recipient Identification Qualifiers table below for the mapping.
jurisdiction_code String Code representing the jurisdiction which issued the form of identification collected. Only used if identification type is a driver license or state issued ID. Example: "OH" for "Ohio".

Recipient Identification Qualifiers

Value Description
01 Military ID
02 State Issued ID
03 Unique System ID
04 Permanent Resident Card (Green Card)
05 Passport ID
06 Driver’s License ID
07 Social Security Number
08 Tribal ID

Get Multiple Requests

url = "https://api.scriptdrop.co/omni/v2/requests/"

headers = [
  {"Authorization", "Basic encoded_authorization"},
  {"Content-type", "application/json"}
]

HTTPoison.start()
HTTPoison.get(url, headers, params: ["ids[]": "1237", "ids[]": "1238"])

JSON returned for two new requests:

{
  "requests": [
    {
      "id": "1234",
      "external_reference_number": "238947",
      "courier_company": null,
      "status": "request_received",
      "status_detail": null,
      "creation_occurred_at": "2025-01-30T015:00:00Z",
      "picked_up": false,
      "pickup_occurred_at": null,
      "delivery": null,
      "cancelled": false,
      "cancellation_occurred_at": null,
      "delivery_eta": "2025-01-31T10:00:00Z - 2025-01-31T14:00:00Z"
    },
    {
      "id": "1235",
      "external_reference_number": "238949",
      "courier_company": null,
      "status": "request_received",
      "status_detail": null,
      "creation_occurred_at": "2025-01-30T015:10:00Z",
      "picked_up": false,
      "pickup_occurred_at": null,
      "delivery": null,
      "cancelled": false,
      "cancellation_occurred_at": null,
      "delivery_eta": "2025-01-31T10:00:00Z - 2025-01-31T14:00:00Z"
    }
  ],
  "page_number": 1,
  "page_total": 1,
  "request_total": 2
}

This endpoint retrieves information for several requests at once.

HTTP Request

GET https://api.scriptdrop.co/omni/v2/requests/?query_parameters

Query Parameters

Name Type Description
ids Integer Retrieve specific requests by request id. Cannot be combined with other parameters.
identifier String Filter results for a specific program using the program’s identifier.
inactive Boolean Default: false. Set to true to filter for requests which are in a terminal/inactive status (complete, incomplete, or cancelled).
start_created_at ISO 8601 timestamp Retrieve all requests created after a specific datetime.
end_created_at ISO 8601 timestamp Retrieve all requests created before a specific datetime. Requires start_created_at. Default: UTC now
page Integer The number of the page you want to retrieve. Default: 1
page_size Integer The number of requests you want per page. Max: 100, Default: 30

200 Request Response Schema

Name Type Description
requests Request[] Array of Request objects as described under Get a Request.
page_number Integer The page number returned
page_total Integer The total number of pages returned
request_total Integer The total number of requests returned

Pharmacy Lookup

example_url_with_origin_address = "https://request.scriptdrop.co/api/v2/pharmacies/?origin_address=855%20Grandview%20Ave,%20Columbus,%20OH%2043215&identifier=identifier"
example_url_with_place_id = "https://request.scriptdrop.co/api/v2/pharmacies/?google_place_id=ChIJ299BewaPOIgRLRWsKwHLBuw&identifier=identifier"

headers = [
  {"Authorization", "Basic encoded_authorization"},
  {"Content-type", "application/json"}
]

HTTPoison.start()
HTTPoison.get(url, headers)

JSON returned for example query string parameters:

{
  "count": "3",
  "page": "1",
  "page_size": "30",
  "total_pages": "1",
  "formatted_address": "855 Grandview Ave, Columbus, OH 43215",
  "pharmacies": [
    {
      "npi": "12078667343",
      "ncpdp": "9758647",
      "name": "Example Pharmacy",
      "preferred": true,
      "distance_from_origin": 2.11,
      "phone_number": "6148675309",
      "fax_number": "6034653629",
      "address": {
        "street1": "200 Grandview Ave.",
        "street2": null,
        "city": "Columbus",
        "state": "OH",
        "zipcode": "43215"
      }
    },
    {
      "npi": "12078667343",
      "ncpdp": "9758647",
      "name": "Drugs-Are-Us",
      "preferred": true,
      "distance_from_origin": 2.56,
      "phone_number": "8142227878",
      "fax_number": "8142227879",
      "address": {
        "street1": "2345 High St.",
        "street2": "Suite 7",
        "city": "Columbus",
        "state": "OH",
        "zipcode": "43213"
      }
    },
    {
      "npi": "12078667343",
      "ncpdp": "9758647",
      "name": "Prescription Mart",
      "preferred": false,
      "distance_from_origin": 4.02,
      "phone_number": null,
      "fax_number": null,
      "address": {
        "street1": "88 Main St.",
        "street2": null,
        "city": "Columbus",
        "state": "OH",
        "zipcode": "43116"
      }
    }
  ]
}

This endpoint retrieves information for pharmacies within a deliverable radius of an origin address or Google Place ID. Returned list of pharmacies is sorted by preferred status, followed by closest distance to origin_address or google_place_id. Separate parameters using the ampersand (&) character. Response is paginated with a default page size of 30.

HTTP Request

GET https://request.scriptdrop.co/api/v2/pharmacies/?parameters

Query String Parameters

Name Type Description
origin_address (required, unless google_place_id is included) URL-escaped string The delivery (dropoff) street address. Specify full address in accordance with the format used by the United States Postal Service. Errors returned for improper formatting or missing zipcodes.
Example: 855 Grandview Ave, Columbus, OH 43215.
Additional elements such as business names, apt, unit or suite numbers should be omitted.
google_place_id (required, unless origin_address is included) URL-escaped string The delivery (dropoff) Google Place ID. Errors returned for invalid Place IDs.
Example: ChIJ299BewaPOIgRLRWsKwHLBuw
identifier (required) string The identifier string of the specific program relevant to your query.
page (optional) integer The number of the page you want to retrieve. Default: 1
page_size (optional) integer The number of responses you want per page. Max: 100, Default: 30

200 Pharmacy Lookup Response Schema

Name Type Description
count Integer Total number of pharmacies found within a deliverable radius of the origin address.
page Integer The number of the page being returned.
total_pages Integer The total number of pages available.
page_size Integer The number of pharmacies returned per page.
formatted_address String Origin address as returned by geocoder.
pharmacies Pharmacy[] Array of pharmacies within a deliverable radius of the origin address.

Pharmacy Parameters

Name Type Description
npi String National Provider Identifier
ncpdp String National Council for Prescription Drug Programs unique pharmacy identifier
name String Pharmacy name
preferred Boolean Indicates whether the pharmacy is a preferred ScriptDrop partner.
distance_from_origin Decimal Approximate distance from pharmacy to origin_address, rounded to nearest 0.01 mile.
phone_number String Pharmacy phone number (only returns for preferred pharmacies)
fax_number String Pharmacy fax number (only returns for preferred pharmacies)
address Address Pharmacy address

Address Parameters

Name Type Description
street1 String Pharmacy street address
street2 String Pharmacy street2 address
city String Pharmacy city
state String Pharmacy state
zipcode String Pharmacy zipcode

Get a Pharmacy

example_url = "https://api.scriptdrop.co/omni/v2/pharmacies/9758647"
headers = [
  {"Authorization", "Basic encoded_authorization"},
  {"Content-type", "application/json"}
]

HTTPoison.start()
HTTPoison.get(url, headers)

JSON returned for example pharmacy:

{
  "npi": "12078667343",
  "ncpdp": "9758647",
  "name": "Example Pharmacy",
  "preferred": true,
  "phone_number": "6148675309",
  "fax_number": "6034653629",
  "address": {
    "street1": "200 Grandview Ave.",
    "street2": null,
    "city": "Columbus",
    "state": "OH",
    "zipcode": "43215"
  }
}

This endpoint retrieves a specific pharmacy.

HTTP Request

GET https://api.scriptdrop.co/omni/v2/pharmacies/:id

URL Parameters

Parameter Description
:id The NPCPD or NPI of the pharmacy to get

200 Single Pharmacy Lookup Response Schema

Name Type Description
npi String National Provider Identifier
ncpdp String National Council for Prescription Drug Programs unique pharmacy identifier
name String Pharmacy name
preferred Boolean Indicates whether the pharmacy is a preferred ScriptDrop partner.
phone_number String Pharmacy phone number (only returns for preferred pharmacies)
fax_number String Pharmacy fax number (only returns for preferred pharmacies)
address Address Pharmacy address

Address Parameters

Name Type Description
street1 String Pharmacy street address
street2 String Pharmacy street2 address
city String Pharmacy city
state String Pharmacy state
zipcode String Pharmacy zipcode

Omni V1

Create a Request

url = "https://request.scriptdrop.co/api/v1/requests"

headers = [
  {"Authorization", "Basic encoded_authorization"},
  {"Content-type", "application/json"}
]

pharmacy_pickup_request_params = %{
  "identifier" => "WAHTP",
  "external_reference_number" => "238947",
  "ndc" => "98765432100",
  "pharmacy" => %{
    "ncpdp" => "1234567"
  },
  "dropoff" => %{
    "name" => "JOHN DOE",
    "phone_number" => "1115550000",
    "address" => %{
      "street1" => "1230 Street",
      "street2" => "Apt 3",
      "city" => "Columbus",
      "state" => "OH",
      "zipcode" => "43210"
    }
  },
  "patient" => %{
    "first_name" => "JOHN",
    "last_name" => "DOE",
    "gender" => "male",
    "date_of_birth" => "2000-02-01"
  },
  "remittance" => %{
    "contact" => %{
      "mobile_phone_number" => "1116660000",
      "email" => "john.doe@someemail.com"
    },
    "payments" => [
      %{
        "fee" => 12.00,
        "kind" => "copay"
      },
      %{
        "fee" => 3.00,
        "kind" => "delivery_fee"
      }
    ]
  }
}

HTTPoison.start()
HTTPoison.post(url, Jason.encode!(omni_request_params), headers)

The above command returns JSON structured like this:

{
  "request": {
    "id": "1234",
    "external_reference_number": "238947",
    "created_at": "2019-01-01T01:00:00Z",
    "order": null
  }
}

This endpoint creates a new Omni request.

HTTP Request

POST https://request.scriptdrop.co/api/v1/requests

Body Parameters

Name Type Required Length Description
identifier String true Unique program id provided by ScriptDrop.
external_reference_number String true max: 255 Reference number used to identify the request from an external system.
ndc String false is: 11 National Drug Code.
name_of_pickup String true Name of item for pickup. Required if ndc not provided.
pharmacy Pharmacy true Pharmacy details.
pickup Pickup false Pickup details. Required if pickup location is not provided pharmacy.
dropoff Dropoff true Dropoff details.
patient Patient true Patient details.
remittance Remittance false Information required to collect any fees or copays associated with the request.

Pharmacy Parameters

Name Type Required Length Description
ncpdp String true is: 7 Pharmacy NCPDP

Pickup Parameters

Name Type Required Length Description
name String true max: 71 In cases where the pickup location is an individual, this should be the first and last name of the person. Otherwise, enter the name of the pickup location.
phone_number String true is: 10 Phone number of the pickup individual or location.
address Address true Request pickup address.

Dropoff Parameters

Name Type Required Length Description
name String true max: 71 The name of the request recipient. In cases where the patient is the recipient, this should be the first and last name of the patient.
phone_number String true is: 10 Phone number for the request recipient.
address Address, Google Place Address true Request dropoff address. Can take a full address OR a Google place id.

Sample Dropoff with Full Address

%{
  "dropoff" => %{
    "name" => "JOHN DOE",
    "phone_number" => "1115550000",
    "address" => %{
      "street1" => "1230 Street",
      "street2" => "Apt 3",
      "city" => "Columbus",
      "state" => "OH",
      "zipcode" => "43210"
    }
}

Sample Dropoff with Google Place ID

%{
  "dropoff" => %{
    "name" => "JOHN DOE",
    "phone_number" => "1115550000",
    "address" => %{
      "google_place_id" => "ChIJIYo9-12OOIgRR9WiX1nG0V0"
    }
}

Address Parameters

Name Type Required Length Description
street1 String true max: 255 Street
street2 String false max: 255 Street2
city String true max: 255 City
state String true max: 2 Two-letter state abbreviation
zipcode String true is: 5 or is: 9 Zipcode

Alternate Address Parameters (FOR DROPOFF ONLY)

Name Type Required Length Description
google_place_id String true max: 255 A Google place id

Patient Parameters

Name Type Required Length Description
first_name String true max: 30 Patient's first name.
last_name String true max: 40 Patient's. last name
gender String false Patient's gender. Can be one of: male, female, unspecified.
date_of_birth ISO 8601 date string true Patient's date of birth.

Remittance Parameters

Name Type Required Length Description
contact Contact true Contact details specifically for the collection of amounts due from the patient.
payments Payment true Array of Payment objects detailing payment amount due and payment kind.

Contact Parameters

Name Type Required Length Description
mobile_phone_number String true is: 10 Phone number used to communicate links and reminders regarding payment.
email String false max: 255 Email used to communicate links and reminders regarding payment.

Payment Parameters

Name Type Required Length Description
fee Decimal true Amount to be charged to patient. Amount must be greater than 0.
kind String true Indicate kind related to fee for request. Can be one of: delivery_fee, copay

200 Response Schema

See the 200 Response Schema under Get a Request.

Error Response

See Errors

Cancel a Request

url = "https://request.scriptdrop.co/api/v1/requests/1235"

headers = [
  {"Authorization", "Basic encoded_authorization"},
]

HTTPoison.start()
HTTPoison.delete(url, headers)

On success the above command returns no response body

Example error response for attempted cancellation of Omni request with orders in uncancellable status:

{
  "error": {
    "id": "1235",
    "type": "unable_to_cancel",
    "message": "Orders are not in a cancellable status."
  }
}

This endpoint cancels an Omni request and any associated orders that are in a cancellable status.

HTTP Request

DELETE https://request.scriptdrop.co/api/v1/requests/:id

URL Parameters

Parameter Description
:id The ID of the request to delete

Success Response

HTTP status code 204

Error Response

See Errors

Get a Request

url = "https://request.scriptdrop.co/api/v1/requests/1236"

headers = [
  {"Authorization", "Basic encoded_authorization"},
  {"Content-type", "application/json"}
]

HTTPoison.start()
HTTPoison.get(url, headers)

JSON returned for a new Omni request:

{
  "request": {
    "id": "1236",
    "external_reference_number": "876566",
    "created_at": "2021-01-02T02:00:00Z",
    "delivery_eta": "2021-01-02 10:00:00 AM - 02:00:00 PM Etc/UTC",
    "order": null
  }
}

JSON returned for a new Omni request with associated order:

{
  "request": {
    "id": "1236",
    "external_reference_number": "876566",
    "created_at": "2021-01-02T02:00:00Z",
    "delivery_eta": "2021-01-02T14:00:00Z",
    "order": {
      "id": "1234",
      "courier_company": null,
      "external_reference_number": null,
      "status": "new",
      "pickup": null,
      "delivery": null,
      "return": null,
      "cancelled_by": null,
      "cancellation_reason": null,
      "status_note": null,
      "status_note_updated_at": null
    },
    "status": {
      "name": "request_incomplete",
      "detail": "patient_picked_up"
    }
  }
}

JSON returned for an Omni request with cancelled order:

{
  "request": {
    "id": "1236",
    "external_reference_number": "876566",
    "created_at": "2021-01-02T02:00:00Z",
    "order": {
      "id": "1234",
      "courier_company": null,
      "external_reference_number": null,
      "status": "new",
      "pickup": null,
      "delivery": null,
      "return": null,
      "cancelled_by": "Internal",
      "cancellation_reason": "Patient no longer wants",
      "status_note": null,
      "status_note_updated_at": null
    },
    "status": {
      "name": "request_incomplete",
      "detail": "pharmacy_out_of_stock"
    }
  }
}

JSON returned for an Omni request with associated picked-up order:

{
  "request": {
    "id": "1236",
    "external_reference_number": "876566",
    "created_at": "2021-01-02T02:00:00Z",
    "order": {
      "id": "1234",
      "courier_company": "Company Name",
      "external_reference_number": null,
      "status": "picked_up",
      "pickup": {
        "occurred_at": "2021-01-02T05:00:00Z"
      },
      "delivery": null,
      "return": null,
      "cancelled_by": null,
      "cancellation_reason": null,
      "status_note": null,
      "status_note_updated_at": null
    },
    "status": {
      "name": "request_received",
      "detail": null
    }
  }
}

JSON returned for an Omni request with successfully delivered order:

{
  "request": {
    "id": "1236",
    "external_reference_number": "876566",
    "created_at": "2021-01-02T02:00:00Z",
    "order": {
      "id": "1234",
      "courier_company": "Company Name",
      "external_reference_number": null,
      "status": "picked_up",
      "pickup": {
        "occurred_at": "2021-01-02T05:00:00Z"
      },
      "delivery": {
        "occurred_at": "2021-01-02T05:20:00Z",
        "signature_url": "https://example.com/238947",
        "signed_by": "John Doe",
        "relationship": "Other",
        "other_relationship_description": "Sibling",
        "recipient_identification": null,
        "failure_reason": null
      },
      "return": null,
      "cancelled_by": null,
      "cancellation_reason": null,
      "status_note": null,
      "status_note_updated_at": null
    },
    "status": {
      "name": "request_received",
      "detail": null
    }
  }
}

JSON returned for Omni request with unsuccessfully delivered order being returned to the pharmacy:

{
  "request": {
    "id": "1236",
    "external_reference_number": "876566",
    "created_at": "2021-01-02T02:00:00Z",
    "order": {
      "id": "1234",
      "courier_company": "Company Name",
      "external_reference_number": null,
      "status": "picked_up",
      "pickup": {
        "occurred_at": "2021-01-02T05:00:00Z"
      },
      "delivery": {
        "occurred_at": "2021-01-02T05:20:00Z",
        "signature_url": null,
        "signed_by": null,
        "relationship": null,
        "other_relationship_description": null,
        "recipient_identification": null,
        "failure_reason": "Patient Not Home"
      },
      "return": null,
      "cancelled_by": null,
      "cancellation_reason": null,
      "status_note": "Pharmacy called to cancel order, patient advised no longer needs Rx.",
      "status_note_updated_at": "2022-10-26T17:14:33.561729Z"
    },
    "status": {
      "name": "request_received",
      "detail": null
    }
  }
}

JSON returned for Omni request with order returned to the pharmacy:

{
  "request": {
    "id": "1236",
    "external_reference_number": "876566",
    "created_at": "2021-01-02T02:00:00Z",
    "order": {
      "id": "1234",
      "courier_company": "Company Name",
      "external_reference_number": null,
      "status": "picked_up",
      "pickup": {
        "occurred_at": "2021-01-02T05:00:00Z"
      },
      "delivery": {
        "occurred_at": "2021-01-02T05:20:00Z",
        "signature_url": null,
        "signed_by": null,
        "relationship": null,
        "other_relationship_description": null,
        "recipient_identification": null,
        "failure_reason": "Patient Not Home"
      },
       "return": {
        "occurred_at": "2021-01-02T05:20:00Z"
      },
      "cancelled_by": null,
      "cancellation_reason": null,
      "status_note": null,
      "status_note_updated_at": null
    },
    "status": {
      "name": "request_received",
      "detail": null
    }
  }
}

This endpoint retrieves a specific request.

HTTP Request

GET https://request.scriptdrop.co/api/v1/requests/:id

URL Parameters

Parameter Description
:id The ID of the request to retrieve

200 Request Response Schema

Name Type Description
request Request Request details

Request Parameters

Name Type Description
id String ID of the request
external_reference_number String Reference number used to identify the request from an external system.
created_at ISO 8601 timestamp Timestamp indicating when the request was created.
order Order Details of the order associated with the request
status Status Details of the status associated with the request
delivery_eta String A string containing the delivery date with the estimated time or time range

Order Parameters

Name Type Description
id String ID of the order
courier_company String Name of the courier company assigned to the order
status String Current status of the order. Will be one of: new, submitted_to_courier, picked_up, delivered, delivery_attempted, returned_to_pharmacy or cancelled.
pickup Pickup Details about when the order was picked up
delivery Delivery Details about when the order was delivered
return Return Details about the order's return to the pharmacy
cancelled_by String Details of who cancelled an order
cancellation_reason String Details of why an order was cancelled
status_note String Internal note about the order's current status
status_note_updated_at String Timestamp of when status_note was last updated

Pickup

Note: The status field should be referenced for the current status of the order.

Name Type Description
occurred_at ISO 8601 timestamp Timestamp indicating when pickup occurred

Delivery

Note: The status field should be referenced for the current status of the order.

Name Type Description
occurred_at ISO 8601 timestamp Timestamp indicating when delivery occurred.
signature_url String URL that can be used to download the signature image. The URL is only authenticated for a brief period of time. A new URL will be provided on each request. Only present when delivery was successful.
signed_by String Name of recipient who signed for the delivery. Only present when the delivery was successful.
relationship String Description of the relationship between the patient and recipient. Only present when the delivery was successful for sameday orders.
other_relationship_description String Description of the relationship between the patient and recipient. Only present when order.delivery.relationship is Other for sameday orders.
failure_reason String Reason why the delivery failed. Only present when the delivery was unsuccessful.
recipient_identification RecipientIdentification Information regarding identification of the recipient at the point of delivery.

Return

Name type Description
occurred_at ISO 8601 timestamp Timestamp indicating when return occurred

Status

Name type Description
name string Name of the status
detail string Details of the status

Recipient Identification

Name Type Description
number String Identifier captured. Example: driver license number.
type String Human readable description of the type of identification collected at point of delivery.
qualifier String Qualifier corresponding to type. See the Recipient Identification Qualifiers table below for the mapping.
jurisdiction_code String Code representing the jurisdiction which issued the form of identification collected. Only used if identification type is a driver license or state issued ID. Example: "OH" for "Ohio".

Recipient Identification Qualifiers

Value Description
01 Military ID
02 State Issued ID
03 Unique System ID
04 Permanent Resident Card (Green Card)
05 Passport ID
06 Driver’s License ID
07 Social Security Number
08 Tribal ID

Get Multiple Requests

url = "https://request.scriptdrop.co/api/v1/requests/"

headers = [
  {"Authorization", "Basic encoded_authorization"},
  {"Content-type", "application/json"}
]

HTTPoison.start()
HTTPoison.get(url, headers, params: ["ids[]": "1237", "ids[]": "1238"])

JSON returned for two new requests:

{
  "requests": [
    {
      "request": {
        "id": "1236",
        "external_reference_number": "876567",
        "created_at": "2021-01-02T02:00:00Z",
        "order": null
      }
    },
    {
      "request": {
        "id": "1237",
        "external_reference_number": "876568",
        "created_at": "2021-01-02T02:05:00Z",
        "order": null
      }
    }
  ]
}

This endpoint retrieves information for several requests at once.

HTTP Request

GET https://request.scriptdrop.co/api/v1/requests/:request_ids

URL Parameters

Parameter Description
:request_ids An array of IDs for the requests you wish to retrieve, formatted as ids[]=1&ids[]=2, etc

200 Request Response Schema

Name Type Description
requests Request[] Array of Request objects as described under Get a Request.

Pharmacy Lookup

example_url_with_origin_address = "https://request.scriptdrop.co/api/v1/pharmacies/?origin_address=855%20Grandview%20Ave,%20Columbus,%20OH%2043215&identifier=identifier"
example_url_with_place_id = "https://request.scriptdrop.co/api/v1/pharmacies/?google_place_id=ChIJ299BewaPOIgRLRWsKwHLBuw&identifier=identifier"

headers = [
  {"Authorization", "Basic encoded_authorization"},
  {"Content-type", "application/json"}
]

HTTPoison.start()
HTTPoison.get(url, headers)

JSON returned for example query string parameters:

{
  "count": "3",
  "page": "1",
  "page_size": "30",
  "total_pages": "1",
  "formatted_address": "855 Grandview Ave, Columbus, OH 43215",
  "pharmacies": [
    {
      "npi": "12078667343",
      "ncpdp": "9758647",
      "name": "Example Pharmacy",
      "preferred": true,
      "distance_from_origin": 2.11,
      "phone_number": "6148675309",
      "fax_number": "6034653629",
      "address": {
        "street1": "200 Grandview Ave.",
        "street2": null,
        "city": "Columbus",
        "state": "OH",
        "zipcode": "43215"
      }
    },
    {
      "npi": "12078667343",
      "ncpdp": "9758647",
      "name": "Drugs-Are-Us",
      "preferred": true,
      "distance_from_origin": 2.56,
      "phone_number": "8142227878",
      "fax_number": "8142227879",
      "address": {
        "street1": "2345 High St.",
        "street2": "Suite 7",
        "city": "Columbus",
        "state": "OH",
        "zipcode": "43213"
      }
    },
    {
      "npi": "12078667343",
      "ncpdp": "9758647",
      "name": "Prescription Mart",
      "preferred": false,
      "distance_from_origin": 4.02,
      "phone_number": null,
      "fax_number": null,
      "address": {
        "street1": "88 Main St.",
        "street2": null,
        "city": "Columbus",
        "state": "OH",
        "zipcode": "43116"
      }
    }
  ]
}

This endpoint retrieves information for pharmacies within a deliverable radius of an origin address or Google Place ID. Returned list of pharmacies is sorted by preferred status, followed by closest distance to origin_address or google_place_id. Separate parameters using the ampersand (&) character. Response is paginated with a default page size of 30.

HTTP Request

GET https://request.scriptdrop.co/api/v1/pharmacies/?parameters

Query String Parameters

Name Type Description
origin_address (required, unless google_place_id is included) URL-escaped string The delivery (dropoff) street address. Specify full address in accordance with the format used by the United States Postal Service. Errors returned for improper formatting or missing zipcodes.
Example: 855 Grandview Ave, Columbus, OH 43215.
Additional elements such as business names, apt, unit or suite numbers should be omitted.
google_place_id (required, unless origin_address is included) URL-escaped string The delivery (dropoff) Google Place ID. Errors returned for invalid Place IDs.
Example: ChIJ299BewaPOIgRLRWsKwHLBuw
identifier (required) string The identifier string of the specific program relevant to your query.
page (optional) integer The number of the page you want to retrieve. Default: 1
page_size (optional) integer The number of responses you want per page. Max: 100, Default: 30

200 Pharmacy Lookup Response Schema

Name Type Description
count Integer Total number of pharmacies found within a deliverable radius of the origin address.
page Integer The number of the page being returned.
total_pages Integer The total number of pages available.
page_size Integer The number of pharmacies returned per page.
formatted_address String Origin address as returned by geocoder.
pharmacies Pharmacy[] Array of pharmacies within a deliverable radius of the origin address.

Pharmacy Parameters

Name Type Description
npi String National Provider Identifier
ncpdp String National Council for Prescription Drug Programs unique pharmacy identifier
name String Pharmacy name
preferred Boolean Indicates whether the pharmacy is a preferred ScriptDrop partner.
distance_from_origin Decimal Approximate distance from pharmacy to origin_address, rounded to nearest 0.01 mile.
phone_number String Pharmacy phone number (only returns for preferred pharmacies)
fax_number String Pharmacy fax number (only returns for preferred pharmacies)
address Address Pharmacy address

Address Parameters

Name Type Description
street1 String Pharmacy street address
street2 String Pharmacy street2 address
city String Pharmacy city
state String Pharmacy state
zipcode String Pharmacy zipcode

Get a Pharmacy

example_url = "https://request.scriptdrop.co/api/v1/pharmacies/9758647"
headers = [
  {"Authorization", "Basic encoded_authorization"},
  {"Content-type", "application/json"}
]

HTTPoison.start()
HTTPoison.get(url, headers)

JSON returned for example pharmacy:

{
  "npi": "12078667343",
  "ncpdp": "9758647",
  "name": "Example Pharmacy",
  "preferred": true,
  "phone_number": "6148675309",
  "fax_number": "6034653629",
  "address": {
    "street1": "200 Grandview Ave.",
    "street2": null,
    "city": "Columbus",
    "state": "OH",
    "zipcode": "43215"
  }
}

This endpoint retrieves a specific pharmacy.

HTTP Request

GET https://request.scriptdrop.co/api/v1/pharmacies/:id

URL Parameters

Parameter Description
:id The NPCPD or NPI of the pharmacy to get

200 Single Pharmacy Lookup Response Schema

Name Type Description
npi String National Provider Identifier
ncpdp String National Council for Prescription Drug Programs unique pharmacy identifier
name String Pharmacy name
preferred Boolean Indicates whether the pharmacy is a preferred ScriptDrop partner.
phone_number String Pharmacy phone number (only returns for preferred pharmacies)
fax_number String Pharmacy fax number (only returns for preferred pharmacies)
address Address Pharmacy address

Address Parameters

Name Type Description
street1 String Pharmacy street address
street2 String Pharmacy street2 address
city String Pharmacy city
state String Pharmacy state
zipcode String Pharmacy zipcode

Sandbox Automated Testing (Omni V1)

An automated testing suite is available for use in the sandbox environment. (Please note this is just for Omni V1. Reach out for information on accessing the sandbox environment.) Currently, the suite is designed to test the following scenarios:

Available Scenarios

Name Description
successful_delivery This scenario will take a submitted request, create a new order, and simulate the successful delivery of the order, passing through the statuses at a specified cadance.
unsuccessful_delivery This scenario will take a submitted request, create a new order, and simulate the unsuccessful delivery of the order as well as the subsequent return to pharmacy, passing through the statuses at a specified cadance.
incomplete_request This scenario will take a submitted request and mark it as incomplete, passing through the statuses at a specified cadance.

Running a Scenario

Sample Request with Test Meta

test_request_params = %{
  "test_meta" => %{
    "scenario" => "successful_delivery",
    "duration_between" => 10
  },
  "identifier" => "WAHTP",
  "external_reference_number" => "238947",
  "ndc" => "98765432100",
  "pharmacy" => %{
    "ncpdp" => "1234567"
  },
  "dropoff" => %{
    "name" => "JOHN DOE",
    "phone_number" => "1115550000",
    "address" => %{
      "street1" => "1230 Street",
      "street2" => "Apt 3",
      "city" => "Columbus",
      "state" => "OH",
      "zipcode" => "43210"
    }
  },
  "patient" => %{
    "first_name" => "JOHN",
    "last_name" => "DOE",
    "gender" => "male",
    "date_of_birth" => "2000-02-01"
  },
  "remittance" => %{
    "contact" => %{
      "mobile_phone_number" => "1116660000",
      "email" => "john.doe@someemail.com"
    },
    "payments" => [
      %{
        "fee" => 12.00,
        "kind" => "copay"
      },
      %{
        "fee" => 3.00,
        "kind" => "delivery_fee"
      }
    ]
  }
}

To run a scenario, submit a request as normal but include the following parameters in the request body.

Body Parameters

Name Type Required Description
test_meta TestMeta false The meta parameters for the test.

Test Meta Parameters

Name Type Required Description
scenario String true The name of the scenario to run. See Available Scenarios for a list of available scenarios.
duration_between Integer false The cadence at which the statuses should be updated in seconds. Must be between 1-900. Defaults to 30 seconds.

Errors

The ScriptDrop Pharmacy API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- Request not authorized.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a route that's not allowed.
406 Not Acceptable -- You requested a format that isn't supported.
422 Unprocessable Request -- Your request is unprocessable. (ex. You've sent a value in a parameter that is outside of limitations.)
429 Too Many Requests -- You've hit your request limit. Retry in a few moments.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
elixir