PF Bridge API reference

PF Bridge APIThis reference needs JavaScript. The guides follow; the full description of every endpoint is in openapi.json.Getting startedPF Bridge gives your system an HTTPS and JSON API to one clinic's Practice Fusion (PF) account. You never handle PF's login: PF Bridge signs in for you, keeps the session alive, and your calls to /v1 use that session.This page takes you from nothing to a first successful call.What has to exist first

An organization for your company, with the clinic's business associate agreement (BAA) and the clinic's signed authorization to access its Practice Fusion account recorded. Until both are recorded no connection of the organization can sign in to PF, and its status stays login_failed.

A connection: one connection per clinic PF practice. The practice's PF login (the PF "bot" user) belongs to the connection.

Credentials for the connection, entered by whoever knows the PF user's password. You do not send them to us in an API call. An administrator creates a credential link in the console and passes it on. The person opens the link, enters the PF email and password, confirms the authorization checkbox and submits. The link works once and expires after 7 days.

A login: starts by itself after the credentials are saved. Practice Fusion may text a security code to the practice's two-step phone on the first login (and later when it does not recognize the session). Send it to POST /v1/login/security-code, or an administrator can type it into the console.

An API key created in the console. The secret is shown once, copy it then.

When the connection is signed in, GET /v1/status answers "loginState": "logged_in".Your first callsReplace the base URL with the address you were given and KEY with your key. Both calls are safe: they only read.BASE=https://api.example.com KEY=pfb_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 1. Is the connection signed in? (No Practice Fusion call, not limited by the connection limiter.) curl -s -H "Authorization: Bearer $KEY" $BASE/v1/status # 2. The practice's providers curl -s -H "Authorization: Bearer $KEY" $BASE/v1/providersIf the second call answers 503 with "error": "pf_not_ready", the connection is not signed in yet. Read loginState in the answer and see Connection status and states.Booking and messages are off at firstA new connection has bookingEnabled and messagesEnabled switched off. POST /v1/appointments answers 403 booking_disabled and POST /v1/messages answers 403 messages_disabled until a clinic administrator turns the switch on in the console (turning it on asks for a confirmation). GET /v1/status shows both switches.A typical integration

On start, and every few minutes, call GET /v1/status. Only call the other endpoints when apiReady is true.

Cache the catalog (/v1/providers, /v1/facilities, /v1/appointment-types, /v1/coverage-types) and refresh it now and then. These calls cost Practice Fusion calls, so do not call them for every user action.

Find the patient by MRN with GET /v1/patients/by-mrn/{mrn} (it also returns insurance). Use POST /v1/patients/search when you only have a name. Every answer carries patientId, which other endpoints use. Search results, GET /v1/patients/{patientId} and by-MRN all carry sms and insurance; a null there means Practice Fusion could not be read for it.

To list a day's appointments with their patients (every type and status, cancelled and no-show included), call GET /v1/schedule/appointments?date=YYYY-MM-DD.

Check the time with GET /v1/schedule/conflicts and book with POST /v1/appointments and an Idempotency-Key.

Handle errors by their error code: see Errors.

Trying calls from this pageEvery operation has a Test Request button. Paste your API key (only the key, starting pfb_live_) into the Bearer Token box under Authentication, check the address at the top of the request, and press Send. Do not add an Authorization header by hand: the page already sends one, and two of them make the call fail with 401. The request goes straight from your browser to that address, and the key is sent nowhere else. Leave X-Connection-Id empty unless you use an organization key. If the browser reports a network error, the API at that address may not allow requests from this page; use the curl examples instead.AuthenticationEvery /v1 call needs an API key in the Authorization header:Authorization: Bearer pfb_live_<43 characters>The form is strict: Bearer with a capital B, exactly one space, then the key. Keys are pfb_live_ followed by 43 characters of A-Za-z0-9_-. Anything else (a missing header, a malformed key, an unknown, revoked or expired key) answers the same way:{ "error": "unauthorized", "message": "Missing or wrong API key" }with status 401. The answer never says which of these it was.Connection keys and organization keys

Kind

Bound to

Extra header

Connection key

