External Partner API
External Partner API
Section titled “External Partner API”Who this is for: admins, engineers/agents integrating outside tools, new hires.
The idea
Section titled “The idea”The care portal exposes a dedicated set of API endpoints (kept separate from its normal internal admin/provider/care-team routes) specifically for outside systems to call into. The main consumer today is the automated phone outreach assistant (see Messaging & notifications), which needs to look up and act on patient/case data mid-call.
What it can do
Section titled “What it can do”- Look up a patient by ID, email, or phone number (matching the last 10 digits so different phone formats all resolve to the same patient), optionally with their services/cases.
- Look up a patient’s services/cases, filterable by status or service type.
- Read and send messages in a case’s in-app conversation thread (see Messaging & notifications), including creating a new thread for a case if one doesn’t exist yet.
- Create a follow-up on a case (a reminder/nudge, optionally sent by email, text, and/or in-app message) — see Care team workflows.
- Work with reviews — pull the context needed to draft a review, generate a draft review, submit a rating, check existing reviews, and other review-flow steps (see Reviews & feedback).
Authentication
Section titled “Authentication”Every endpoint requires one of two pre-shared keys sent as an Authorization: Bearer header — an “internal API key” for most lookups/actions, or a separate “server-to-server token” for a subset of endpoints (currently the review-drafting ones). There is no per-partner login; access is all-or-nothing per key.
Open questions
Section titled “Open questions”- Whether any partner besides the automated phone outreach assistant currently calls this API was not confirmed.
- The exact criteria for which endpoints use the “internal API key” versus the separate “server-to-server token” (both grant broadly similar access) was not fully explained in the code — it may simply reflect when each endpoint was added.
Where this comes from
Section titled “Where this comes from”parkingmd-care-portal/src/app/api/v1/external/_helpers.tsparkingmd-care-portal/src/app/api/v1/external/patients/[patientId]/route.ts,.../patients/[patientId]/services/route.tsparkingmd-care-portal/src/app/api/v1/external/tasks/[taskId]/messages/route.tsparkingmd-care-portal/src/app/api/v1/external/followups/route.tsparkingmd-care-portal/src/app/api/v1/external/reviews/(draft/,context/,rating/,existing-reviews/,escalation/,feedback-tags/,items/,platforms/,media/upload/,photo-outline-default/,video-outline-default/,reward-decision/,service-review-content/)