Start with a Test API key and synthetic records. Use the API reference for current request schemas.
Affinity supports individual orders and bulk preparation. Each order belongs to one patient and requires its clinician’s review and attestation before signing through the API or Affinity.
Map your workflow
| RxRelay workflow | Affinity workflow |
|---|---|
| Clinic | Practice. A practice key accesses one practice. |
| Organization with several clinics | Platform. Use /v1/practices to manage connected practices. |
| Register users and prescribers | Register people through /v1/practices/{practiceId}/users; invitations remain optional. |
| Medication and pharmacy discovery | Use /v1/pharmacies and /v1/catalog/items. Store the returned pharmacy and catalog item IDs. |
| Patient records and saved addresses | Use /v1/practices/{practiceId}/patients and its patient address routes. |
| Create an order | Use POST /v1/orders to prepare one patient’s unsigned order. |
| Prepare several orders | Use POST /v1/order-batches. Each order has its own patient, signing, and fulfillment state. |
| Approve or reject an order | Use /v1/orders/{orderId}/sign or /rejection with the clinician identity and exact versions. |
| Order status and tracking | Retrieve the order and process signed webhook events. Pharmacy submission runs asynchronously. |
Your platform authenticates clinicians and collects their signing intent. A key with orders:sign can sign and submit on their behalf. Live still requires current verified prescribing authority.
Set up your practice and Team
- Create or select the destination practice.
- Create an API key with the permissions your backend needs.
- Register staff and prescribers through Team.
- Confirm each clinician’s active membership and prescribing credentials.
Use the registered person’s userId when assigning new drafts. You can omit userId to prepare unassigned drafts.
Preserve patient identifiers
Choose one stable external identity source, such as rxrelay. Keep each patient’s original identifier as the value.
For an API import, include externalIdentities when creating the patient:
{
"name": { "first": "Synthetic", "last": "Patient" },
"dateOfBirth": "1980-01-10",
"externalIdentities": [{ "source": "rxrelay", "value": "your-original-patient-id" }]
}Send this body to POST /v1/practices/{practiceId}/patients with the required authentication and mutation headers.
For later imports, look up both externalIdentitySource and externalIdentityValue on the practice patient collection. Update the matched patient with PATCH.
Patient email addresses do not merge records. Two people with the same email can remain separate patients.
Clinic also supports CSV import through Patients → Patient actions → Bulk import patients. Map these columns:
- First name
- Last name
- Date of birth
- External identity source
- External patient ID
Review the import preview and resolve conflicting identifiers before importing. Replay the same file in Test mode and confirm the patient count stays unchanged.
Prepare new orders
Read the available catalog and shipping options for the destination practice and mode. Match each product to its Affinity catalog item.
Check formulation, strength, route, quantity rules, pharmacy, and shipping. A matching product name alone does not establish an equivalent prescription.
Use /v1/orders for one patient or /v1/order-batches for up to 20 distinct patients. Each order accepts 1–20 prescriptions.
Store your order reference in externalOrderId. Store each prescription reference in externalPrescriptionId.
Send an Idempotency-Key for creation. Retry the unchanged request with the same key after an uncertain response.
Sign each order using the current versions and clinician attestation, then submit it. See headless signing.
Follow the result
Configure webhooks before switching your order workflow. Verify signatures and deduplicate events by event ID.
Track rejection, signing, submission, and shipment separately. Signing an order does not establish pharmacy acceptance.
Retrieve the order after missed or out-of-order events. Confirm tracking and item correlation against your stored external identifiers.
Plan historical records separately
The patient CSV importer does not import historical orders, prescriptions, fulfillment history, or attachments.
Customers can write import scripts against the public API. Historical import tooling is outside the current release scope.
If you need historical records in Affinity, confirm the supported destination before importing. Preserve the source export and reconcile counts and identifiers.
Do not recreate historical prescriptions through order creation. New orders require new clinician review and can lead to fulfillment and billing.
Verify before switching to Live
Complete the Test workflow with representative synthetic records:
- Import patients and replay the import.
- Prepare individual and bulk orders.
- Complete clinician review and rejection.
- Confirm revoked access prevents further actions.
- Confirm status events, tracking, and webhook replay.
Confirm each required pharmacy, product, price, and shipping service with Affinity. Feature coverage does not guarantee the same pharmacy network.
Agree on the last order your previous system will submit. Reconcile pending orders before enabling new Live submissions in Affinity.