hlthstack API (1.0.0)

Download OpenAPI specification:

URL: https://www.hlthstack.io/ License: MIT

Partner REST API for health checkups, lab tests, doctor consultations, ePharmacy, benefit wallets and member pre-registration.

The hlthstack API lets partners book and manage health benefits for their members: health checkups and lab tests, in-clinic and online specialist consultations, ePharmacy orders, and benefit wallet balances. Status changes are pushed to you through webhooks (see the webhooks section).

Authentication. Call getAccessToken with HTTP Basic credentials issued by hlthstack. It returns a bearer token valid for 1 hour. Send it as Authorization: Bearer <token> on every other call. Multi-entity partners also send API-ENTITY-ID and API-SECRET-KEY.

Pre-registration (tag Pre-registration) uses its own credentials and token: call getPreRegistrationAccessToken with HTTP Basic and send the token as X-EKINCARE-KEY.

Conventions.

  • Request and response bodies are JSON unless stated otherwise (vouchers are PDF, some uploads are multipart).
  • Date-times are ISO 8601. Send appointment_date_time in UTC (2030-01-15T03:30:00Z).
  • plan_id, wherever accepted, is the plan identifier hlthstack shares at onboarding (a string). It is optional; when omitted, the entity's base plan is used.
  • Any unhandled error is returned as 422 {"errors":{"messages":["..."]}}.

Input validation. Request schemas encode the checks the server applies to the input itself (required, enum, pattern, minLength, maximum, minItems, ...). Patterns are ECMAScript/Python regexes and are matched as a search, as JSON Schema specifies: a pattern is anchored (^...$) only where the server anchors it. Rules that span fields or need the current date are listed on the operation under x-hlthstack-rules, each {rule, description, fields}, where rule is one of the kinds in x-hlthstack-rule-kinds and fields are dotted paths (customers[].dob). Checks that depend on stored data (plan benefits, slot availability, provider capability) are not encoded and are reported by the server.

Guides: https://github.com/hlthstack/integration-guide/tree/main/docs. Getting started: https://github.com/hlthstack/integration-guide/blob/main/docs/getting-started.md.

Postman. Import the collection (https://developers.hlthstack.io/postman/hlthstack.postman_collection.json) and the staging (https://developers.hlthstack.io/postman/hlthstack-staging.postman_environment.json) or production (https://developers.hlthstack.io/postman/hlthstack-production.postman_environment.json) environment, then fill in your credentials. Tokens are fetched for you.

Authentication

Obtain a bearer access token.

Get an access token

Exchanges the username and password issued by hlthstack (HTTP Basic) for a bearer token. The token expires 1 hour after issue (expires_at). Request a new one before it expires; there is no refresh token.

Authorizations:
basicAuth

Responses

Response samples

Content type
application/json
{
  • "access_token": "YOUR_ACCESS_TOKEN",
  • "expires_at": "2026-01-15T07:16:21Z"
}

Health Checkups

Providers, slots and appointments for health checkups, lab tests, dental, vision and vaccinations.

Appointment status changed or reports uploaded Webhook

Sent to your status_updates endpoint on every appointment status change. type is reports_upload when the appointment is partially_received/received and report links are present, otherwise status_update. Verify the Signature header (see the webhooks guide). Reply 2xx within 30 seconds.

Authorizations:
bearerAuth
header Parameters
Signature
required
string

HS256 JWT signed with your webhook secret. See the webhooks guide for the claims.

Request Body schema: application/json
required
type
string
Enum: "status_update" "reports_upload"
booking_id
string
appointment_id
string
customer_id
string

hlthstack's customer id.

customer_name
string
mobile_number
string or null
api_customer_id
string or null

Null for bookings hlthstack's team made on a member's behalf.

member_id
string or null

Member's employee id, when known.

appointment_date_time
string <date-time>
event_timestamp
number

Epoch seconds of the status change.

booking_source
string or null

Channel the booking was made through, fixed at booking time. hlthstack-api for bookings made through the hlthstack API hosts.

service_type
string

The benefit, e.g. ahc, inclinic_consultation.

plan_id
string or null
customer_plan_id
integer or null

Subscription that paid; null on the base plan.

subscription_id
string or null
status
string (AppointmentStatus)

Appointment status. Health checkups: payment_pending, new, confirmed, rejected, noshow, cancelled, rescheduled, completed, verification_required, partially_received, received. Consultations: new, confirmed, rejected, noshow, cancelled, rescheduled, completed, received. Treat unknown values gracefully.

status_text
string
comment
string or null
provider_id
integer
provider_name
string or null
provider_branch
string or null
provider_address
string or null
voucher_api_url
string <uri>

Present once the appointment is confirmed.

phlebo_name
string

Present once confirmed, if a phlebotomist is assigned.

phlebo_number
string
reports
Array of strings <uri> [ items <uri > ]

Present in partially_received and received.

doctor_id
string
doctor_name
string
doctor_specialities
Array of strings
doctor_gender
string or null
doctor_qualification
string or null
doctor_languages
Array of strings
doctor_experience
integer or null
object or null (FileLink)
Array of objects or null (FileLink)
latitude
number or string or null
longitude
number or string or null
hospital_name
string or null
hospital_location
string or null
hospital_address
string or null
meeting_link
string or null

Video consultations only.

object (AppointmentPayment)

Responses

Request samples

Content type
application/json
{
  • "booking_id": "EKI0000000001700000000",
  • "appointment_id": "APT1A2B3C4D5",
  • "customer_id": "EKI000000001",
  • "customer_name": "Jane Doe",
  • "mobile_number": "9999999999",
  • "api_customer_id": "CUST1001",
  • "member_id": "EMP0001",
  • "appointment_date_time": "2030-01-15T02:30:00Z",
  • "event_timestamp": 1768440000.123,
  • "booking_source": "hlthstack-api",
  • "service_type": "ahc",
  • "plan_id": "EXAMPLE_PLAN",
  • "customer_plan_id": null,
  • "subscription_id": null,
  • "status": "confirmed",
  • "status_text": "Confirmed",
  • "comment": "Your appointment is confirmed.",
  • "provider_id": 1001,
  • "provider_name": "Example Diagnostics",
  • "provider_branch": "Madhapur",
  • "provider_address": "1 Example Road, Madhapur, Hyderabad",
  • "phlebo_name": "John Doe",
  • "phlebo_number": "+919999999999",
  • "type": "status_update",
  • "payment": {
    }
}

Digitized lab results available Webhook

Sent to your separately registered lab_results endpoint (enabled on request).

Authorizations:
bearerAuth
header Parameters
Signature
required
string

HS256 JWT signed with your webhook secret. See the webhooks guide for the claims.

Request Body schema: application/json
required
type
string
Value: "lab_results"
booking_id
string
appointment_id
string
customer_id
string
api_customer_id
string or null
member_id
string or null
plan_id
string or null
object

Responses

Request samples

Content type
application/json
{
  • "type": "lab_results",
  • "booking_id": "EKI0000000001700000000",
  • "appointment_id": "APT1A2B3C4D5",
  • "customer_id": "EKI000000001",
  • "api_customer_id": "CUST1001",
  • "member_id": null,
  • "plan_id": "EXAMPLE_PLAN",
  • "digitization": {
    }
}

List providers

Lists providers (diagnostic centres, clinics, doctors) near a location that can serve the given packages, ordered by distance. Use listSlots for availability: the provider_slots embedded here is deprecated.

Either pincode or both latitude and longitude are required (if only coordinates are sent the pincode is derived from them). sort_by and gender are supported only for service_name=inclinic_consultation.

Authorizations:
bearerAuth
query Parameters
service_name
required
string (BenefitType)
Enum: "ahc" "dental" "vision" "fitness" "pharmacy" "eap" "family_doctor" "pre_employment" "covid_vaccination" "flu_vaccination" "other_health_checks" "rtpcr" "specialist_consultation" "pregnancy_care" "ohc" "annual_calendar" "health_coach" "health_insurance" "face_to_face_consults" "daycare_surgeries" "ambulance_on_demand" "supplementary_insurance" "elder_care" "home_care" "healthcare_financing" "nhc" "diet_consultation" "inclinic_consultation" "fertility_treatment" "consultation24x7" "imaging_services" "occupational_medical_rooms" "cancer_screening" "onsite_camp" "filler_benefit_one" "filler_benefit_two" "filler_benefit_three" "filler_benefit_four" "prescribed_diagnostics" "ppmc" "weight_management_program" "diabetic_program" "bp_program" "cervical_vaccination" "physiotherapy" "prescribed_diagnostics_flow" "vision_wearable" "maternity_care" "gym_subscription" "fitness_products" "wellbeing_marketplace" "pcos_program" "parenting_program" "midlife_health_program" "general_health_program" "fertility_care" "cholesterol_program" "financial_wellbeing"

The service to search for. Common values: ahc (health checks), dental, vision, flu_vaccination, covid_vaccination, inclinic_consultation. The value must be a known benefit type (see BenefitType), and the service must be enabled for your plan (otherwise 403). benefit_type is accepted as an alias.

package_ids
required
string[0-9]+(,[0-9]+)*
Example: package_ids=1001,1002

Comma-separated package ids shared at onboarding, for example 1001,1002. Each id must be a package of the requested benefit. The pattern is the server's own, unanchored check.

pincode
string^[0-9]{6}$
Example: pincode=500081

6-digit pincode. Required unless latitude and longitude are sent (the pincode is then derived from them).

latitude
number
Example: latitude=17.4437

Decimal latitude. Required unless pincode is sent. When no pincode can be derived from the coordinates, the value must be non-negative and include a decimal point (for example 17.0, not 17).

longitude
number
Example: longitude=78.386

Decimal longitude. Required unless pincode is sent. When no pincode can be derived from the coordinates, the value must be non-negative and include a decimal point.

radius
number
Default: 100

Search radius in km for in-clinic providers. Default 100.

auto_allocate_provider
boolean

Home-collection packages only. Let hlthstack allocate the best provider by availability. The appointment is cancelled if no provider is available at the location, and the slot may change if no provider is free at that time.

plan_id
string

Plan identifier shared at onboarding. Defaults to the base plan.

page
integer
Default: 1

Page number. Values below 1 are read as 1.

per_page
integer <= 50
Default: 20

Page size, at most 50. Values below 1 are read as 1.

sort_by
string
Enum: "fee" "experience" "distance" "rating" "visited_before"

In-clinic consultations only. visited_before also needs api_customer_id.

sort_asc
boolean

In-clinic consultations only. Default ascending for fee/distance, descending for experience/rating.

gender
string^(?:[Mm][Aa][Ll][Ee]|[Ff][Ee][Mm][Aa][Ll][Ee]...
Examples: gender=Male gender=Female gender=Non-binary

In-clinic consultations only. Filter doctors by gender. Male, Female or Non-binary, any case.

api_customer_id
string

Required with sort_by=visited_before.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "providers": [
    ]
}

List slots for a provider

Returns bookable slots for one provider and benefit. Pass booking_date for a single day; omit it for several days (count_days, default 14). Read booking_slots; the top-level date and slots describe only the first day and are deprecated.

The first bookable date depends on the provider's slot_lead_time and timezone (from listProviders); a booking_date before it returns 400.

For inclinic_consultation and specialist_consultation the provider must be an active doctor whose speciality matches the packages.

Authorizations:
bearerAuth
path Parameters
provider_id
required
integer
Example: 1001
benefit_type
required
string
Examples: ahc dental vision flu_vaccination covid_vaccination inclinic_consultation specialist_consultation

The service the slots are for. Same values as service_name.

query Parameters
package_ids
required
string
Example: package_ids=1001

Comma-separated package ids.

booking_date
string <date>

Day to fetch (YYYY-MM-DD). Omit for multiple days.

count_days
integer

Number of days to return when booking_date is omitted. Default 14.

slot_start_date
string <date>

Start the multi-day window no earlier than this date.

pincode
string
Example: pincode=500081

6-digit pincode of the member's location. Derived from latitude/longitude when omitted.

latitude
number
Example: latitude=17.4437

Decimal latitude. Required unless pincode is sent. When no pincode can be derived from the coordinates, the value must be non-negative and include a decimal point (for example 17.0, not 17).

longitude
number
Example: longitude=78.386

Decimal longitude. Required unless pincode is sent. When no pincode can be derived from the coordinates, the value must be non-negative and include a decimal point.

city_name
string

City for the pincode. Derived from the pincode when omitted.

plan_id
string

Plan identifier shared at onboarding. Defaults to the base plan.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "date": "2026-01-15",
  • "booking_slots": [
    ],
  • "report_tat": null,
  • "interval": 3600,
  • "unavailable_reason": null
}

