> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byblend.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Building by Blend
> Welcome to the Blend API documentation
# General Concepts
Products are your business's individual "SKUs," whether prescription or non-prescription. These entities contain descriptive information, pricing, your own product code/identifier, and other (generally) patient-facing information. Blend will manage underlying inventory for your products.
The healthcare professionals who will prescribe your prescription products, and who will be sending Electronic Prescriptions. Prescriber regulatory information (NPI/SPI), licensing credentials, supervisory relationships (if applicable), address/contact and biographical information are required to be kept up-to-date within Blend.
Electronic Prescriptions, sent via either the Surescripts network or directly via API, are required to fill an order containing prescription products. Each prescription product in an order needs an active/non-expired prescription with fills remaining.
The individuals who will receive products directly fulfilled by Blend. Patient profiles in Blend must be kept up-to-date, including name, address, contact information, and (critically) any risk factors: allergies, drug interactions, pre-existing conditions, pregnancy state, etc.
Orders are the unification of the above that result in (in most cases) a filled prescription, packaged product(s) in your custom packaging, and a shipping box sent straight to your patient.
# Blend End-to-End
Each of the above is required to be created within Blend for an order to be filled end-to-end.
*For the most part*, the above entities can be created in any order. Blend systems will match accordingly when all data is available. The happiest path, however, is the following:
```mermaid theme={null}
flowchart TB
subgraph live[Order Flow]
direction TB
subgraph 3[New Patients]
direction TB
patient(Create Patient) -->prescription(Send Prescription) -->order(Create Order)
end
subgraph 4[Existing Patients]
direction TB
prescription2(Send Prescription) -->order2(Create Order)
end
subgraph 5[Refill]
direction TB
order3(Create Order)
end
end
subgraph before[Onboarding]
direction LR
top1(Create Products)
bottom1(Create Prescribers)
end
style live fill:#fff,stroke:#5d6b68
style before fill:#FEE0A8
style 3 fill:#f9fbfb,stroke:#5d6b68
style 4 fill:#f2f7f7,stroke:#5d6b68
style 5 fill:#dfecec,stroke:#5d6b68
```
*Please also note the single Composite Creation option, below, for specific use cases of specific customer types.*
### During Onboarding: Create Products and Prescribers
During your Blend onboarding, we will work with you to create initial products and match them accordingly with your own EMR or similar systems.
We will likewise work with you to bulk import existing prescribers and their licensing and other information.
Depending on your approach to existing patients and prospective refill prescriptions, we can also import / create patient records in advance.
### For New Patient Orders: Create (a New) Patient, Prescription, and Order
At the time of an order, your systems should be prepared to create the following entities within Blend.
* A **patient**, using the `/patients` endpoint.
* Alternatively, this can be created within an Order in a single request
* Not applicable for refills, as patient data already exists
* An **electronic prescription** (assuming the patient requires a prescribed product)
* This can be sent via Surescripts, or directly via API (`/prescriptions/electronic-prescription`) depending on your integration
* An **order**, using the `/orders` endpoint, containing the product(s) to be fulfilled by Blend
*While a patient must be created before sending an order, a prescription can be sent at any time (even before patient creation). Blend will match accordingly regardless of which is created first.*
### For Existing Patient Orders: Create a Prescription and Order
For existing patients (non-refill) orders, your system needs to only send:
* An **electronic prescription**, either via Surescripts or directly via API
* An **order** containing the product(s) to be fulfilled
### For Refill Orders: Create an Order
* Refills of existing prescriptions can be fulfilled simply be sending a new order
# Composite Creation
For customers who wish to streamline their API usage, Blend offers a "composite" endpoint, a convenience function wherein you can create an Electronic Prescription, Order, and even a new Patient and Prescriber, in a single request.
This Composite endpoint expects up to four objects in a request -- `electronic_prescription`, `order`, `patient`, `prescriber` -- with each adhering to its individual endpoint required fields. Patients and prescribers can be passed by reference.
# How Blend Matches Patients, Orders, Prescribers, Prescriptions and Products
There are a few key data fields Blend uses to match entities.
### Prescription to Patient
* If directly provided via API, Blend will look for a patient's `id` (Blend ID) or `external_id` (your own identifier that can be stored in Blend patient profiles).
* For Surescripts prescriptions, Blend will match on patient name (or preferred name) and date of birth; or patient contact information and date of birth.
### Prescription to Prescriber
* Prescribers will be matched based on NPI, DEA number, or SPI, with a fallback to name and date of birth
### Prescription to Product
* If directly provided via API, Blend will look for a `product` ID (Blend ID) or `product_code` in your request
* For Surescripts prescriptions, Blend will parse the ``, the `` or `` fields for matches to your products' `sku`, `product_code`, `ID`, or even its `name`.
### Prescription to Order
* Because a `patient` must be sent with an order, Blend will leverage the above mapping to tie orders to prescriptions via patient-match.
# Order Merging
Blend will attempt to consolidate open orders for the same patient. If a new order is created (either via API or in the Blend Dashboard) while a patient has an existing "open" order, the new order will be automatically merged into the existing order.
### Open (Mergeable) Orders
An open or mergeable order is one that has not yet been picked by Blend pharmacy staff. Once an order has entered the physical picking phase, it can no longer be merged-into, and a new order will be created for that patient.
### Shipping Updates Upon Merge
If a new order is merged into an existing order, any shipping address or preference updates **will** be inherited by the original order:
* If a new shipping address is provided, the merged order will be sent to the new shipping address.
* If a new/different shipping preference is provided (e.g., carrier or service level), the merged order will use the new preference.
### Merge response
If your attempt to create a new order has been merged with an existing open order for that patient, you will receive the original (existing) order information in response to your Create Order request.
In addition, this response will include `"merged_into_existing": true` to confirm a merge has occurred.
### Overriding order merge
You may send the `force_new=true` querystring argument when creating a new order (in either the Create Order or Composite endpoints) to prevent order merging. For instance, if a patient has requested a separate order be sent to a different location, you will want to maintain separate orders.