Skip to main content

​
Overview

Creating an encounter in Wizlo requires assembling specific identifiers for the clinic, patient, treatments (products), and documents. Unlike simple flat payloads, the Wizlo API relies on relational UUIDs to ensure data integrity. This guide outlines the flow to “translate” external request data (such as a patient intake form submission) into a valid Wizlo POST /encounters request.

​
Prerequisite: Authentication

All API calls in this flow require a valid Machine-to-Machine (M2M) Access Token.
  1. Endpoint: POST /oauth/token
  2. Action: Exchange your client_id and client_secret for an access_token.
  3. Usage: Include Authorization: Bearer <access_token> in the headers of all subsequent requests.
See the Generate M2M Token reference for details.

​
Step 1: Get Clinic ID

Goal: Resolve the “Clinic Object” or “Clinic Name” to a Wizlo clinicId. You need the unique UUID of the clinic where the encounter is being scheduled.
  • API Reference: List Clinics
  • Method: GET /clinics?search={clinic_name}
  • Logic: Search for the clinic by name or legal name.
  • Extraction: From the response data array, select the matching clinic and extract its id.

​
Step 2: Identify or Create Patient

Goal: Resolve the “Patient Object” to a Wizlo patientId. Wizlo requires a patientId (UUID) to link the encounter. You must determine if the patient already exists or create a new profile.

​
A. Check / Create Patient

  • API Reference: Create Patient
  • Method: POST /clients
  • Payload: Map the patient’s demographic data (Name, Email, DOB, Phone).
  • Logic:
    1. Attempt to create the patient.
    2. Success (201): Extract user_id from the response.
    3. Conflict (409): The patient exists. Use GET /clients?email={email} (or similar search) to retrieve the existing user_id.

​
Step 3: Select Products (Treatments)

Goal: Map “Product IDs” to Wizlo treatmentIds. The encounter payload requires an array of treatmentIds (which correspond to Product UUIDs in the catalog).
  • API Reference: List Products
  • Method: GET /tenants/products?search={sku_or_name}
  • Logic:
    1. Search for the product using the external product_id (SKU) or name.
    2. Verify the product is active (isActive: true).
    3. Extract the id (UUID) from the response.
  • Output: An array of UUIDs, e.g., ["45ab34be-8d6e..."].

​
Step 4: Upload Documents (Optional)

Goal: specific URLs (Intake, Lab, ID) →\rightarrow Wizlo documentIds. If your source data includes URLs to PDF files (e.g., intake_upload_url, ID_upload_url), you must upload them to Wizlo to attach them to the encounter.
  • API Reference: Upload Document from URL
  • Method: POST /clients-documents/{patientId}/upload-url/{documentType}
  • Inputs:
    • patientId: From Step 2.
    • documentType: Map based on file content (e.g., intake-forms, lab-results, id-card).
    • url: The source URL of the file.
  • Logic: Loop through your available URLs, upload each, and collect the returned documentId.
Source FieldWizlo Document Type
intake_upload_urlintake-forms
lab_upload_urllab-results
ID_upload_urlid-card
gfe_upload_urlgfe-forms

​
Step 5: Create Encounter

Goal: Submit the final payload. Assemble all IDs collected in the previous steps into the final request.
  • API Reference: Create Encounter
  • Method: POST /encounters
  • Headers: Authorization: Bearer <token>, Content-Type: application/json

​
Field Mapping

External FieldWizlo FieldNotes
Clinic ObjectclinicIdRequired (Step 1)
Patient ObjectpatientIdRequired (Step 2)
Product IDstreatmentIdsRequired. Array of UUIDs (Step 3)
Upload URLsdocumentIdsOptional. Array of UUIDs (Step 4)
GFE TypereviewTypeRequired. E.g., “synchronous”
N/AserviceQueueHardcode: "provider_network"
AppointmentscheduledDayOptional. Format: YYYY-MM-DD
AppointmentscheduledTimeOptional. Format: HH:MM:SS
Diagnosis/VitalsadditionalNotesOptional. Append text here

​
Example Request

{
  "clinicId": "5468f02f-37d4-47bc-a474-7f15748ec9a8",
  "patientId": "a8912dbe-137c-4d9e-8785-84bd1ef298f3",
  "reviewType": "asynchronous",
  "serviceQueue": "provider_network",
  "treatmentIds": [
    "45ab34be-8d6e-4037-a0e3-a60b45169f09"
  ],
  "documentIds": [
    "c1814499-8db8-a017-9b58-952679d6d3bd"
  ],
  "scheduledDay": "2025-12-13",
  "scheduledTime": "14:30:00",
  "scheduledTimeZone": "America/New_York",
  "additionalNotes": "Patient reports mild hypertension. Weight: 180lbs."
}
Fields like order_id and Local Pharmacy are not required. The order is generated automatically by Wizlo upon encounter completion, and the pharmacy is determined by the selected Product settings.