Create a booking

Books one appointment per customer at one provider and time. All appointments share a booking_id; each customer gets an appointment_id.

The booking customer is the last entry with booking_customer: true, else the first; set it on one entry only. address is required for home_collection. There's no fixed limit on customers, but all of them must fit in the provider's slot capacity, otherwise appointment_date_time fails with Booking threshold reached ... (its slots are full).

If the member's wallet covers the cost the booking is placed and status is confirmed (the appointment itself still starts at new and is confirmed by the provider). If an amount is due, status is payment_pending and payment_link must be paid by the member; its appointments are payment_pending until then, then new.

To pay from a specific subscription when a customer holds several on a plan, send customer_plan_id (hlthstack's id, from listCustomerPlans) or subscription_id (your own id). customer_plan_id wins when both are sent.

Authorizations:
bearerAuth
header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
required
provider_id
required
integer or string^[+-]?[0-9]+$
appointment_date_time
required
string <date-time>

A slot's utc_slot_time.

appointment_type
required
string
Enum: "home_collection" "inclinic"
service_name
required
string (BenefitType)
Enum: "ahc" "dental" "vision" "fitness" "pharmacy" "eap" "family_doctor" "pre_employment" "covid_vaccination" "flu_vaccination" "other_health_checks" "rtpcr" "specialist_consultation" "pregnancy_care" "ohc" "annual_calendar" "health_coach" "health_insurance" "face_to_face_consults" "daycare_surgeries" "ambulance_on_demand" "supplementary_insurance" "elder_care" "home_care" "healthcare_financing" "nhc" "diet_consultation" "inclinic_consultation" "fertility_treatment" "consultation24x7" "imaging_services" "occupational_medical_rooms" "cancer_screening" "onsite_camp" "filler_benefit_one" "filler_benefit_two" "filler_benefit_three" "filler_benefit_four" "prescribed_diagnostics" "ppmc" "weight_management_program" "diabetic_program" "bp_program" "cervical_vaccination" "physiotherapy" "prescribed_diagnostics_flow" "vision_wearable" "maternity_care" "gym_subscription" "fitness_products" "wellbeing_marketplace" "pcos_program" "parenting_program" "midlife_health_program" "general_health_program" "fertility_care" "cholesterol_program" "financial_wellbeing"

A benefit type. The service must also be enabled on your plan.

required
Array of objects (BookingCustomer) non-empty
object (BookingAddress)

Required for home_collection.

plan_id
string
customer_plan_id
integer >= 0
subscription_id
string
api_partner_order_id
string

Default for customers that do not send their own.

Responses

Request samples

Content type
application/json
{
  • "appointment_date_time": "2030-01-15T02:30:00Z",
  • "appointment_type": "home_collection",
  • "service_name": "ahc",
  • "provider_id": 1001,
  • "customers": [
    ],
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "provider_id": 1001,
  • "home_collection_enable": true,
  • "booking_id": "EKI0000000001700000000",
  • "status": "confirmed",
  • "customers": [
    ]
}

Get booking or appointment details

Pass only booking_id to get every appointment in the booking; add appointment_id to get one appointment. Each appointment has the same shape as the appointment webhook payload.

Authorizations:
bearerAuth
query Parameters
booking_id
required
string (BookingId) EKI[0-9A-Z_]{19}
Example: booking_id=EKI0000000001700000000

EKI followed by 19 characters (22 in all). The pattern is the server's own, unanchored check.

appointment_id
string (AppointmentId) APT[0-9A-Z_]{9}
Example: appointment_id=APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "booking_id": "string",
  • "service_name": "string",
  • "appointments": [
    ]
}

