Getting Started

Connect your applications and services with DrCare247 using our APIs and integration tools. Create and manage members, schedule consultations, access prescriptions, order laboratory tests, and retrieve results - all through a unified integration experience.
Stay informed with real-time webhook notifications and enable seamless patient access to the DrCare247 portal through Single Sign-On (SSO).

Get your credentials

DrCare247 provides the following credentials and URLs during onboarding. Keep credentials secure and use the issued values on your requests.

Item	Used for
AppId, AppSecret	Identify your application on every API call. Keep AppSecret private.
API user (email and password)	Sign in and obtain an access token
Registered Origin	Identifies your DrCare247 account on every API call. Use the exact issued value.
API host	Where you send API calls. In the examples, replace {api-host} with it
Patient portal host	The address of the DrCare247 patient portal. Your SSO links point here

Need API credentials?

Email [email protected] with your organization name, technical contact, and required integrations (Schedule API, Lab API, Webhooks, or SSO).

During onboarding, DrCare247 will provide your AppId, AppSecret, API user, registered Origin, API host, and patient portal host. To configure webhooks, also provide your endpoint and signing secret; see Set up webhooks.

Set up webhooks

To receive member, appointment, and lab notifications, give DrCare247 an HTTPS endpoint URL, a signing secret, and a receiver name. See Webhooks → Setting up.

Recommended: Set up webhooks before your first API call

Register the endpoint first if you want to receive the MemberCreated event for the member you create in step 4.

Events you'll receive

Area	Events
Member	MemberCreated, MemberUpdated
Appointment	AppointmentCreated, AppointmentUpdated (later changes, including Completed and Cancelled)
Lab	LabOrderCompleted, if you order labs

Your receiver must

• Verify the X-Webhook-Signature header
• Reply with any 2xx status within 30 seconds
• Handle the same event arriving more than once

See Webhooks for payloads, signature verification and retries.

Log in

Sign in with your API user to obtain the Bearer token required for subsequent API requests.

POST /api/auth/login

curl -X POST "https://{api-host}/api/auth/login" \
  -H "AppId: {AppId}" \
  -H "AppSecret: {AppSecret}" \
  -H "Origin: {registered Origin}" \
  -H "Content-Type: application/json" \
  -d '{ "username": "{api user email}", "password": "{password}" }'

Token is indata

Send it on every other call asAuthorization: Bearer {token}

Same Origin, every call

Send the same Origin used at login with every authenticated request. A different Origin results in HTTP 401. When your token expires, log in again.

See Authenticate API User.

Create the member

Before booking a consultation through the API, create the patient as a member and save the returned member ID.

POST /api/v1/Member/create

curl -X POST "https://{api-host}/api/v1/Member/create" \
  -H "AppId: {AppId}" \
  -H "AppSecret: {AppSecret}" \
  -H "Origin: {registered Origin}" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "member": {
      "firstName": "Jane",
      "lastName": "Doe",
      "dob": "1990-04-12",
      "gender": "F",
      "email": "[email protected]",
      "phone": "5551234567",
      "refId": "YOUR-PATIENT-1001"
    }
  }'

The response includes the new member's DrCare247 ID in data.id. Use it as memberId when you book the consultation.

Booking through SSO instead?

This step is optional. When a patient signs in through Single Sign-On, DrCare247 first looks for an existing patient-portal login with their email, then for a member whose refId is your patient id (user_id), and creates a new member only if neither matches. You receive a MemberCreated webhook only when a new member is created.

If you create the member here first, send your SSO user_id as refId so that SSO finds the same member. If the ids differ, SSO tries to create a second member with the same email, and the sign-in fails with code 659.

Send your own patient id as refId

You can then look the member up by your own id with Get Member. Member webhooks include it as RefId when DrCare247 has it, but it can be null, so match webhooks on MemberId.

Patient ids that look like UUIDs or contain @

Get Member treats a value that looks like a UUID as a DrCare247 member id, and a value that contains @ as an email address. So a refId in either form can't be looked up. Add a prefix (for example ACME-1001), or look the member up by its DrCare247 id instead.

Address required? Avoid code 707

If your account is set up to require an address, also send contact (address1, cityName, state, postalCode). Send state as the state code, for example TX. Otherwise the call is rejected with code 707.

See Create Member.

Book the consultation

After creating the member, choose between booking in the patient portal (SSO) and booking through your application (API). Each booking has two distinct IDs:

• The appointment is the booking itself. Webhooks call its id appointmentId.
• The consultation is the visit record that holds the outcome. Webhooks call its id consultationId.

Choose the way that fits your product:

Option A

SSO into the DrCare247 portal

When to use it

The patient books, completes intake and pays in the DrCare247 patient portal.

How

Redirect the patient to:

/sso?code=…&action=create_appt&refid={your order id}&params=…

Single Sign-On →

Option B

Create Appointment API

When to use it

You collect everything in your own UI and take payment yourself.

How

POST /api/v1/Schedule/createappointment

with memberId, residingState and statusId. All three are required.

Create Appointment →

Either way, give every order its own reference

Send it as refid on the SSO link, or as extRefId on Create Appointment. Appointment webhooks return it as ExtRefId (capital E). Use a new value for every booking.

Get prescription and lab results

When AppointmentUpdated arrives with status: "Completed", use the webhook consultationId to get the consultation. The response includes its prescriptions and labOrders:

GET /api/v1/Encounter/get

curl -X GET "https://{api-host}/api/v1/Encounter/get?Id={consultationId}" \
  -H "AppId: {AppId}" \
  -H "AppSecret: {AppSecret}" \
  -H "Origin: {registered Origin}" \
  -H "Authorization: Bearer {token}"

Missed a webhook? Reconcile with your own reference

You can also find the consultation by its external order reference: ?extAptRefId={your order id}. Use the extRefId from Create Appointment or the refid from the SSO link.

For a lab order you placed with Create Lab Order, wait for the LabOrderCompleted webhook and read the results with Get Lab Result (GET /api/v1/LabOrder/result). Get Lab Order returns the order and its status, not the results.

Things that trip up a first integration

What you see	Why, and what to do
401 with an empty body	The token has expired or was ended by logging out, you sent a different Origin from the one you logged in with, or you sent no Authorization header. Log in again and send the token with the same Origin on every call.
401 with the text Specified AppId or User is not authorized to use this resource.	The AppId header is not the AppId the token was issued to, or the token is not a valid JWT. Send the AppId you logged in with, and the token exactly as returned.
Create Appointment rejected with 477	statusId is missing or not allowed. Send 1 (Scheduled), 6 (Requested) or 7 (Pending).
Create Appointment rejected with 249 or 248	With statusId 1 or 6, you must send consent (otherwise 249). Whenever you send consent, every item must have isAgreed: true (otherwise 248).
Get Lab Order returns 404	The route is GET /api/v1/LabOrder, without /get.
An HTTP 200 that isn't a full success	Create Lab Order returns 691 for a duplicate order, and Get Lab Result returns 512 when the result isn't ready yet. Both come with HTTP 200. Always read the code.
The code is not where you expect it	Read status first, then the code from messages[0].code. See Read responses reliably in the API reference and Response Codes.

WebhooksPayloads, signatures, retriesSingle Sign-OnLink format, token endpoint, errorsAPI referenceEvery endpoint, field and code