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

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. 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:

{
  "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, 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 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.