Reschedule every appointment in a booking

Moves all appointments in the booking. See rescheduleAppointment for the rules. Some appointments may be moved while others are not; the response then lists both as comma-separated appointment_ids.

Authorizations:
bearerAuth
path Parameters
booking_id
required
string (BookingId) EKI[0-9A-Z_]{19}
Example: EKI0000000001700000000

EKI followed by 19 characters (22 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
required
appointment_date_time
required
string <date-time>
provider_id
integer or string or null^(?:[+-]?[0-9]+)?$

Only to move to another provider. Blank or null keeps the current provider.

object (BookingAddress)

Home collection only, with provider_id. Checked only when the booking has a home-collection appointment.

Responses

Request samples

Content type
application/json
{
  • "appointment_date_time": "2030-01-16T02:30:00Z"
}

Response samples

Content type
application/json
Example
{
  • "message": "Booking rescheduled successfully"
}

Cancel every appointment in a booking

Home collection: allowed until a phlebotomist is assigned or 30 minutes before the slot, whichever is first. In-clinic: allowed until 30 minutes before the slot.

Authorizations:
bearerAuth
path Parameters
booking_id
required
string (BookingId) EKI[0-9A-Z_]{19}
Example: EKI0000000001700000000

EKI followed by 19 characters (22 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
optional
reason
string <= 255 characters

Recorded as the cancellation reason. Defaults to Cancelled by your booking partner.

Responses

Request samples

Content type
application/json
{
  • "reason": "Member is travelling"
}

Response samples

Content type
application/json
Example
{
  • "message": "Booking cancelled successfully"
}

Reschedule an appointment

  • New time only: send appointment_date_time.
  • New provider: add provider_id. Not allowed once the appointment is confirmed at the current provider.
  • New address (home collection): add address together with provider_id.

Home collection: allowed until a phlebotomist is assigned or 30 minutes before the slot, whichever is first. In-clinic: until 30 minutes before the slot. An in-clinic appointment cannot become home collection.

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
required
appointment_date_time
required
string <date-time>
provider_id
integer or string or null^(?:[+-]?[0-9]+)?$

Only to move to another provider. Blank or null keeps the current provider.

object (BookingAddress)

Home collection only, with provider_id. Checked only when the booking has a home-collection appointment.

Responses

Request samples

Content type
application/json
{
  • "appointment_date_time": "2030-01-16T02:30:00Z",
  • "provider_id": 1002
}

Response samples

Content type
application/json
{
  • "message": "Appointment rescheduled successfully"
}

Cancel an appointment

Same cut-offs as cancelBooking.

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
optional
reason
string <= 255 characters

Recorded as the cancellation reason. Defaults to Cancelled by your booking partner.

Responses

Request samples

Content type
application/json
{
  • "reason": "Member is travelling"
}

Response samples

Content type
application/json
{
  • "message": "Appointment cancelled successfully"
}

Download the appointment voucher

Returns the voucher PDF. Available only once the appointment is confirmed.

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Get verified report links

Call when the appointment is partially_received or received. Returns links to the verified reports, or a message if none are verified yet. Report links are signed URLs that expire 5 minutes after they're issued: download right away and don't store them.

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
Example

Get digitized lab results

Returns the structured lab values for an appointment (same body as the labResults webhook). Enabled on request: ask hlthstack to register a lab-results webhook endpoint for you; without one this returns 401.

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "type": "lab_results",
  • "booking_id": "EKI0000000001700000000",
  • "appointment_id": "APT1A2B3C4D5",
  • "customer_id": "EKI000000001",
  • "api_customer_id": "CUST1001",
  • "member_id": null,
  • "plan_id": "EXAMPLE_PLAN",
  • "digitization": {
    }
}

Consultations

In-clinic consultations and online specialist consultations (scheduled and priority).

Consultation status changed Webhook

Same endpoint and envelope as appointmentStatusUpdate, with service_type inclinic_consultation or specialist_consultation plus doctor fields, summary, doctor_prescriptions, hospital fields (in-clinic) and meeting_link (video).

Authorizations:
bearerAuth
header Parameters
Signature
required
string

HS256 JWT signed with your webhook secret. See the webhooks guide for the claims.

Request Body schema: application/json
required
type
string
Enum: "status_update" "reports_upload"
booking_id
string
appointment_id
string
customer_id
string

hlthstack's customer id.

customer_name
string
mobile_number
string or null
api_customer_id
string or null

Null for bookings hlthstack's team made on a member's behalf.

member_id
string or null

Member's employee id, when known.

appointment_date_time
string <date-time>
event_timestamp
number

Epoch seconds of the status change.

booking_source
string or null

Channel the booking was made through, fixed at booking time. hlthstack-api for bookings made through the hlthstack API hosts.

service_type
string

The benefit, e.g. ahc, inclinic_consultation.

plan_id
string or null
customer_plan_id
integer or null

Subscription that paid; null on the base plan.

subscription_id
string or null
status
string (AppointmentStatus)

Appointment status. Health checkups: payment_pending, new, confirmed, rejected, noshow, cancelled, rescheduled, completed, verification_required, partially_received, received. Consultations: new, confirmed, rejected, noshow, cancelled, rescheduled, completed, received. Treat unknown values gracefully.

status_text
string
comment
string or null
provider_id
integer
provider_name
string or null
provider_branch
string or null
provider_address
string or null
voucher_api_url
string <uri>

Present once the appointment is confirmed.

phlebo_name
string

Present once confirmed, if a phlebotomist is assigned.

phlebo_number
string
reports
Array of strings <uri> [ items <uri > ]

Present in partially_received and received.

doctor_id
string
doctor_name
string
doctor_specialities
Array of strings
doctor_gender
string or null
doctor_qualification
string or null
doctor_languages
Array of strings
doctor_experience
integer or null
object or null (FileLink)
Array of objects or null (FileLink)
latitude
number or string or null
longitude
number or string or null
hospital_name
string or null
hospital_location
string or null
hospital_address
string or null
meeting_link
string or null

Video consultations only.

object (AppointmentPayment)

Responses

Request samples

Content type
application/json
{
  • "booking_id": "EKI0000000001700000000",
  • "appointment_id": "APT1A2B3C4D5",
  • "customer_id": "EKI000000001",
  • "api_customer_id": "CUST1001",
  • "appointment_date_time": "2030-01-15T04:30:00Z",
  • "booking_source": "hlthstack-api",
  • "service_type": "specialist_consultation",
  • "status": "confirmed",
  • "status_text": "Confirmed",
  • "comment": "",
  • "provider_id": 3001,
  • "doctor_id": "DOC000000002",
  • "doctor_name": "Dr. Jane Doe",
  • "doctor_specialities": [
    ],
  • "doctor_gender": "Female",
  • "doctor_qualification": "MBBS, MD",
  • "doctor_languages": [
    ],
  • "doctor_experience": 10,
  • "meeting_link": "https://meet.example.com/abc",
  • "summary": null,
  • "doctor_prescriptions": [ ],
  • "type": "status_update"
}

List slots for a provider

Returns bookable slots for one provider and benefit. Pass booking_date for a single day; omit it for several days (count_days, default 14). Read booking_slots; the top-level date and slots describe only the first day and are deprecated.

The first bookable date depends on the provider's slot_lead_time and timezone (from listProviders); a booking_date before it returns 400.

For inclinic_consultation and specialist_consultation the provider must be an active doctor whose speciality matches the packages.

Authorizations:
bearerAuth
path Parameters
provider_id
required
integer
Example: 1001
benefit_type
required
string
Examples: ahc dental vision flu_vaccination covid_vaccination inclinic_consultation specialist_consultation

The service the slots are for. Same values as service_name.

query Parameters
package_ids
required
string
Example: package_ids=1001

Comma-separated package ids.

booking_date
string <date>

Day to fetch (YYYY-MM-DD). Omit for multiple days.

count_days
integer

Number of days to return when booking_date is omitted. Default 14.

slot_start_date
string <date>

Start the multi-day window no earlier than this date.

pincode
string
Example: pincode=500081

6-digit pincode of the member's location. Derived from latitude/longitude when omitted.

latitude
number
Example: latitude=17.4437

Decimal latitude. Required unless pincode is sent. When no pincode can be derived from the coordinates, the value must be non-negative and include a decimal point (for example 17.0, not 17).

longitude
number
Example: longitude=78.386

Decimal longitude. Required unless pincode is sent. When no pincode can be derived from the coordinates, the value must be non-negative and include a decimal point.

city_name
string

City for the pincode. Derived from the pincode when omitted.

plan_id
string

Plan identifier shared at onboarding. Defaults to the base plan.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "date": "2026-01-15",
  • "booking_slots": [
    ],
  • "report_tat": null,
  • "interval": 3600,
  • "unavailable_reason": null
}

