Webhook Payload Structure
This page documents the complete structure of webhook payloads sent by VectorCare.
Example Payloads
Section titled “Example Payloads”A schema reference showing every field populated with example values. In practice, many of these fields will be null depending on the organization's configuration and the type of transport.
A hypothetical BLS ambulance transport moving an inpatient from a skilled nursing facility to a hospital for a CT scan. The patient is on contact isolation precautions. This request has not yet been accepted, so responder fields and agreed_for_time are null.
A hypothetical critical care transport between hospitals with IV therapy, oxygen, and cardiac monitoring. This request has been accepted, so it includes an agreed_for_time, responder details, and a revised_eta. Fields like cct_criteria, intravenous_therapy, medical_supervision, medications, override_approver, and override_reason are populated in this scenario.
A hypothetical recurring wheelchair transport for a dialysis patient picked up from home. This trip is part of a standing order collection and is the outbound leg of a round trip with a scheduled return time. The patient's son is accompanying as an additional passenger. Fields like collection_id, is_dialysis_trip, pickup_is_home, additional_passenger_*, and travel_authorization_number are populated in this scenario.
When a request is no longer available to your organization (e.g., the broadcast was canceled, expired, or declined), the request_status is UNAVAILABLE and the data field is null. Your webhook handler should check for this case before attempting to read data fields.
{ "event_id": "b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4", "event_timestamp": "2026-02-15T10:30:45.000Z", "service_request_id": "VC-TN4KQ8R2", "request_status": "UNAVAILABLE", "action": "BROADCAST_CANCELED", "data": null}Top-Level Fields
Section titled “Top-Level Fields”| Field | Type | Nullable | Description |
|---|---|---|---|
| event_id | string | | Unique identifier for this webhook event. Chronologically sortable. IDs generated later are lexicographically greater. Use to deduplicate retried webhooks and determine event ordering. |
| event_timestamp | string | | When the webhook was sent (ISO 8601 UTC) |
| service_request_id | string | | Unique identifier for this service request (e.g., VC-BSBBCY5Q) |
| request_status | string | | High-level status indicator (see Request Status) |
| action | string | | What triggered this webhook (see Actions) |
| data | object | nullable | Full request details (see Data Object Fields below). Null when request_status is UNAVAILABLE. |
Data Object Fields
Section titled “Data Object Fields”All fields are always present but many will be null depending on request state and service configuration. Healthcare organizations configure which fields are collected for their transport requests.
Core Fields
Section titled “Core Fields”| Field | Type | Nullable | Description |
|---|---|---|---|
| service_request_id | string | | Unique identifier for this service request (e.g., VC-BSBBCY5Q) |
| request_current_state | string | | Internal VectorCare workflow state (e.g., awaiting, accepted) |
| change_request_enabled | boolean | | Whether you can submit a Change Request to propose a new pickup time for this request |
| service_type | string | | Type of transport service (custom configured by requesting organization) |
| service_level_type | string | nullable | Medical service level (custom configured, e.g., ALS, BLS, CCT, Wheelchair) |
| scheduling_option | string | | How the pickup time was scheduled (e.g., specific, asap) |
| scheduling_type | string | | Trip direction: one_way or round_trip |
| organization_id | string | | Unique identifier for the requesting organization |
| account_name | string | | Display name of the organization that created the request |
| facility_name | string | nullable | Name of the specific facility within the organization |
| collection_id | string | nullable | Groups related trips together (e.g., standing orders) |
| service_request_web_url | string | | URL to view this service request in the VectorCare web application. The user following this link must be logged in to VectorCare (this is a web session login, not related to API credentials). |
Timing
Section titled “Timing”| Field | Type | Nullable | Description |
|---|---|---|---|
| agreed_for_time | string | nullable | Confirmed pickup time (ISO 8601 UTC). When present, this is the authoritative pickup time and may differ from pickup_date_time. null until both parties have agreed on the pickup time. Fall back to pickup_date_time when this field is null. |
| pickup_date_time | string | nullable | Originally requested pickup time (ISO 8601 UTC). This is not the confirmed pickup time. See the separate agreed_for_time field, which should be used as the authoritative pickup time when it is present. |
| appointment_datetime | string | nullable | Patient's appointment time at destination |
| return_date_time | string | nullable | Scheduled time for return trip pickup |
| revised_eta | string | nullable | Updated estimated time of arrival if changed from original |
Locations
Section titled “Locations”| Field | Type | Nullable | Description |
|---|---|---|---|
| pickup_location | location | nullable | Pickup address with GPS coordinates (see Location Object) |
| pickup_facility_name | string | nullable | Name of the facility at pickup location |
| pickup_facility_type | string | nullable | Category of the pickup facility (e.g., hospital, SNF) |
| pickup_is_home | boolean | nullable | Indicates if pickup location is the patient's residence |
| pickup_exact_location | string | nullable | Specific location within the facility (e.g., "ER Bay 3") |
| pickup_room_number | string | nullable | Room or bed number at the pickup location |
| pickup_stair_steps | string | nullable | Number of stair steps at pickup (for accessibility) |
| pickup_phone_number | string | nullable | Contact phone number for pickup location |
| pickup_phone_number_extension | string | nullable | Phone extension for pickup location |
| destination_location | location | nullable | Destination address with GPS coordinates (see Location Object) |
| destination_facility_name | string | nullable | Name of the facility at destination |
| destination_facility_type | string | nullable | Category of the destination facility |
| destination_is_home | boolean | nullable | Indicates if destination is the patient's residence |
| destination_exact_location | string | nullable | Specific location within the destination facility |
| destination_address_detail | string | nullable | Additional address info (unit number, suite, building) |
| destination_room_number | string | nullable | Room or bed number at destination |
| destination_stair_steps | string | nullable | Number of stair steps at destination |
| destination_phone_number | string | nullable | Contact phone number for destination |
| destination_phone_number_extension | string | nullable | Phone extension for destination |
| departure_airport | location | nullable | Departure airport, air transport only (see Location Object) |
| arrival_airport | location | nullable | Arrival airport, air transport only (see Location Object) |
Patient Information
Section titled “Patient Information”| Field | Type | Nullable | Description |
|---|---|---|---|
| patient_id | string | nullable | VectorCare patient identifier |
| patient_first_name | string | nullable | Patient's first name |
| patient_middle_name | string | nullable | Patient's middle name |
| patient_last_name | string | nullable | Patient's last name |
| patient_date_of_birth | string | nullable | Patient's date of birth in YYYY-MM-DD format |
| patient_age | number | nullable | Patient's age in years |
| patient_gender | string | nullable | Patient's gender |
| patient_weight_lbs | number | nullable | Patient's weight in pounds |
| patient_weight_kg | number | nullable | Patient's weight in kilograms |
| patient_height_inches | number | nullable | Patient's height in inches |
| patient_girth_inches | number | nullable | Patient's girth measurement in inches |
| patient_bmi | string | nullable | Patient's body mass index |
| patient_over_300p | boolean | nullable | Indicates if patient weighs over 300 lbs (bariatric) |
| patient_language_spoken | string | nullable | Patient's preferred spoken language |
| patient_language_written | string | nullable | Patient's preferred written language |
| patient_interpreter_required | boolean | nullable | Indicates if an interpreter is needed for the transport |
| patient_membership_primary_id | string | nullable | Primary member ID or medical record number (MRN) |
| patient_membership_primary_prefix | string | nullable | Prefix for the primary member ID |
| patient_membership_secondary_id | string | nullable | Secondary member ID or MRN |
| patient_membership_secondary_prefix | string | nullable | Prefix for the secondary member ID |
| patient_active_membership | boolean | nullable | Indicates if patient has an active membership |
| patient_coverages | array | nullable | Patient's insurance coverage information |
Medical
Section titled “Medical”| Field | Type | Nullable | Description |
|---|---|---|---|
| diagnosis_notes | string | nullable | Clinical notes or diagnosis information |
| can_ambulate | boolean | nullable | Indicates if patient can walk independently |
| patient_is_ready | boolean | nullable | Indicates if patient is ready for pickup |
| is_inpatient | boolean | nullable | Indicates if patient is currently admitted |
| is_dialysis_trip | boolean | nullable | Indicates if transport is for dialysis treatment |
| is_recent_onset | boolean | nullable | Indicates if patient's condition is recent onset |
| hospice | boolean | nullable | Indicates if patient is under hospice care |
| o2 | string | nullable | Oxygen flow rate in liters per minute |
| intravenous_therapy | array | nullable | IV therapy details and requirements |
| number_of_drips | string | nullable | Number of active IV drips during transport |
| medications | array | nullable | Medications being administered during transport |
| cct_criteria | array | nullable | Criteria met for critical care transport level |
| medical_supervision | array | nullable | Required medical supervision level |
| mental_health_hold | array | nullable | Mental health hold status (e.g., 5150) |
| isolation_precaution | boolean | nullable | General isolation precaution flag |
| under_isolation | array | nullable | Specific isolation types required (e.g., contact, airborne) |
Equipment
Section titled “Equipment”| Field | Type | Nullable | Description |
|---|---|---|---|
| has_own_wheelchair | boolean | nullable | Indicates if patient will bring their own wheelchair |
| required_equipment | array | nullable | Medical equipment needed for transport |
| special_equipment | array | nullable | Additional specialized equipment requirements |
People
Section titled “People”| Field | Type | Nullable | Description |
|---|---|---|---|
| requester_first_name | string | | First name of the person who created the request |
| requester_last_name | string | | Last name of the person who created the request |
| requester_email | string | | Email address of the requester |
| requester_phone_number | string | nullable | Phone number of the requester |
| requester_phone_number_extension | string | nullable | Phone extension for the requester |
| responder_user_first_name | string | nullable | First name of the assigned transport provider user |
| responder_user_last_name | string | nullable | Last name of the assigned transport provider user |
| responder_user_email | string | nullable | Email of the assigned transport provider user |
| contact_name | string | nullable | Name of alternate contact person for this transport |
| contact_phone | string | nullable | Phone number of alternate contact |
| additional_passenger_name | string | nullable | Name of person accompanying the patient |
| additional_passenger_phone | string | nullable | Phone number of accompanying person |
| additional_passenger_relationship | string | nullable | Accompanying person's relationship to patient |
| additional_passenger_weight | string | nullable | Weight of accompanying person in pounds |
| additional_personnel | array | nullable | Additional crew or staff requirements |
| authorizing_physician | string | nullable | Physician who authorized the transport |
| receiving_practitioner | string | nullable | Practitioner receiving the patient at destination |
| receiving_practitioner_2 | string | nullable | Additional practitioner receiving the patient |
| transporting_practitioner | string | nullable | Practitioner accompanying patient during transport |
Request Details
Section titled “Request Details”| Field | Type | Nullable | Description |
|---|---|---|---|
| trip_priority_level | string | nullable | Urgency level assigned to the request |
| escalated | boolean | nullable | Indicates if the request has been escalated |
| note | string | nullable | Free-text notes added by the requester |
| transport_reason | array | nullable | Selected reasons for the transport |
| other_requirements | string | nullable | Free-text field for additional transport requirements |
Payment & Authorization
Section titled “Payment & Authorization”| Field | Type | Nullable | Description |
|---|---|---|---|
| payment_option_primary | string | nullable | Primary payer or insurance provider |
| payment_option_primary_group_number | string | nullable | Group number for primary insurance |
| payment_option_primary_subscriber_id | string | nullable | Subscriber ID for primary insurance |
| payment_plan_primary | string | nullable | Payment plan for primary payer |
| payment_option_secondary | string | nullable | Secondary payer or insurance provider |
| payment_option_secondary_group_number | string | nullable | Group number for secondary insurance |
| payment_option_secondary_subscriber_id | string | nullable | Subscriber ID for secondary insurance |
| payment_plan_secondary | string | nullable | Payment plan for secondary payer |
| pre_authorization_number | string | nullable | Insurance pre-authorization number |
| external_authorization | string | nullable | External system authorization reference |
| travel_authorization_number | string | nullable | Travel-specific authorization number |
| gl_code | string | nullable | General ledger code for billing |
| case_number | string | nullable | External case or reference number |
Round Trip & Return
Section titled “Round Trip & Return”| Field | Type | Nullable | Description |
|---|---|---|---|
| is_round_trip_first_trip | boolean | | True if this request is the outbound leg of a round trip |
| is_round_trip_return_trip | boolean | | True if this request is the return leg of a round trip |
| round_trip_other_service_request_id | string | nullable | Service request ID of the linked trip leg |
| wait_and_return | boolean | nullable | Indicates if crew should wait at destination for return |
| return_on_will_call | boolean | nullable | Indicates if return trip is on will-call |
Override & Dry Run
Section titled “Override & Dry Run”| Field | Type | Nullable | Description |
|---|---|---|---|
| override_approver | string | nullable | Name of person who approved a service level override |
| override_reason | array | nullable | Reasons provided for the service level override |
| dry_run_reason | array | nullable | Reasons for dry run (crew arrived but patient was not transported) |
Location Object Structure
Section titled “Location Object Structure”All location fields share this structure:
| Field | Type | Nullable | Description |
|---|---|---|---|
| address | string | nullable | Full formatted address string |
| city | string | nullable | City name |
| country | string | nullable | Country name |
| lat | number | nullable | GPS latitude coordinate |
| lng | number | nullable | GPS longitude coordinate |
| name | string | nullable | Location display name or facility name |
| state | string | nullable | State or province abbreviation |
| street | string | nullable | Street address line |
| zip | string | nullable | ZIP or postal code |