One connection (one clinic's PF practice). The connection comes from the key.

None. If you send X-Connection-Id it must be the key's connection, else 400 connection_mismatch.

Organization key

Your organization.

Send X-Connection-Id: conn_… on every /v1 call, naming one of your connections. Without it: 400 connection_required. An unknown connection: 404 connection_not_found.

curl -s -H "Authorization: Bearer $ORG_KEY" -H "X-Connection-Id: conn_01J8EXAMPLE0000000000000" $BASE/v1/statusScopesA key carries scopes. Each endpoint needs one; a key without it answers 403 forbidden_scope with requiredScope in the body.

Scope

Endpoints

status:read

GET /v1/status

catalog:read

GET /v1/appointment-types, /v1/facilities, /v1/providers, /v1/coverage-types, /v1/practice-contacts

schedule:read

GET /v1/schedule, /v1/schedule/appointments, /v1/schedule/conflicts

patients:read

POST /v1/patients/search, GET /v1/patients/by-mrn/{mrn}, GET /v1/patients/{patientId}, GET /v1/patients/{patientId}/insurance, GET /v1/appointments/{appointmentId}

appointments:write

POST /v1/appointments

messages:write

POST /v1/messages

login:write

POST /v1/login/security-code

A key created for integrations normally has all of these. Keys can also carry manage:* scopes for the management API, which is not part of this reference.Keeping keys safe

The secret is shown once, when the key is created. Store it in a secret manager, not in source code, and never in a browser or mobile app.

Send it only to your PF Bridge base URL, over HTTPS. The "Test Request" panel of this page sends your key only to the server shown at its top, and does not store it.

Keys can have an expiry date. An expired key answers 401.

Rotating a keyRotate in the console. Rotation creates a new secret. The old secret keeps working for a grace period (24 hours by default, at most 168 hours), then stops. Deploy the new secret during the grace period. To cut an old key off at once, revoke it instead: a revoked key answers 401 immediately.Paused connections and suspended organizationsWhen a clinic administrator or PF Bridge support pauses a connection, or the organization is suspended, calls with an organization key answer 403 connection_disabled or 403 org_suspended. Calls with a connection key answer 503 pf_not_ready with "loginState": "logged_out" instead, because that is the answer such clients already handle.Connection status and statesGET /v1/status describes the connection of your API key. It makes no Practice Fusion call and is not limited by the connection's rate limiter (only the per-key limit applies), so you can poll it. Poll every few minutes at most, and use Retry-After from other calls to decide when to try again sooner.curl -s -H "Authorization: Bearer $KEY" $BASE/v1/statusThe fields that matter

Field

Meaning

loginState

What the API can do now: see the table below.

loginStateSince

When loginState last changed.

sessionActive

true when loginState is logged_in.

apiReady

true when a session exists and it can make calls. Treat apiReady: false as "do not call PF-backed endpoints yet".

startedAt

When the current Practice Fusion session was obtained. A new login looks like a restart.

lastApiOkAt

The last successful Practice Fusion answer on this connection.

lastLoginAt

The last successful login.

bookingEnabled, messagesEnabled

The connection switches. false makes POST /v1/appointments or POST /v1/messages answer 403.

autoLogin

enabled is false while the connection is paused; credentialsSaved says whether credentials are stored.

twoFactor

awaitingCodeSince is set while a login waits for a security code (see Security codes). lastResult is logged_in, rejected, timeout or null.

limiter

The connection's rate limiter right now: see Rate limits.

connectionId

The connection this key resolves to (conn_…).

session

obtainedAt, refreshDueAt, and refresh.state (idle, queued, logging_in, awaiting_code, failed) for the background refresh of the session.

lastUnlockAt, unlockAttempts, reloads, loginAttempts, crashes and lastActivityAt are bookkeeping fields that carry no information you need. Ignore them. lastUnlockAt and lastActivityAt are always null, and unlockAttempts and reloads are always 0.loginState values

Value

Meaning

What to do

logged_in

A usable session exists. This stays true while the session is being refreshed in the background, even while a refresh waits for a code.

Call the API.

unknown

Never logged in and no login is running.

Wait, or ask the clinic administrator whether credentials were entered.

logging_in

A login is running.

Wait. Logins usually finish within a minute or two.

awaiting_code

The login is on Practice Fusion's security code page.

Send the code to POST /v1/login/security-code.

login_failed

Logins gave up and a person has to act: for example the PF email or password was rejected, no security code arrived in time, or the clinic's BAA or access authorization is not recorded yet.

Tell the clinic administrator to open the connection in the console, which shows the reason and offers a new credential link. Do not keep retrying.

logged_out

The session is gone and a new login is queued, or the connection is paused.

Wait. If it lasts, check with the clinic administrator.

locked, unlocking and unlock_failed are never reported.What pf_not_ready meansA PF-backed call made while no usable session exists answers:HTTP/1.1 503 Retry-After: 30 { "error": "pf_not_ready", "message": "Practice Fusion is not logged in yet", "loginState": "awaiting_code", "retryAfterSeconds": 30 }Nothing was sent to Practice Fusion. loginState tells you why. Wait for Retry-After seconds and try again. If loginState is awaiting_code, a security code is needed. If it is login_failed, a person has to act. Reads can be retried freely. For a booking, retry with the same Idempotency-Key.A session can also end by itself (Practice Fusion signs it out). Calls then answer 503 pf_session_rejected for a moment, a new login starts, and the connection returns to logged_in within a minute or two.ErrorsEvery failed call answers with a JSON body of the same shape:{ "error": "slot_taken", "message": "Practice Fusion reports a conflict at that time", "appointmentConflicts": 1, "blockedTimeConflicts": 0 }

error is the code. Branch on this, never on message.

message is a short sentence for people. It may change.

Some codes add fields (listed below).

Every answer carries an X-Request-Id header. Send your own X-Request-Id (up to 100 characters of A-Za-z0-9._:-) to correlate calls, and quote it when you ask for support. Answers carry Cache-Control: no-store, and X-Bridge-Version.Which errors to retry

Answer

Retry?

429 rate_limited

Yes. Wait Retry-After seconds plus 0 to 1 s of random jitter.

503 pf_not_ready

Yes. Wait Retry-After seconds.

502 and 504

Once, after a short pause. For POST /v1/appointments and POST /v1/messages read Idempotency and safe retries first.

Any other 4xx

No. Fix the request or the setup.

500 internal_error

Once after a pause, then report it with the X-Request-Id.

Request and authentication errors

Status

error

Extra fields

What it means and what to do

400

bad_request

A parameter or body field is invalid. The message says which.

400

bad_json

The body is not JSON. Send Content-Type: application/json.

400

connection_required

Organization key without X-Connection-Id.

400

connection_mismatch

Connection key with a different X-Connection-Id. Drop the header.

401

unauthorized

Missing or wrong API key. See Authentication.

403

forbidden_scope

requiredScope

The key lacks the scope. Ask for a key with it.

403

booking_disabled

Booking is off for the connection. A clinic administrator turns it on.

403

messages_disabled

Messages are off for the connection.

403

connection_disabled

Organization keys only: the connection is paused.

403

org_suspended

Organization keys only: the organization is suspended.

404

not_found

No such endpoint.

404

connection_not_found

The X-Connection-Id is not a connection of your organization.

405

method_not_allowed

Wrong HTTP method for the path.

413

body_too_large

The body is over 256 KiB.

Lookup errors

Status

error

When

404

provider_not_found

The provider is unknown or not schedulable.

404

facility_not_found

Unknown facility.

404

appointment_type_not_found

Unknown appointment type.

404

patient_not_found

Unknown patient (or no patient with that MRN).

409

patient_mrn_ambiguous

More than one patient has that MRN. Find the patient with POST /v1/patients/search and use GET /v1/patients/{patientId}.

404

appointment_not_found

Unknown appointment.

Booking and message errors

Status

error

Extra fields

What to do

400

start_in_past

Pick a future time (clinic time).

400

appointment_type_inactive

Pick an active appointment type.

400

any_time_disabled

Remove allowAnyTime. It is a testing switch and is off.

400

recipient_unknown

unknownRecipients

A message recipient is not in the practice's contacts. Refresh GET /v1/practice-contacts.

409

slot_taken

appointmentConflicts, blockedTimeConflicts

Practice Fusion reports a conflict. Pick another time.

409

outside_hours

The facility is not open for the whole appointment.

409

patient_inactive

The patient is inactive in PF.

422

idempotency_key_reused

The Idempotency-Key was used for a different request. Use a new key per booking.

502

pf_rejected_booking

pfStatus, pfDetail

Practice Fusion refused the booking. pfDetail is the start of its message (up to 500 characters).

502

booking_failed

pfStatus

The booking failed and the appointment is not in Practice Fusion. Safe to retry with the same key.

502

pf_rejected_message

pfStatus

Practice Fusion refused the message.

503

pf_user_unknown

The service cannot tell which PF user the session belongs to. Retry later; contact support if it stays.

504

booking_outcome_unknown

The booking may or may not exist. See Idempotency and safe retries.

Security code errors

Status

error

What it means

409

not_awaiting_code

No login of this connection is on the code page right now.

409

code_already_used

The same code was sent within the last hour.

422

code_rejected

Practice Fusion did not accept the code. Check it and try again; see Security codes.

Rate limit errors

Status

error

Extra fields

What it means

429

rate_limited

reason, retryAfterSeconds

See Rate limits. Also the Retry-After header. reason is busy, budget, pf_throttled or key_rate.

For organization keys, a plan with a hard usage cap can also answer 402 quota_exceeded (meter, periodEnd) when the cap is reached. Connection keys get 429 rate_limited with reason budget instead.Practice Fusion and session errors

Status

error

Extra fields

What it means

502

pf_error

pfStatus (optional)

Practice Fusion answered with an unexpected error, or the request failed. Retry once.

503

pf_not_ready

loginState, retryAfterSeconds

No usable session yet. See Connection status and states.

503

pf_session_rejected

pfStatus

Practice Fusion refused the session for this call. A new login starts by itself. Retry after a short wait.

504

pf_timeout

Practice Fusion did not answer within 20 seconds.

500

internal_error

A fault on our side. Quote the X-Request-Id.

Rate limitsPractice Fusion is a shared system that we reach through one signed-in session per connection, so every connection has its own limiter. It protects the clinic's PF account, not our servers. A limited call answers 429 with a body like:HTTP/1.1 429 Retry-After: 2 { "error": "rate_limited", "message": "Too many Practice Fusion requests in flight for this connection", "reason": "busy", "retryAfterSeconds": 2 }The Retry-After header and retryAfterSeconds carry the same number of seconds. Wait that long plus 0 to 1 second of random jitter, then retry. A limited call did nothing: it is always safe to repeat.The reasons

reason

Meaning

busy

Too many Practice Fusion requests are already running for the connection (4 at a time by default). Bookings also run one at a time per connection and wait briefly for their turn.

budget

The connection's budget of Practice Fusion calls is used up (120 per minute by default, with a burst of 40). Also answered to connection keys when the organization's plan has a hard cap.

pf_throttled

Practice Fusion itself answered "too many requests" (or timed out three times in a row). The connection pauses its calls for a while: Practice Fusion's own Retry-After if it sent one, otherwise 30 seconds, doubling up to 300 seconds.

key_rate

Your API key sent more than 50 requests per second (a burst of 100 is allowed). Checked first, before the connection or Practice Fusion is touched, on every endpoint including GET /v1/status and POST /v1/login/security-code.

ip_rate

Too many requests from one IP address. Only the credential page that clinic staff open to enter the Practice Fusion password uses it (30 page loads and 10 submits per minute); a /v1 call never gets it.

The per-key limitBesides the per-connection limiter, every API key may send 50 requests per second (a burst of 100). It exists to stop a runaway loop, and the defaults are far above what a normal integration sends. Over it you get:HTTP/1.1 429 Retry-After: 1 { "error": "rate_limited", "message": "Too many requests for this API key", "reason": "key_rate", "retryAfterSeconds": 1 }A call refused this way is not billed and did nothing, so it is safe to repeat after Retry-After. Another key of the same connection has its own allowance. Connection keys get exactly this body too (the reason value is new, the shape is the one you already handle).The numbers are defaults. The actual values for your connection are in the limiter block of GET /v1/status (maxInFlight, pfCallsPerMinute, burst, tokens left now, pfBackoffUntil, and counters of rejected calls by reason).What a call costsEach endpoint reserves a number of Practice Fusion calls up front and gives back what it did not use (a call that needs more is charged for what it really used). The costs are estimates. They are shown on every operation of the reference:

Endpoint

Cost

GET /v1/status, POST /v1/login/security-code

0 (never limited by the connection limiter; the per-key limit applies)

GET /v1/appointment-types, /v1/facilities, /v1/coverage-types, /v1/practice-contacts

GET /v1/providers

GET /v1/schedule

5 + (1 if facilityId is given, else 2) × ceil(days / 7)

GET /v1/schedule/appointments

3 + (1 if facilityId is given, else 2), plus 1 for each patient on the day (their insurance)

GET /v1/schedule/conflicts

POST /v1/patients/search

up to 17 (1, plus 2 for each of the first 8 results; the rest is refunded)

GET /v1/patients/{patientId}

GET /v1/patients/{patientId}/insurance

GET /v1/patients/by-mrn/{mrn}

GET /v1/appointments/{appointmentId}

POST /v1/appointments

POST /v1/messages

Good behaviour

Cache the catalog calls. Do not fetch them per user action.

Ask GET /v1/schedule for the range you need (at most 31 days), not one call per day. To see who is booked on a day, use GET /v1/schedule/appointments (one date, all patients) instead of looking patients up one by one.

Spread bulk work out: look patients up one at a time at a steady pace. A day with many patients makes GET /v1/schedule/appointments use many Practice Fusion calls (one per patient, for insurance), so do not call it in a tight loop.

Honour Retry-After. Retrying immediately only extends the wait.

The 503 pf_not_ready answer also carries Retry-After. Other answers do not send rate limit "remaining" headers.

Usage and plansEvery /v1 call except GET /v1/status and POST /v1/login/security-code counts towards your organization's usage. Ask your administrator about the limits of your plan.Idempotency and safe retriesNetworks fail between "sent" and "answered". Two calls change data in Practice Fusion: booking an appointment and sending a message. Both are built so that you can retry without doing it twice.Booking and the Idempotency-Key headerPOST /v1/appointments requires an Idempotency-Key header: 8 to 100 characters of A-Za-z0-9._:-. Without it the call answers 400 bad_request. Generate a new key for each booking you intend to make (a UUID is fine) and store it with your own record of that booking, so a retry can send the same key.curl -s -X POST $BASE/v1/appointments \ -H "Authorization: Bearer $KEY" \ -H "Idempotency-Key: booking-2026-11-16-jordan-0001" \ -H "Content-Type: application/json" \ -d '{"patientId":"3f2b7a10-5c1e-4d8a-9b61-0a7d2e4c8f11","providerId":"9c4e1d52-7a30-4b6f-8e21-5d0b3a7c9e44","facilityId":"b1d6e3a8-2f47-4c90-a5d3-6e8f0c1b7a22","appointmentTypeId":"5a8c2f90-1e6d-4b37-9d42-c7e0a3b5f166","start":"2026-11-16T10:00","durationMinutes":30}'Records are kept for 24 hours. The rules:

You send

Answer

The key for the first time

The booking runs. 201 with the appointment.

The same key and the same body again

The first 201 again, with "replayed": true. Nothing is booked twice.

The same key with a different body

422 idempotency_key_reused.

The same key while the first call is still running

The retry waits for the first call (up to 25 seconds) and answers with its result.

The same key after a failed call (any error except 504 booking_outcome_unknown)

The booking runs again. Failures are not remembered, so a retry can succeed.

"Same body" means the same booking after defaults are applied (for example, leaving out durationMinutes and sending the default value are the same).When the answer is lost or the call times out

No answer at all (your client timed out): retry with the same Idempotency-Key and the same body. You get either the stored result or a fresh attempt, never two appointments from one key.

201 with "recovered": true: Practice Fusion did not answer, but the appointment was found in its schedule. The booking succeeded.

502 booking_failed: Practice Fusion failed and the appointment is not there. Retry with the same key.

502 pf_rejected_booking: Practice Fusion refused the booking. Do not retry unchanged; read pfDetail.

504 booking_outcome_unknown: Practice Fusion did not answer and the schedule could not be checked, so we do not know whether the appointment exists. This answer is remembered for 24 hours, so repeating the same key returns the same 504. Do this instead:

Wait a few seconds, then read the provider's schedule with GET /v1/schedule (the day of the appointment) or check with GET /v1/schedule/conflicts for that provider, facility and time.
If the time is now busy with your appointment, treat the booking as done. (Practice Fusion's schedule is anonymous here: it does not show whose appointment it is. Compare with what you expect at that time.)
If the time is free, book again with a new Idempotency-Key. A second booking at the same time for the same provider is normally refused by Practice Fusion's own conflict check (409 slot_taken), which protects against a late first attempt.

504 pf_timeout on other endpoints: Practice Fusion did not answer within 20 seconds. For reads, retry once.

Messages and messageIdPOST /v1/messages has no header. It is de-duplicated on the messageId you put in the body, for 24 hours. A repeat of the same messageId returns the first answer with "replayed": true and sends nothing.

Generate one messageId (a GUID) per message and keep it for retries. Use a new threadId for a new conversation and reuse it to continue one.

A failed call is forgotten, so retrying the same messageId after an error sends the message again.

There is no endpoint to look up whether a message was sent. After a 504 pf_timeout the outcome is unknown: retrying may deliver the message twice. Decide whether a duplicate internal message is acceptable before retrying.

Reads and security codesGET calls and the searches change nothing and can be retried at will within the rate limits. POST /v1/login/security-code is safe to retry: a code is used once (409 code_already_used for the same code within an hour).Security codesPractice Fusion protects logins with a two-step code that it texts to the practice's phone. PF Bridge asks for one whenever Practice Fusion does: on the first login of a connection, and later whenever Practice Fusion does not recognize the signed-in browser. This is rare for a connection that has been running for a while, but your integration should handle it.How you know a code is needed

GET /v1/status shows loginState: "awaiting_code", and twoFactor.awaitingCodeSince is set.

During a background refresh the connection stays logged_in (calls keep working) but twoFactor.awaitingCodeSince is set. A code is accepted then too.

A PF-backed call answers 503 pf_not_ready with loginState: "awaiting_code".

Submit the codecurl -s -X POST $BASE/v1/login/security-code \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -d '{"code":"482913"}'The code is 4 to 6 digits, sent as a string. The key needs the login:write scope. This call is not limited by the connection's rate limiter (only the per-key limit applies) and does not need a signed-in session.

Answer

Meaning

200 { "result": "logged_in" }

Practice Fusion accepted the code and the connection is signed in.

422 code_rejected

Practice Fusion did not accept the code (typo, expired, or an older code). Read the newest text and send it again.

409 not_awaiting_code

No login of this connection is on the code page. Check GET /v1/status and try again when awaiting_code shows, or the login may have just ended.

409 code_already_used

The same code was sent within the last hour.

400 bad_request

The code is not 4 to 6 digits.

504 pf_timeout

The login worker did not answer in time. Check GET /v1/status before sending the code again.

A call can take up to about 19 seconds, because the login may still be reaching the code page and Practice Fusion then verifies the code. Set your client timeout to 20 seconds or more.Where codes come fromThe code goes to the PF user's phone. Your system can read it and post it to this endpoint (for example, from an SMS provider webhook). An administrator can also type the code into the console. Whichever way a code arrives, it is used once.Do not log the codeDo not write security codes to logs. PF Bridge never logs them either.Versioning and changelogVersioningThe API is versioned in the path: everything here is /v1. Every answer carries X-Bridge-Version with the service version (for example 1.0.0).Within /v1:

New fields may be added to answers, and new optional request fields or new error codes may appear. Ignore fields you do not know, and treat an unknown error code like the closest known status.

Breaking changes (removing or renaming a field, changing a meaning) would ship as /v2. /v1 would keep working for at least 12 months after that.

Machine-readable specThe OpenAPI 3.1 file this page is built from is published next to it as openapi.json. It is generated from the code, so it always matches the API.Changelog

Version

Change

1.0.0

First release: status, catalog, schedule (busy time, the appointments of one date, conflicts), patients (search, by MRN, by id, insurance), appointments, messages and security code endpoints.