List in-clinic doctors

Doctors near a location for the given consultation packages, with doctor details.

Authorizations:
bearerAuth
query Parameters
package_ids
required
string[0-9]+(,[0-9]+)*
Example: package_ids=1001,1002

Comma-separated package ids shared at onboarding, for example 1001,1002. Each id must be a package of the requested benefit. The pattern is the server's own, unanchored check.

pincode
string^[0-9]{6}$
Example: pincode=500081

6-digit pincode. Required unless latitude and longitude are sent (the pincode is then derived from them).

latitude
number
Example: latitude=17.4437

Decimal latitude. Required unless pincode is sent. When no pincode can be derived from the coordinates, the value must be non-negative and include a decimal point (for example 17.0, not 17).

longitude
number
Example: longitude=78.386

Decimal longitude. Required unless pincode is sent. When no pincode can be derived from the coordinates, the value must be non-negative and include a decimal point.

radius
number
Default: 100

Search radius in km. Default 100.

plan_id
string

Plan identifier shared at onboarding. Defaults to the base plan.

page
integer
Default: 1

Page number. Values below 1 are read as 1.

per_page
integer <= 50
Default: 20

Page size, at most 50. Values below 1 are read as 1.

sort_by
string
Enum: "fee" "experience" "distance" "rating" "visited_before"

In-clinic consultations only. visited_before also needs api_customer_id.

sort_asc
boolean

In-clinic consultations only. Default ascending for fee/distance, descending for experience/rating.

gender
string^(?:[Mm][Aa][Ll][Ee]|[Ff][Ee][Mm][Aa][Ll][Ee]...
Examples: gender=Male gender=Female gender=Non-binary

In-clinic consultations only. Filter doctors by gender. Male, Female or Non-binary, any case.

api_customer_id
string

Required with sort_by=visited_before.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "providers": [
    ],
  • "total_results": 1,
  • "page": 1
}

List online specialists

Doctors available for online (audio/video) specialist consultations. No location is needed. Send default_provider=true to list the providers configured for priority consultations; an empty list means priority consultation is unavailable for the package or right now.

Authorizations:
bearerAuth
query Parameters
package_ids
required
string[0-9]+(,[0-9]+)*
Example: package_ids=1001,1002

Comma-separated package ids shared at onboarding, for example 1001,1002. Each id must be a package of the requested benefit. The pattern is the server's own, unanchored check.

default_provider
boolean

true to list priority-consultation providers.

plan_id
string

Plan identifier shared at onboarding. Defaults to the base plan.

page
integer
Default: 1

Page number. Values below 1 are read as 1.

per_page
integer <= 50
Default: 20

Page size, at most 50. Values below 1 are read as 1.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "providers": [
    ],
  • "min_price": 700
}

Book an in-clinic consultation

Books an in-person consultation at the doctor's clinic. service_mode, when sent, must be at_provider_location; address (the member's) is required, including pincode. The booking is made for the first customer in customers. Subscription selection works as in createAppointment.

Authorizations:
bearerAuth
header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
required
appointment_date_time
required
string <date-time>

Later than now.

service_mode
string
Value: "at_provider_location"
provider_id
required
integer or string^[+-]?[0-9]+$
required
Array of objects (ConsultationCustomer) non-empty
required
object (ConsultationAddress)

The member's address, as BookingAddress, except that pincode is required.

plan_id
string
customer_plan_id
integer >= 0
subscription_id
string

Responses

Request samples

Content type
application/json
{
  • "appointment_date_time": "2030-01-15T04:30:00.000Z",
  • "service_mode": "at_provider_location",
  • "provider_id": 2001,
  • "customers": [
    ],
  • "address": {
    }
}

Response samples

Content type
application/json
{
  • "provider_id": 2001,
  • "booking_id": "EKI0000000001700000000",
  • "customers": [
    ]
}

Book an online specialist consultation

Books an audio or video consultation.

  • Scheduled (priority_consultation: false): appointment_date_time must be a slot from listSlots; provider_id must not be a priority provider.
  • Priority (priority_consultation: true): a doctor calls within about 4 hours. Available 8 AM-4 PM IST; provider_id must come from listSpecialistConsultationProviders with default_provider=true; appointment_date_time is optional. The consultation is confirmed immediately and the doctor's details arrive by webhook once a doctor is assigned.
Authorizations:
bearerAuth
header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
required
appointment_date_time
string <date-time>

Required, and later than now, unless priority_consultation is true.

service_mode
string
Enum: "audio_call" "video_call"
priority_consultation
boolean
Default: false
provider_id
required
integer or string^[+-]?[0-9]+$
required
Array of objects (ConsultationCustomer) non-empty
plan_id
string
customer_plan_id
integer >= 0
subscription_id
string

Responses

Request samples

Content type
application/json
{
  • "appointment_date_time": "2030-01-15T04:30:00.000Z",
  • "service_mode": "audio_call",
  • "provider_id": 3001,
  • "priority_consultation": false,
  • "customers": [
    ]
}

Response samples

Content type
application/json
{
  • "provider_id": 2001,
  • "booking_id": "EKI0000000001700000000",
  • "customers": [
    ]
}

Get an in-clinic consultation

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "booking_id": "EKI0000000001700000000",
  • "appointment_id": "APT1A2B3C4D5",
  • "appointment_date_time": "2030-01-15T04:30:00Z",
  • "status": "confirmed",
  • "service_name": "Inclinic consultation",
  • "service_mode": "at_provider_location",
  • "api_customer_id": "CUST1001",
  • "customer_id": "EKI000000001",
  • "doctor_id": "DOC000000001",
  • "doctor_name": "Dr. Jane Doe",
  • "doctor_specialities": [
    ],
  • "doctor_gender": "Female",
  • "doctor_qualification": "MBBS",
  • "doctor_languages": [
    ],
  • "doctor_experience": 8,
  • "provider_id": 2001,
  • "is_priority_consultation": false,
  • "is_default_provider": false,
  • "latitude": 17.44,
  • "longitude": 78.38,
  • "hospital_name": "Example Clinic",
  • "hospital_location": "Madhapur",
  • "hospital_address": "1 Example Road, Madhapur, Hyderabad, Telangana 500081"
}

