---
title: "Migrate from RxRelay"
description: "Move patient records and new ordering workflows to Affinity."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.affinityrx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from RxRelay

Start with a Test API key and synthetic records. Use the [API reference](/api/) 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

1. Create or select the destination practice.
2. Create an API key with the permissions your backend needs.
3. Register staff and prescribers through [Team](/guides/provider-access).
4. 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:

```json
{
  "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](/guides/choose-an-integration/#sign-from-your-backend).

## Follow the result

Configure [webhooks](/guides/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:

1. Import patients and replay the import.
2. Prepare individual and bulk orders.
3. Complete clinician review and rejection.
4. Confirm revoked access prevents further actions.
5. 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.

Source: https://docs.affinityrx.com/guides/migrate-from-rxrelay/index.mdx