How Do I Create an Exam Invite in API? – Clinic Knowledgebase

Need to automate sending exam invites? Qualiphy’s API lets you create and send exam invites programmatically.

Why it matters:

Creating exam invites through the API helps integrate this step into your clinic’s workflow, saving time and reducing manual efforts.

To create an exam invite via the API:

To send a POST request to create an exam invite use the endpoint below:

POST /api/exam_invite/

This endpoint is used to send an exam invitation to a patient. This allows healthcare providers to schedule exams and notify patients via email, integrating the invitation process into their workflow. The endpoint accepts details about the patient, such as their name, contact information, and exam specifics, and can optionally include additional information like callback URLs and extra patient data. This endpoint streamlines the scheduling and communication process, ensuring that patients receive timely invitations and relevant information about their scheduled exams.

Note: Only 1 prescriptive exam may be completed at a time.

Refer to the specifics below:

Example Request Payload:

{
  "api_key": "your_api_key",
  "exams": [
    1,
    2,
    3
  ],
  "first_name": "John",
  "last_name": "Doe",
  "email": "johndoe@example.com",
  "dob": "1990-06-30",
  "phone_number": "+15552223344",
  "webhook_url": "https://example.com/webhook",
  "additional_data": "{}",
  "redirect_approve": "https://example.com/approve",
  "redirect_reject": "https://example.com/reject",
  "redirect_na": "https://example.com/na",
  "redirect_missed": "https://example.com/missed",
  "dmv_license_number": "D1234567",
  "address_line_1": "123 Main St",
  "address_line_2": "Apt 4B",
  "city": "New York",
  "state": "NY",
  "zip_code": "10001",
  "shipping_address_line_1": "123 Main St",
  "shipping_address_line_2": "Apt 4B",
  "shipping_city": "New York",
  "shipping_state": "NY",
  "shipping_zip_code": "10001",
  "patient_address_prefill": 1,
  "gender": 1,
  "tele_state": "NY",
  "pharmacy_id": 1,
  "exam_pos_id": 1
}

Parameters:

api_key (string) - Required: API key for authentication
exams (array [integer]) - Required: List of exam IDs
first_name (string) - Required: Patient's first name
last_name (string) - Required: Patient's last name
email (string) - Required: Patient's email address
dob (string) - Required: Patient's date of birth (YYYY-MM-DD)
phone_number (string) - Required: Patient's phone number (10 digits or +1)
webhook_url (string) - Optional: Webhook URL for callback
additional_data (string) - Optional: Additional data (stringified)
redirect_approve (string) - Optional: Redirect URL on approve
redirect_reject (string) - Optional: Redirect URL on reject
redirect_na (string) - Optional: Redirect URL on not available
redirect_missed (string) - Optional: Redirect URL on missed exam
dmv_license_number (string) - Optional: DMV license number
address_line_1 (string) - Optional: Address line 1
address_line_2 (string) - Optional: Address line 2
city (string) - Optional: City
state (string) - Optional: State (capital abbreviation)
zip_code (string) - Optional: ZIP code
shipping_address_line_1 (string) - Optional: Shipping address line 1
shipping_address_line_2 (string) - Optional: Shipping address line 2
shipping_city (string) - Optional: Shipping city
shipping_state (string) - Optional: Shipping state (capital abbreviation)
shipping_zip_code (string) - Optional: Shipping ZIP code
patient_address_prefill (integer) - Optional: 1 - no prefill, 2 - prefill all address info
gender (integer) - Optional: Gender (1=Male, 2=Female, 3=Prefer not to say)
tele_state (string) - Optional: Telehealth state (capital abbreviation)
pharmacy_id (string) - Optional: Unique id for partner pharmacy when using prescription services.
exam_pos_id (string) - Optional: Unique id for partner pharmacy treatment packages when using prescription services.

Request Fields:

Field	Explanation
exams	You will need to pass here an array of exam ids provided on the previous screen. Therefore you may send multi-exams, which will all be linked to a single meeting.
dob	This is the patient’s date of birth field and needs to be sent in the following format. YYYY-MM-DD ie. 1990-06-30
phone_number	This is the patient’s phone number which will be used to text them an invite unless it is disabled via our platform. We support only the following two formats. +15552223232 or 1234567890
webhook_url	This is the url to be used in which you want Qualiphy’s platform to send back data upon exam completion. You will be getting a POST call to this url.
additional_data	This field allows for you to send data in a stringified format that is specific to your software, whether it be IDs or other crucial information for mapping results and generated PDFs into your own code.
redirect_approve redirect_reject redirect_na redirect_missed	Each potential status for our screenings along with missed calls due to no provider availability will allow you to set a different url for redirect. This will allow you to set the experience for your patients post screening completion on our platform.
address_line_1 address_line_2 city state zip_code	This is the patient’s home address.
shipping_address_line_1 shipping_address_line_2 shipping_city shipping_state shipping_zip_code	This is the patient’s shipping address and will be used for sending prescriptions for RX screened exams.
patient_address_prefill	This field is only required if you are passing an RX exam as we will require the collection of addresses for shipping purposes. When setting the value of this field to 2 then prior to the screening the patient will need to add their own home and shipping address, otherwise with a value of 1 they will not be asked for it. Regardless of address required, you can pass in address and set this to 2 if you want the patient to input their address prior to the screening.
gender	The values expected based on the patient’s gender is the following: (1 = Male, 2 = Female, 3 = Prefer Not to Say)
tele_state	Telehealth clinic types will be required to pass in states in which they want the patient to be screened. The format will be as a two letter uppercase abbreviation of the state. Capital Abbreviation i.e NY = New York
pharmacy_id	If you are using an exam that is of RX type 2, then you will include the pharmacy id for the pharmacy you want to select.
exam_pos_id	If you are using an exam that is of RX type 2, then you will include treatment package id for the selected treatment package.

Responses:

Status Code: 200 - Successful response

{
  "http_code": 200,
  "meeting_url": "https://app.qualiphy.me/meeting/example-id",
  "meeting_uuid": "example-id",
  "patient_exams": [
    {
      "patient_exam_id": 4844,
      "exam_title": "GFE Test",
      "exam_id": 800
    }
  ]
}

Status Code: 400 - Invalid Request

{
  "error_message": "Invalid Request."
}

Status Code: 401 - Unauthorized access

{
  "error_message": "Unauthorized access."
}

Status Code: 500 - Server error

{
  "error_message": "Something went wrong. Please try again later."
}

Status Code: 401 - To integrate a new Patient Care Provider, you will need to add them through the Qualiphy Portal, ensuring that all relevant details

{
  "http_code": 401,
  "error_message": "Need to add Patient Care Provider via Qualiphy Portal!"
}

Status Code: 401 - You need to signed docusign and signed rx

{
  "http_code": 401,
  "error_message": "Need to sign contract!"
}

Status Code: 401 - Need to sign Prescriptive Services Contract via Qualiphy Portal!

{
  "http_code": 401,
  "error_message": "Need to sign Prescriptive Services Contract via\nQualiphy Portal!"
}

Response Fields:

Field	Explanation
http_code	200
meeting_url	This is the meeting link that will be used for the exams.
meeting_uuid	This is the meeting unique id.
patient_exams	An array of patient exams, where each object contains patient_exam_id, exam_title, and exam_id.

Example Request Payload:

Parameters:

Request Fields:

Responses:

Response Fields:

Related articles