Get an online specialist consultation

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "booking_id": "EKI0000000001700000000",
  • "appointment_id": "APT1A2B3C4D5",
  • "appointment_date_time": "2030-01-15T04:30:00Z",
  • "status": "confirmed",
  • "service_name": "Specialist consultation",
  • "service_mode": "video_call",
  • "api_customer_id": "CUST1001",
  • "customer_id": "EKI000000001",
  • "doctor_id": "DOC000000002",
  • "doctor_name": "Dr. Jane Doe",
  • "doctor_specialities": [
    ],
  • "doctor_gender": "Female",
  • "doctor_qualification": "MBBS, MD",
  • "doctor_languages": [
    ],
  • "doctor_experience": 10,
  • "provider_id": 3001,
  • "is_priority_consultation": false,
  • "is_default_provider": false,
  • "summary": null,
  • "prescriptions": [ ],
}

Reschedule a consultation

Moves the consultation to a new slot with the same doctor (to change doctor, cancel and book again). Allowed up to 30 minutes before the current slot, and not within 5 minutes of the previous booking or reschedule.

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
required
appointment_date_time
required
string <date-time>

New slot (utc_slot_time from listSlots).

provider_id
integer or string

Optional. If sent, must be the consultation's current provider.

Responses

Request samples

Content type
application/json
{
  • "appointment_date_time": "2030-01-16T04:30:00.000Z"
}

Response samples

Content type
application/json
{
  • "message": "Appointment rescheduled successfully"
}

Cancel a consultation

Allowed up to 30 minutes before the slot, and not after a no-show or rejection.

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "msg": "Appointment cancelled"
}

Get the consultation summary and prescriptions

File links are pre-signed and expire after a few minutes; fetch them when needed.

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{}

Download an in-clinic consultation voucher

Returns the voucher PDF for a confirmed in-clinic consultation.

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "errors": {
    }
}

Upload medical documents for a consultation

Shares the member's reports with the doctor (online specialist and priority consultations). Multipart form with one or more files[][name] + files[][value] pairs, each with a non-blank name and a file. Allowed types: PDF, JPEG, PNG (password-protected PDFs are refused).

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: multipart/form-data
required
files[][name]
required
string\S

Title of the document. Repeat once per file, in the same order as files[][value].

files[][value]
required
string <application/octet-stream>

The file.

Responses

Response samples

Content type
application/json
{
  • "message": "Document uploaded successfully"
}

ePharmacy

Medicine search, prescription digitization, cart, pricing and orders.

Pharmacy order status changed Webhook

Sent to your status_updates endpoint on every order status change, including refunds. Each body is a full snapshot. Delivery order is not guaranteed: use the signature timestamp and getOrder to reconcile.

Authorizations:
bearerAuth
header Parameters
Signature
required
string

HS256 JWT signed with your webhook secret. See the webhooks guide for the claims.

Request Body schema: application/json
required
type
string
Enum: "status_update" "post_billing" "additional_payment_required"

status_update here; post_billing and additional_payment_required extend this payload.

order_id
string
customer_id
string
api_customer_id
string or null
member_id
string or null
ordered_for_name
string or null
mobile_number
string or null
order_type
string or null
vendor_name
string or null
service_type
string
Value: "pharmacy"
plan_id
string or null
customer_plan_id
integer or null
subscription_id
string or null
status
string (PharmacyOrderStatus)

Order status. Match on this, not on status_text. Known values: received, abandoned, failed, consultation_required, prescription_under_verification, verification_pending, onhold, verified, prescription_rejected, prescription_cancelled, ops_rejected, created, in_progress, processed, packing, packed, invoice_generated, in_transit, in_delivery, out_for_delivery, delivery_postponed, delivered, cancellation_request, cancellation_inprogress, cancelled, rejected, out_of_stock, returned, returned_and_refunded. New values may be added.

status_text
string or null
status_description
string or null
partner_status
string or null
Array of objects (OrderItem)
total_amount
number
total_selling_price
number
total_discount
number
sub_total
number

Partner-collected only.

additional_charge
number

Partner-collected only.

total_payable
number

Partner-collected only.

tracking_url
string or null
tracking_partner
string or null
tracking_number
string or null
eta_from
string or null
eta_to
string or null
object (ShipmentDetails)
address
string

Present when the order has an address.

city
string
pincode
string
state
string
object or null (SplitDetails)
object (PharmacyPayment)

Responses

Request samples

Content type
application/json
{
  • "type": "status_update",
  • "order_id": "EPO000000000001",
  • "customer_id": "EKI000000001",
  • "api_customer_id": "CUST1001",
  • "ordered_for_name": "Jane Doe",
  • "mobile_number": "9999999999",
  • "order_type": "cart_order",
  • "vendor_name": "Example Pharmacy",
  • "service_type": "pharmacy",
  • "plan_id": "EXAMPLE_PLAN",
  • "status": "out_for_delivery",
  • "status_text": "Order out for delivery",
  • "order_items": [
    ],
  • "total_amount": 95,
  • "total_selling_price": 90,
  • "total_discount": 5,
  • "shipment_details": {
    },
  • "address": "1 Example Road, Motera, Ahmedabad, Gujarat, 380005",
  • "city": "Ahmedabad",
  • "pincode": "380005",
  • "state": "Gujarat",
  • "split_details": {
    }
}

Partner-collected order settled Webhook

Partner-collected flow only. Sent when every order in the tree is final. settlement.adjustment_amount is what you owe the member back. The latest one wins.

Authorizations:
bearerAuth
header Parameters
Signature
required
string

HS256 JWT signed with your webhook secret. See the webhooks guide for the claims.

Request Body schema: application/json
required
type
string
Enum: "status_update" "post_billing" "additional_payment_required"

status_update here; post_billing and additional_payment_required extend this payload.

Value: "post_billing"
order_id
string
customer_id
string
api_customer_id
string or null
member_id
string or null
ordered_for_name
string or null
mobile_number
string or null
order_type
string or null
vendor_name
string or null
service_type
string
Value: "pharmacy"
plan_id
string or null
customer_plan_id
integer or null
subscription_id
string or null
status
string (PharmacyOrderStatus)

Order status. Match on this, not on status_text. Known values: received, abandoned, failed, consultation_required, prescription_under_verification, verification_pending, onhold, verified, prescription_rejected, prescription_cancelled, ops_rejected, created, in_progress, processed, packing, packed, invoice_generated, in_transit, in_delivery, out_for_delivery, delivery_postponed, delivered, cancellation_request, cancellation_inprogress, cancelled, rejected, out_of_stock, returned, returned_and_refunded. New values may be added.

status_text
string or null
status_description
string or null
partner_status
string or null
Array of objects (OrderItem)
total_amount
number
total_selling_price
number
total_discount
number
sub_total
number

Partner-collected only.

additional_charge
number

Partner-collected only.

total_payable
number

Partner-collected only.

tracking_url
string or null
tracking_partner
string or null
tracking_number
string or null
eta_from
string or null
eta_to
string or null
object (ShipmentDetails)
address
string

Present when the order has an address.

city
string
pincode
string
state
string
object or null (SplitDetails)
object (PharmacyPayment)
object

Responses

Request samples

