> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# User migration

> Migrating patients and removing a wrongly created one are requested from OpenLoop; you can still correct a record and re-submit.

> [!WARNING]
>
> **Migration and clean-up are requested from OpenLoop, not done by you.** If you are migrating an
> existing patient population onto the platform, or need a wrongly created patient removed, raise it
> with your OLH implementation contact before you plan around anything on this page. Nothing here is
> a committed migration path.

## What exists today

Patients are created one at a time with `POST /v0.1/patients` (verified on staging). That is the
only published way to get a patient into the platform.

**No bulk import endpoint is published.** There is no CSV upload, no batch create, and no
migration API in the published reference. A migration built only from published endpoints is a
loop over `POST /v0.1/patients`, at your own rate — which is why a population migration is planned
with OpenLoop rather than run from your side alone.

**You cannot delete.** Partners do not delete records — not patients, questionnaire responses,
consents or document references. A patient you create stays created. Removing one — a duplicate, a test record on
production, a half-finished migration — is something OpenLoop does on request.

The records hanging off a patient are not yours to replay either. A completed intake creates the
encounter as a side effect of `POST /v0.1/questionnaire-responses`, and the prescription that may
follow is created by a clinician; you can store the `encounter_id` the submit returns, but
encounters are not partner-readable. So historical clinical records cannot simply be replayed
through the partner surface.

## What you can still do yourself

| Situation | Your call | Label |
| - | - | - |
| A patient's details are wrong (name, email, phone, birth date, address) | `PUT /v0.1/patients/{id}` with the corrected fields | published |
| An intake was saved `in-progress` and needs finishing or correcting | `PUT /v0.1/questionnaire-responses/{id}` | published |
| An intake was submitted against the wrong patient or the wrong form | Submit again, correctly, with `POST /v0.1/questionnaire-responses`, and ask OpenLoop to remove the wrong one | verified on staging (submit); by-arrangement (removal) |
| A duplicate patient exists | Keep using the one you intend to keep, and ask OpenLoop to remove the other | by-arrangement |

Neither `PUT` is exercised by a conformance check. Whether a `PUT` clears fields you omit is not
stated in the spec, so rehearse it on a scratch patient on staging and send the full record you
want stored.

## Questions to settle before you start

Ask these of your OLH implementation contact; the answers change the shape of the work substantially.

| Question | Why it matters |
| - | - |
| Is there a supported bulk path not in the published reference? | Determines whether this is a loop or an operation someone runs for you |
| Do historical clinical records need to come across, or only patients and their active treatment? | Clinical history may not be replayable through partner endpoints at all |
| What identifier ties a migrated patient to your existing records? | There is no external-id field documented on the patient resource |
| How are in-flight prescriptions and active subscriptions handled at cutover? | A patient mid-treatment cannot simply be recreated |
| Is a zero-downtime cutover expected, and who verifies it? | Determines whether you need dual-write or a freeze window |
| How do you request removal of a wrongly created patient, and what is the turnaround? | You cannot undo a create yourself, so the clean-up path is OpenLoop's |
| What is the rollback plan if the cutover fails partway? | Partial migrations are the expensive failure mode, and only OpenLoop can remove what was created |

## What we can tell you now

* Creating a patient is idempotent only in the sense that repeated calls create **separate**
  records (verified on staging). There is no documented upsert, and no partner delete to undo a
  duplicate, so you must track which of your patients you have already created.
* `GET /v0.1/patients?email=<email>` filters by email and validates its input, so email is usable
  as a de-duplication check before creating (verified on staging).
* For OpenLoop-side clean-up: deleting a patient does **not** cascade to their encounters
  (verified on staging 2026-10-02). When you ask OpenLoop to remove a
  patient who has already submitted an intake, say so, so the encounter is handled too.

## Status

This page will be replaced once a migration path is agreed. Until then, treat any migration plan
built from this cookbook alone as unvalidated.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.