--- title: "Practices" description: "Platforms create and list their practices, and send a practiceId with each order." --- > 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. # Practices A platform orders for its practices. Each platform order names one practice with `practiceId`. A practice's own key can omit `practiceId`; Affinity uses that practice. Use the flat `/v1/orders` route for both key types. ## Create a practice ```sh curl https://api.affinityrx.com/v1/practices \ -H "Authorization: Bearer $AFFINITY_API_KEY" \ -H "Affinity-Version: 2026-10-28" \ -H "Idempotency-Key: practices-guide-create-42" \ -H "Content-Type: application/json" \ --data '{ "externalId": "practice-42", "name": "Example Clinic", "phone": "+15125550123", "address": { "line1": "200 Example Ave", "line2": "Suite 4", "city": "Austin", "state": "TX", "postalCode": "78701" } }' ``` `name`, `phone`, and `address` are required. Missing fields return `400` with the exact field path. The dashboard also requires these fields when you create a practice. An order for an older practice without a phone or address returns `422`. Create each practice once. With a platform key, send its `practiceId` with each order. Use `externalId` for your own practice ID. The field is optional and accepts up to 128 characters. Affinity trims surrounding spaces. The value is case sensitive and must contain visible text on one line. An active practice of your platform cannot share an `externalId` with another active practice. A create or update with a used `externalId` returns `409` [`practice_already_exists`](/errors/practice-already-exists/). The response gives the existing practice ID in `data.practiceId`. Use that ID or send a different `externalId`. Concurrent creates with one `externalId` create one practice. Names and addresses do not identify a practice. Two practices can have the same name and address. Live access and the saved pharmacy-side record are per practice. The platform controls its practices' Live access and pays one weekly invoice for their Live orders. An independent practice pays its own invoice. Affinity staff control Live access for platforms and independent practices. Orders do not create practices from inline data. Platforms have no address. A platform can have an optional contact phone in Settings → Organization. This phone does not replace a practice's phone. The request returns `200` with the practice: ```json { "id": "prac_01j9z3k4m5n6p7q8r9s0t1v2w3", "externalId": "practice-42", "name": "Example Clinic", "phone": "+15125550123", "address": { "line1": "200 Example Ave", "line2": "Suite 4", "city": "Austin", "state": "TX", "postalCode": "78701" }, "liveEnabled": false, "createdAt": "2026-10-28T15:04:05.000Z" } ``` Keep the `id`. With a platform key, send it as `practiceId` in each order for this practice. Every practice response includes `externalId`. The value is `null` when no ID is set. A request without `Idempotency-Key` returns `400`. When a request times out, send it again with the same key and the same body. Affinity does not create a second practice. Affinity trims surrounding spaces from practice names, address lines and city names before saving. A blank apartment line becomes `null`. ## List and read practices - `GET /v1/practices` lists your practices, newest first. `query` searches by name. `sort` takes `name`, `location`, `mode` or `created`. A leading `-` reverses the order. - `GET /v1/practices?externalId=practice-42` matches the ID exactly, including case. - `GET /v1/practices/{practiceId}` reads one practice. - `PATCH /v1/practices/{practiceId}` changes `externalId`, `name`, `phone`, `address` or `liveEnabled`. Send only the fields that change and a new `Idempotency-Key`. Set, change or clear `externalId` with PATCH. Send `"externalId": null` to clear it. An omitted `externalId` keeps its current value. Retry an uncertain update with the same key and body. Affinity returns the original response without another update. A different body with the same key returns `409` `idempotency_key_reused`. Missing or invalid keys return `400`. A practice of another platform returns `404`. ## Archive a practice A platform admin deletes a managed practice in the dashboard. This action archives the practice in both Test and Live. API keys cannot delete practices. Reads, new updates and new orders for an archived practice return `404`. Live orders in `submitted` or `processing` block deletion with `409 orders_in_progress`. Wait for those orders to finish or cancel them. Existing orders remain available and keep their signed practice details. Their `practice.archivedAt` shows when the practice was archived. A replay of an earlier keyed practice update still returns its stored response. Archiving frees the practice's `externalId`. A new practice can use that value. ## Live access Practices are shared across Test and Live. After a practice has Live access, use a Live key to change its name, phone or address. A Test key gets `403` [`live_mode_required`](/errors/live-mode-required/), even if the supplied value is unchanged. A practice starts in Test. Test orders work at once. Live orders need Live access on the platform and on the practice: 1. Email [support@affinityrx.com](mailto:support@affinityrx.com) to request Live access. Affinity staff turn on Live access for your platform. 2. You turn on Live access for each practice. Send `"liveEnabled": true` on create or with `PATCH /v1/practices/{practiceId}`. Use a Live API key. Turning Live on and sending Live orders do not require a card or bank account on file. A Test key that changes `liveEnabled` gets `403` `live_key_required`. A platform without Live access gets `403` `platform_live_disabled` when it enables a practice. It can still disable Live access. When Affinity turns off Live access for a platform, new Live orders for its practices get `403` `mode_not_enabled`. `liveEnabled` shows effective access: both the platform and practice must have Live enabled. Restoring the platform's Live access restores access for practices whose own Live setting stayed enabled. To keep a practice out of Live after that, send `"liveEnabled": false` while the platform's Live access is off. Existing keys still read records, cancel orders and manage webhooks. Existing billing and webhook delivery continue. Read [Test and Live mode, and IDs](/guides/test-and-live-mode/). Source: https://docs.affinityrx.com/guides/practices/index.mdx If a response or a page is wrong or unclear, send `POST /v1/feedback` with an `Idempotency-Key`, a short message and the `requestId` from the response. Do not include patient information.