Content type
application/json
{
  • "type": "post_billing",
  • "order_id": "EPO000000000001",
  • "customer_id": "EKI000000001",
  • "api_customer_id": "CUST1001",
  • "ordered_for_name": "Jane Doe",
  • "mobile_number": "9999999999",
  • "order_type": "cart_order",
  • "vendor_name": "Example Pharmacy",
  • "service_type": "pharmacy",
  • "plan_id": "EXAMPLE_PLAN",
  • "status": "out_for_delivery",
  • "status_text": "Order out for delivery",
  • "order_items": [
    ],
  • "total_amount": 95,
  • "total_selling_price": 90,
  • "total_discount": 5,
  • "shipment_details": {
    },
  • "address": "1 Example Road, Motera, Ahmedabad, Gujarat, 380005",
  • "city": "Ahmedabad",
  • "pincode": "380005",
  • "state": "Gujarat",
  • "split_details": {
    },
  • "settlement": {
    }
}

Partner-collected order needs more money Webhook

Partner-collected flow only. Collect additional_payment.amount_payable from the member.

Authorizations:
bearerAuth
header Parameters
Signature
required
string

HS256 JWT signed with your webhook secret. See the webhooks guide for the claims.

Request Body schema: application/json
required
type
string
Enum: "status_update" "post_billing" "additional_payment_required"

status_update here; post_billing and additional_payment_required extend this payload.

Value: "additional_payment_required"
order_id
string
customer_id
string
api_customer_id
string or null
member_id
string or null
ordered_for_name
string or null
mobile_number
string or null
order_type
string or null
vendor_name
string or null
service_type
string
Value: "pharmacy"
plan_id
string or null
customer_plan_id
integer or null
subscription_id
string or null
status
string (PharmacyOrderStatus)

Order status. Match on this, not on status_text. Known values: received, abandoned, failed, consultation_required, prescription_under_verification, verification_pending, onhold, verified, prescription_rejected, prescription_cancelled, ops_rejected, created, in_progress, processed, packing, packed, invoice_generated, in_transit, in_delivery, out_for_delivery, delivery_postponed, delivered, cancellation_request, cancellation_inprogress, cancelled, rejected, out_of_stock, returned, returned_and_refunded. New values may be added.

status_text
string or null
status_description
string or null
partner_status
string or null
Array of objects (OrderItem)
total_amount
number
total_selling_price
number
total_discount
number
sub_total
number

Partner-collected only.

additional_charge
number

Partner-collected only.

total_payable
number

Partner-collected only.

tracking_url
string or null
tracking_partner
string or null
tracking_number
string or null
eta_from
string or null
eta_to
string or null
object (ShipmentDetails)
address
string

Present when the order has an address.

city
string
pincode
string
state
string
object or null (SplitDetails)
object (PharmacyPayment)
object

Responses

Request samples

Content type
application/json
{
  • "type": "additional_payment_required",
  • "order_id": "EPO000000000001",
  • "customer_id": "EKI000000001",
  • "api_customer_id": "CUST1001",
  • "ordered_for_name": "Jane Doe",
  • "mobile_number": "9999999999",
  • "order_type": "cart_order",
  • "vendor_name": "Example Pharmacy",
  • "service_type": "pharmacy",
  • "plan_id": "EXAMPLE_PLAN",
  • "status": "out_for_delivery",
  • "status_text": "Order out for delivery",
  • "order_items": [
    ],
  • "total_amount": 95,
  • "total_selling_price": 90,
  • "total_discount": 5,
  • "shipment_details": {
    },
  • "address": "1 Example Road, Motera, Ahmedabad, Gujarat, 380005",
  • "city": "Ahmedabad",
  • "pincode": "380005",
  • "state": "Gujarat",
  • "split_details": {
    },
  • "additional_payment": {
    }
}

Prescription digitization finished Webhook

Sent to your digitization_results endpoint when a request reaches completed, partial, rejected or failed.

Authorizations:
bearerAuth
header Parameters
Signature
required
string

HS256 JWT signed with your webhook secret. See the webhooks guide for the claims.

Request Body schema: application/json
required
type
string
Value: "digitization_results"
event_type
string
Value: "pharmacy.prescription.digitized"
request_id
string
status
string
Enum: "completed" "partial" "rejected" "failed"
customer_id
string
api_customer_id
string or null
member_id
string or null
plan_id
string or null
Array of objects or null
Array of objects or null
cart_id
integer or null
Array of objects
comment
string or null

Responses

Request samples

Content type
application/json
{
  • "type": "digitization_results",
  • "event_type": "pharmacy.prescription.digitized",
  • "request_id": "string",
  • "status": "completed",
  • "customer_id": "string",
  • "api_customer_id": "string",
  • "member_id": "string",
  • "plan_id": "string",
  • "items": [
    ],
  • "reviewed_items": [
    ],
  • "cart_id": 0,
  • "documents": [
    ],
  • "comment": "string"
}

Search medicines

Searches the catalogue. The returned id is the only medicine id the cart accepts. rx_required: true means a prescription must be attached before ordering.

Authorizations:
bearerAuth
query Parameters
name
required
string >= 3 characters \S[\s\S]+\S
Example: name=paracetamol

Search text, at least 3 characters after trimming surrounding whitespace.

page
integer >= 1
Default: 1
header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "medicines": [
    ],
  • "meta": {
    }
}

Upload a prescription for digitization

Upload a prescription; hlthstack extracts the medicines and, when done, builds a cart for the member. Poll getPrescriptionDigitization or wait for the prescriptionDigitized webhook.

customers is an array with exactly one customer. Send an Idempotency-Key to make retries safe: repeating a key returns the existing request.

Authorizations:
bearerAuth
header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Idempotency-Key
string

Optional. A unique key per upload; a repeat returns the original request.

Request Body schema: multipart/form-data
required
customers[][name]
required
string\S
customers[][api_customer_id]
required
string^[a-zA-Z0-9]+$
customers[][mobile_number]
required
string^[0-9]{10}$
customers[][gender]
required
string
Enum: "male" "female" "non-binary"
customers[][dob]
required
string <date>
plan_id
string
files[]
required
Array of strings non-empty

JPEG, PNG or PDF; each up to 10 MB.

Responses

Response samples

Content type
application/json
{
  • "request_id": "DIGI_RQ_A1B2C3D4E",
  • "digitization_id": "DIGI_RQ_A1B2C3D4E",
  • "status": "pending",
  • "message": "Prescription uploaded successfully. You will receive a webhook once digitization is complete."
}

Get digitization status

Statuses: pending -> ai_processing -> manual_review -> completed | partial | rejected | failed. On completed/partial the response has the extracted items and a ready cart_id. File URLs are pre-signed and expire after 5 minutes.

Authorizations:
bearerAuth
path Parameters
request_id
required
string
Example: DIGI_RQ_A1B2C3D4E
header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "request_id": "DIGI_RQ_A1B2C3D4E",
  • "status": "completed",
  • "api_customer_id": "CUST1001",
  • "message": "Prescription digitization is completed.",
  • "items": [
    ],
  • "cart_id": 701
}

Get the member's cart

There is one cart per member per plan.

Authorizations:
bearerAuth
query Parameters
customer_details[api_customer_id]
required
string

Your id for the member.

plan_id
string

Plan identifier shared at onboarding. Defaults to the base plan.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "cart": {
    }
}

Create or update the member's cart

Find-or-create and merge. Send at least one change: products, address or address_id, prescription_urls / prescription_files, remove_prescription_ids, or fulfillment_type. The whole update is atomic: on error the cart is unchanged.

  • products: quantity: 0 removes a line, > 0 adds or updates it; ids not sent are untouched; duplicate ids are rejected.
  • customer_details other than api_customer_id create or enrich the member; a new api_customer_id creates the member.
  • Attach a prescription whenever any item has rx_required: true.
  • For store pickup, send fulfillment_type: store_pickup with selected_chemist_id (a store id from getFulfillmentOptions).

