Introduction

Welcome to the ScriptDrop Omni Request 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

You must replace encoded_authorization with your encoded API key and secret.

V1 Omni Requests

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"
example_url_with_place_id = "https://request.scriptdrop.co/api/v1/pharmacies/?google_place_id=ChIJ299BewaPOIgRLRWsKwHLBuw"

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
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.

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

An automated testing suite is available for use in the sandbox environment. (Please 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.