Use multipart/form-data (with bracketed field names) to upload prescription_files[].

Authorizations:
bearerAuth
header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema:
required
plan_id
string
required
object
Array of objects non-empty
object (PharmacyAddressInput)

A new address. pincode (or its alias zip_code) is required as well as line1, city and state.

address_id
integer

Mutually exclusive with address.

fulfillment_type
string
Enum: "delivery" "store_pickup"
selected_chemist_id
string

Store id; required for store_pickup.

medicine_vendor_id
integer
prescription_urls
Array of strings <uri> <= 5 items [ items <uri >^https://[^/?#@:]+(?::443)?(?:[/?#]|$) ]

Public HTTPS URLs (port 443, no user info) to PDF/PNG/JPEG files under 7 MB.

remove_prescription_ids
Array of integers non-empty

Responses

Request samples

Content type
Example
{
  • "plan_id": "EXAMPLE_PLAN",
  • "customer_details": {
    },
  • "products": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "cart": {
    }
}

Get delivery and pickup options

Live express/standard delivery and store-pickup options for the cart. Slow (typically 3-8 s). Delivery and pickup are evaluated independently: check the nested success flags, not just the HTTP status.

Each option has a vendor_id (pass it as medicine_vendor_id to getOrderPaymentDetails) and a location_token (pass it to createOrder). Tokens are specific to one mode or store; fetch options again if the member changes their choice.

Authorizations:
bearerAuth
query Parameters
customer_details[api_customer_id]
required
string

Your id for the member.

cart_id
required
integer
plan_id
string

Plan identifier shared at onboarding. Defaults to the base plan.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "delivery_options": {
    },
  • "pickup_options": {
    }
}

Price the cart

Final amounts before ordering, including the wallet split. total_payable is what the member still owes. Note the field is selected_delivery_option here but delivery_option on createOrder.

Authorizations:
bearerAuth
header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
required
plan_id
string
required
object (CustomerDetailsRef)
cart_id
required
integer
selected_delivery_option
required
string
Enum: "express" "standard" "store_pickup"
selected_chemist_id
string

Required for store_pickup; must match the cart's store.

medicine_vendor_id
integer

The option's vendor_id.

customer_plan_id
integer >= 0
subscription_id
string

Responses

Request samples

Content type
application/json
{
  • "plan_id": "EXAMPLE_PLAN",
  • "customer_details": {
    },
  • "cart_id": 701,
  • "selected_delivery_option": "standard",
  • "medicine_vendor_id": 3
}

Response samples

Content type
application/json
{
  • "products": [
    ],
  • "payment_details": {
    },
  • "estimated_time": "24-48 hrs",
  • "fulfillment": {
    },
  • "address": { }
}

Place an order

Places an order from the cart. The response status depends on your payment flow (fixed per contract):

  • confirmed: the wallet covered the whole amount.
  • payment_pending: send payment_link to the member; unpaid orders are abandoned after 3 hours.
  • partner_payment_pending: collect amount_to_collect yourself, then call confirmOrder; unconfirmed orders are abandoned after 3 hours.

For store pickup, set it on the cart first (updateCart); don't pass the store here.

Authorizations:
bearerAuth
header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
required
plan_id
string
required
object (CustomerDetailsRef)
cart_id
required
integer
delivery_option
string
Default: "standard"
Enum: "express" "standard" "store_pickup"
delivery_type
string
Enum: "delivery" "pickup"

Defaults from the cart's fulfillment_type.

location_token
string

Token of the chosen option from getFulfillmentOptions.

medicine_vendor_id
integer
coupon_code
string
customer_plan_id
integer >= 0
subscription_id
string

Responses

Request samples

Content type
application/json
{
  • "plan_id": "EXAMPLE_PLAN",
  • "customer_details": {
    },
  • "cart_id": 701,
  • "delivery_option": "standard",
  • "location_token": "OPAQUE_TOKEN"
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "status": "confirmed",
  • "booking_id": 90001,
  • "user_prescription_details": {
    }
}

List a member's orders

Newest first.

Authorizations:
bearerAuth
query Parameters
customer_details[api_customer_id]
required
string

Your id for the member.

page
integer
Default: 1

Page number. Values below 1 are read as 1.

per_page
integer
Default: 10
header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "orders": [
    ],
  • "meta": {
    }
}

Get an order

The source of truth for an order's state; use it to reconcile webhooks.

Authorizations:
bearerAuth
path Parameters
order_id
required
string
Example: EPO000000000001

The order's unique_id.

query Parameters
customer_details[api_customer_id]
required
string

Your id for the member.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "order": {
    }
}

Cancel an order

Possible only before the pharmacy ships (vendor-specific) and never for split orders. Refunds to wallets and payment methods run automatically.

Authorizations:
bearerAuth
path Parameters
order_id
required
string
Example: EPO000000000001

The order's unique_id.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
required
plan_id
string
required
object (CustomerDetailsRef)
reason
string
Default: "Cancel order"
message
string

Free text, for example when reason is "other".

Responses

Request samples

Content type
application/json
{
  • "customer_details": {
    },
  • "reason": "Ordered by mistake"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "order_id": "EPO000000000001",
  • "status": "cancelled"
}

Confirm a partner-collected payment

Partner-collected flow only. Tells hlthstack you collected amount_to_collect. partner_collected_amount must equal it exactly. Safe to retry: the same amount and reference returns already_confirmed. On 409, back off and retry.

Authorizations:
bearerAuth
path Parameters
order_id
required
string
Example: EPO000000000001

The order's unique_id.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
required
required
object (CustomerDetailsRef)
partner_collected_amount
required
string or number > 0

Decimal amount greater than 0, for example "261.0".

partner_payment_reference
required
string\S

Your payment/transaction reference (not blank; surrounding whitespace is trimmed).

Responses

Request samples

Content type
application/json
{
  • "customer_details": {
    },
  • "partner_collected_amount": "261.0",
  • "partner_payment_reference": "TXN-0001"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "status": "confirmed",
  • "order_id": "EPO000000000003",
  • "partner_collected_amount": 261,
  • "partner_payment_reference": "TXN-0001",
  • "vendor_order_status": "onhold"
}

Wallet

Member benefit wallets and plan subscriptions.

Get a member's benefit wallet

Allocated and available amounts per benefit for the member and their active family, primary member first. Identify the member by api_customer_id or customer_id (api_customer_id wins when both are sent); a dependant's id returns the whole family. Send customer_plan_id or subscription_id to read one subscription (upcoming and ended ones included).

Authorizations:
bearerAuth
path Parameters
company_slug
required
string

Your company slug, shared at onboarding. Must match the entity of the access token.

query Parameters
plan_id
string

Plan identifier shared at onboarding. Defaults to the base plan.

api_customer_id
string
customer_id
string

hlthstack's customer id.

customer_plan_id
integer >= 0

hlthstack's subscription id (from listCustomerPlans).

subscription_id
string

Your own subscription id, if sent at enrollment.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

List a member's plan subscriptions

One row per subscription (active, upcoming or in grace; fully lapsed ones are left out). Use customer_plan_id to choose which subscription pays when booking or ordering.

Authorizations:
bearerAuth
path Parameters
company_slug
required
string

Your company slug, shared at onboarding. Must match the entity of the access token.

query Parameters
api_customer_id
string
customer_id
string
header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "data": {
    }
}

Pre-registration

Register, update and deactivate members and their dependants in bulk. Uses its own credentials and token (X-EKINCARE-KEY).

Get a pre-registration access token

Exchanges your pre-registration credentials (HTTP Basic: the account email and password hlthstack issued for pre-registration, not your booking API credentials) for a token. Send it as the X-EKINCARE-KEY header on the other pre-registration calls.

The token is valid for 1 hour. expires_at is a UTC timestamp in the form 2026-01-15 07:16:21 UTC (not ISO 8601). Every call issues a new token; there is no refresh token.

Authorizations:
preRegistrationBasicAuth

Responses

Response samples

Content type
application/json
{
  • "access_token": "YOUR_PRE_REGISTRATION_TOKEN",
  • "expires_at": "2026-01-15 07:16:21 UTC"
}

Pre-register members and dependants

Queues members (employees) and their dependants for registration and returns a request_id. Processing is asynchronous: poll getPreRegistrationStatus for each row's outcome. Employees are processed before dependants, so a dependant can refer to an employee sent in the same request.

  • Send employees, dependants or both; at most 250 rows in total per request.
  • Every key marked required must be present in every row, even when its value is empty ("" or null). A row missing a required key is dropped silently: it is not registered and is not reported in the status. If no row is left, the call fails with 400.
  • Each employee needs company_id (a company your credentials can act on) and an email or an employee_code.
  • Each dependant is linked to its employee by guardian_email, or by company_id plus guardian_employee_code when the employee has no email.
  • Row values are checked while the request is processed; a row that fails a check is reported in failure_records (see the field patterns and x-hlthstack-rules).
Authorizations:
preRegistrationKey
Request Body schema: application/json
required
Array of objects (PreRegistrationEmployee)
Array of objects (PreRegistrationDependant)

Responses

Request samples

Content type
application/json
{
  • "employees": [
    ],
  • "dependants": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Request has been accepted",
  • "request_id": "3f2b8c1e-0d4a-4c5e-9b7a-2e6f1d8c9a01"
}

Update registered members and dependants

Queues updates to registered members and dependants and returns a request_id; poll getPreRegistrationStatus for each row's outcome. Send only the identifier and the fields to change. At most 250 rows in total per request.

  • An employee is found by email, or by company_id plus employee_code when no email is sent. The email itself can't be changed here.
  • A dependant is found by api_customer_id, then dependent_code, under the employee given by guardian_email (or company_id plus guardian_employee_code); otherwise by mobile_number, which must match exactly one dependant. At least one of api_customer_id, dependent_code or mobile_number is required.
  • mobile_number in an update is stored as the member's alternate mobile number.
  • voluntary_plan_ids takes the same entries as createPreRegistrations. On a dependant it is refused (the rest of the row is still applied).
Authorizations:
preRegistrationKey
Request Body schema: application/json
required
Array of objects (PreRegistrationEmployeeUpdate)
Array of objects (PreRegistrationDependantUpdate)

Responses

Request samples

Content type
application/json
{
  • "employees": [
    ],
  • "dependants": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Request has been accepted",
  • "request_id": "3f2b8c1e-0d4a-4c5e-9b7a-2e6f1d8c9a01"
}

Deactivate members or dependants

Queues deactivations and returns a request_id; poll getPreRegistrationStatus for each one's outcome. employees lists employee emails, dependants lists dependant mobile numbers. At most 250 entries in total per request.

Deactivating an employee also deactivates all their dependants and cancels their ongoing appointments. Only members of companies your credentials can act on are deactivated.

Authorizations:
preRegistrationKey
Request Body schema: application/json
required
employees
Array of strings

Emails of the employees to deactivate.

dependants
Array of strings

Mobile numbers of the dependants to deactivate.

Responses

Request samples

Content type
application/json
{
  • "employees": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Request has been accepted",
  • "request_id": "3f2b8c1e-0d4a-4c5e-9b7a-2e6f1d8c9a01"
}

Get the outcome of a pre-registration request

The request's processing status and its rows, split into success_records and failure_records. Poll until status is completed; records are added while the request is inprogress.

  • Create and update requests: each success record is the member as stored (dependants included, with guardian_email and relation); employees carry customer_plans. Each failure record echoes the row with its errors.
  • Deactivate requests: success records carry status (Active/Inactive); failure records are {"errors": ["..."]} only.
Authorizations:
preRegistrationKey
path Parameters
request_id
required
string <uuid>
Example: 3f2b8c1e-0d4a-4c5e-9b7a-2e6f1d8c9a01

The request_id returned by a create, update or deactivate call.

Responses

Response samples

Content type
application/json
{
  • "request_id": "3f2b8c1e-0d4a-4c5e-9b7a-2e6f1d8c9a01",
  • "status": "completed",
  • "success_records": [
    ],
  • "failure_records": [
    ],
  • "created_at": "2026-01-15T06:16:21Z"
}

Testing

Staging-only endpoints that move a booking or order through its lifecycle and fire the real webhooks.

(Staging only) Move an appointment to a new status

Staging only. Production returns 401. Moves the appointment through its lifecycle and fires the same webhook a real update would.

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
required
status
required
string
Enum: "confirm" "assign_phlebo" "cancel" "completed" "reschedule" "reports_partially_received" "reports_received" "lab_result"

reschedule moves the appointment to the next day. assign_phlebo needs a confirmed appointment. lab_result needs a received appointment and a lab-results webhook endpoint.

Responses

Request samples

Content type
application/json
{
  • "status": "confirm"
}

Response samples

Content type
application/json
{
  • "messages": [
    ]
}

(Staging only) Move a consultation to a new status

Staging only; the route does not exist in production (404). Fires the same webhook as a real update. reports_received attaches a sample summary and prescription and then moves the consultation to received.

Authorizations:
bearerAuth
path Parameters
appointment_id
required
string (AppointmentId) APT[0-9A-Z_]{9}
Example: APT1A2B3C4D5

APT followed by 9 characters (12 in all). The pattern is the server's own, unanchored check.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
required
status
required
string
Enum: "confirm" "cancel" "completed" "reschedule" "reports_received"
reschedule_time
string <date-time>

For reschedule. Defaults to 1 day from now.

Responses

Request samples

Content type
application/json
{
  • "status": "confirm"
}

Response samples

Content type
application/json
{
  • "messages": [
    ]
}

(Staging only) Move an order to a new status

Staging only; the route does not exist in production (404). Records a status change and fires the same status_update webhook a pharmacy update would. The optional text and tracking fields are passed through to the webhook.

Authorizations:
bearerAuth
path Parameters
order_id
required
string
Example: EPO000000000001

The order's unique_id.

header Parameters
API-ENTITY-ID
string

Multi-entity partners: the id of the entity to act for. When omitted, the entity tied to your credentials is used. Requires API-SECRET-KEY.

API-SECRET-KEY
string

For multi-entity partners, the secret key issued with your credentials. Required when API-ENTITY-ID is sent.

Request Body schema: application/json
required
required
object (CustomerDetailsRef)
status
required
string
Enum: "received" "cancellation_request" "cancellation_inprogress" "consultation_required" "processed" "rejected" "invoice_pending" "invoice_generated" "onhold" "cancelled" "abandoned" "packing" "packed" "delivery_postponed" "out_for_delivery" "delivered" "in_transit" "in_delivery" "created" "verification_pending" "verified" "failed" "in_progress" "error" "out_of_stock" "returned_and_refunded" "returned" "under_ops_verification" "prescription_under_verification" "prescription_on_hold" "prescription_rejected" "prescription_cancelled" "ops_verified" "ops_rejected"

An order status (see PharmacyOrderStatus).

status_text
string
status_description
string
tracking_number
string
tracking_url
string
tracking_partner
string

Responses

Request samples

Content type
application/json
{
  • "customer_details": {
    },
  • "status": "in_progress",
  • "status_text": "Order is being processed"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "order_id": "EPO000000000001",
  • "status": "in_progress",
  • "journey": [
    ]
}