API de Taxi

Get drivers in viewport with automatic clustering based on zoom level. Returns clusters for areas with many drivers and individual markers for areas below the clustering threshold. The clustering behavior adapts based on zoom level: - Street view (zoom >= 17): Always show individual drivers - City view (zoom <= 8): Cluster aggressively (> 2 drivers) - Standard zoom: Cluster when > 5 drivers in a cell # Arguments * input.bounds - Viewport bounds (sw/ne corners) * input.zoom - Map zoom level (1-20) * input.online_status - Optional filter by Online or Busy # Example

graphqlquery {
adminDriverMap(input: {
bounds: {
sw: { latitude: 40.70, longitude: -74.02 }
ne: { latitude: 40.75, longitude: -73.97 }
}
zoom: 14
}) {
clusters {
h3Index
count
centroid { latitude longitude }
onlineCount
busyCount
}
singles {
driverId
coordinates { latitude longitude heading }
onlineStatus
lastUpdatedAt
}
h3Resolution
totalCount
}
}

# Authorization Requires TenantAdmin or PlatformAdmin role.

List the service classes of a specific tenant (PlatformAdmin only). Mirrors serviceClassesAdmin but takes the target tenant from the argument instead of the request context, so platform admins can inspect a tenant they're not impersonating. Used by the admin tenant detail page.

Get available ride options for a specific service class Returns all active ride options with their pricing configuration # Arguments * service_class_id - The service class to get options for * currency - Currency to display fees in (defaults to USD)

Get the current dispatch configuration. Returns the active dispatch config for the current tenant.

Get all dispatch configuration revisions. Returns the history of dispatch config changes for this tenant.

Get dispatch configuration by version. Useful for previewing or rolling back to a previous version.

Get a single driver by ID with all related data. # Authorization Requires TenantAdmin or PlatformAdmin role.

Get driver's credit/debit records. # Authorization Requires TenantAdmin or PlatformAdmin role.

Get driver leaderboard. # Authorization Requires TenantAdmin or PlatformAdmin role.

List drivers with filtering and pagination. # Authorization Requires TenantAdmin or PlatformAdmin role.

Explain whether a driver is eligible for a given service class. Runs the same EligibilityEvaluator the dispatch path uses, so the answer is authoritative — no chance of admin and dispatch disagreeing. When the driver is ineligible, returns the structured reasons so support can pinpoint the failing dimension. # Authorization Requires TenantAdmin or PlatformAdmin role.

Get driver statistics/KPIs. # Authorization Requires TenantAdmin or PlatformAdmin role.

Get a single group flat fare by ID. # Authorization Requires TenantAdmin role.

List group flat fares with pagination and filtering. # Authorization Requires TenantAdmin role.

Get active taxi rides for the current user, scoped to the role they're acting under for this request. The same account can hold both Customer and Driver roles (common in dev and for tenants where drivers also ride as passengers). If we returned the union we'd leak the user's own passenger-side dispatching order into the driver app, which then renders it as an active trip and hides the actual ride-offer Accept UI. So we scope by request_ctx.role.

Get pending ride offers for the current driver. Returns only non-expired offers sorted by creation time (newest first).

Get nearby driver coordinates for map display. Returns 5-20 nearby available drivers around a center point for UI visualization. This is a lightweight query - it only returns driver IDs, coordinates, and ratings. # Arguments * input.center - Center coordinates to search from * input.limit - Max drivers to return (5-20, default 10) * input.radius_meters - Search radius in meters (default 5000m) # Example

graphqlquery {
nearbyDriversForMap(input: {
center: { latitude: 40.7128, longitude: -74.0060 }
limit: 15
}) {
driverId
coordinates { latitude longitude }
rating
}
}

Get recent unique travel locations (pickup/dropoff addresses) from order history. Returns locations deduplicated by coordinates, ordered by most recent usage. Useful for showing users their frequently used addresses for quick selection. # Arguments * limit - Maximum number of unique locations to return (default: 5, max: 20) # Example

graphqlquery {
recentTravelLocations(limit: 5) {
id
coordinates { latitude longitude }
formattedAddress
label
kind
lastUsedAt
}
}

Get a single ride option pricing by ID. # Authorization Requires TenantAdmin role. # Arguments * id - Ride option pricing ID * currency - Currency to display fee in (defaults to USD)

List ride option pricings with pagination and filtering. # Authorization Requires TenantAdmin role. # Arguments * input - Filter and pagination options * currency - Currency to display fees in (defaults to USD)

Get a single service class by ID for admin. # Authorization Requires TenantAdmin role.

List service classes for admin with pagination. # Authorization Requires TenantAdmin role.

Read the calling tenant's taxi-operations toggles. Returns the "all-on" default when no row exists yet.

Public, unauthenticated live view of a shared trip, addressed by its share token. Returns null for unknown, expired, or revoked tokens alike (no enumeration signal). Intended to be polled by a logged-out "follow my ride" web page. The gateway must allow this query through without authentication and rate-limit it by token/IP (tracked as the pre-prod gateway carve-out).

Get the current tenant's vehicle catalog config. Returns the "show everything" defaults when no row exists yet — so callers always get a non-null payload they can render straight into the settings UI.

Get paginated list of active vehicle colors Returns colors available for the tenant (tenant overrides + global colors). Results are ordered by position.

List vehicle colors for admin with pagination. # Authorization Requires TenantAdmin role.

Get paginated list of active vehicle makes Returns makes available for the tenant (tenant overrides + global makes). Results are ordered by position.

List vehicle makes for admin with pagination. # Authorization Requires TenantAdmin role.

Get paginated list of active vehicle models Returns models available for the tenant (tenant overrides + global models). Optionally filter by make_id. Results are ordered by position.

List vehicle models for admin with pagination. # Authorization Requires TenantAdmin role.

Get a single zone flat fare by ID. # Authorization Requires TenantAdmin role.

List zone flat fares with pagination and filtering. # Authorization Requires TenantAdmin role.

Get a single zone surcharge by ID. # Authorization Requires TenantAdmin role.

List zone surcharges with pagination and filtering. # Authorization Requires TenantAdmin role.

Driver accepts a dispatched taxi order

Add credit to a driver's wallet. # Authorization Requires TenantAdmin or PlatformAdmin role.

Approve a driver (approves their KYC application). # Authorization Requires TenantAdmin or PlatformAdmin role.

Approve a driver's photo. Sets the driver's photo status to Approved. # Authorization Requires TenantAdmin or PlatformAdmin role.

Driver marks arrival at a specific waypoint (pickup, intermediate stop, or dropoff)

Driver marks arrival at destination (ride complete)

Driver marks arrival at pickup location

Manually assign a driver to an order. # Authorization Requires TenantAdmin or PlatformAdmin role. # Arguments * input - The driver assignment input containing orderId, driverId, and optional force flag # Returns The assignment response containing success status, updated order, and optional message. # Errors - Unauthorized: If caller is not an admin - NotFound: If order or driver does not exist - InvalidState: If order is not in a dispatchable state or driver is not approved - InvalidState: If order already has a driver and force=false

Swap the payment method used for an active taxi order. Allowed any time before the payment for the order is captured (i.e. from booking through end-of-ride payment confirmation). The new method is authorized / debited first; only on success is the previous method voided or refunded. # Errors - INVALID_INPUT — missing/extra payment_method_id for the chosen type. - INVALID_STATE — order is in a terminal state, already captured, or the new method needs 3DS verification (not supported in swap flow today). - PAYMENT_FAILED — PSP declined the new method. - UNAUTHORIZED — caller is not the order owner.

Confirm the metered fare submitted by driver. Called by passenger after reviewing the driver-submitted fare. Once confirmed, payment is captured and the ride is completed.

Confirm a pending payment after 3DS or other client-side authentication. This mutation is called when a customer completes payment authentication (e.g., 3DS) for an order that was in PendingPayment status. On success: - The order will transition to Dispatching status - A dispatch job will be enqueued to find drivers On failure: - A payment block will be created for the customer - The order will be cancelled - The customer must resolve the payment issue before creating new orders

Create a new driver. Creates an account (if needed) and a driver record with all provided details including vehicle information, profile photo, and address. # Authorization Requires TenantAdmin or PlatformAdmin role. # Input Fields - Account: email, phone, first_name, last_name, gender, country_code, profile_photo_upload_id - Address: address_line1, address_line2, city, state, postal_code, address_country_code - License: license_number, license_expiry - Vehicle: vehicle_model_id, vehicle_color_id, vehicle_year, plate_number - Assignment: zone_id

Create a new group flat fare. # Authorization Requires TenantAdmin role.

Create a new ride option pricing. # Authorization Requires TenantAdmin role.

Create a new service class. # Authorization Requires TenantAdmin role.

Mint (or re-fetch) a public "follow my ride" link for one of the caller's own active trips. Returns a stable link if one is already active for the trip.

Create a new vehicle color. # Authorization Requires TenantAdmin role.

Create a new vehicle make. # Authorization Requires TenantAdmin role.

Create a new vehicle model. # Authorization Requires TenantAdmin role.

Create a new zone flat fare. # Authorization Requires TenantAdmin role.

Create a new zone surcharge. # Authorization Requires TenantAdmin role.

Deduct credit from a driver's wallet. # Authorization Requires TenantAdmin or PlatformAdmin role.

Delete a driver (soft delete). # Authorization Requires TenantAdmin or PlatformAdmin role.

Delete a group flat fare (soft delete). # Authorization Requires TenantAdmin role.

Delete a ride option pricing (soft delete). # Authorization Requires TenantAdmin role.

Delete a service class. # Authorization Requires TenantAdmin role.

Delete a vehicle color. # Authorization Requires TenantAdmin role.

Delete a vehicle make. # Authorization Requires TenantAdmin role.

Delete a vehicle model. # Authorization Requires TenantAdmin role.

Delete a zone flat fare (soft delete). # Authorization Requires TenantAdmin role.

Delete a zone surcharge (soft delete). # Authorization Requires TenantAdmin role.

Driver departs from a waypoint (advances to next destination)

Add a global make ID to the tenant's hidden list. No-op if already hidden (idempotent so the UI can call it without checking state).

Driver initiates ride (passenger picked up)

Pay additional amount for an order that exceeded pre-authorization. When a ride's final cost exceeds the pre-authorized amount, the order enters PendingAdditionalPayment status. The customer must pay the excess amount before the order can be completed. This mutation processes the additional payment and, if successful, transitions the order to Completed status. # Arguments * input - Payment details including order ID and payment method # Returns Payment result with status and any required client actions (e.g., 3DS) # Errors - InvalidState - Order is not in PendingAdditionalPayment status - Unauthorized - Caller is not the order owner - PaymentFailed - Payment processing failed

Raise an SOS during an active trip. Emits a realtime safety alert and opens a maximum-priority support ticket for ops triage. Returns the ticket reference so the rider sees confirmation help is on the way.

Reject a driver (rejects their KYC application). # Authorization Requires TenantAdmin or PlatformAdmin role.

Reject a driver's photo with a reason. Sets the driver's photo status to Rejected and stores the rejection reason. # Authorization Requires TenantAdmin or PlatformAdmin role.

Driver rejects a dispatched taxi order

Driver retracts a previously submitted metered fee so they can re-enter it. Rolls the order back from PendingFeeConfirmation to PendingMeteredFee.

Revoke a share link the caller previously created. Returns true if a link was revoked, false if there was nothing to revoke.

Driver confirms rider paid in cash

Rollback dispatch configuration to a previous version. Creates a new version with the content from the specified version. Requires TenantAdmin role.

Set driver status to offline (unavailable for orders) This mutation: - Sets the driver as unavailable - Removes driver info from Redis cache (demotes from online pool)

Set driver status to online (available for orders) This mutation: - Validates that the driver is approved - Infers the zone from the provided coordinates - Updates the driver's location - Sets the driver as available - Promotes driver info to Redis cache for quick dispatch

Enable or disable one of the service classes the driver qualifies for. Disabling a class removes the driver from dispatch for it end-to-end: they stop receiving offers for it immediately while online, and are not indexed for it on their next go-online. Re-enabling restores it (subject to the driver still qualifying). In-flight offers/trips are unaffected. Returns the driver's refreshed manageable classes, each with its current on/off state.

Set the service classes for a driver. Replaces all existing service class assignments with the provided list. Pass an empty array to remove all service class assignments. # Authorization Requires TenantAdmin or PlatformAdmin role.

Set or clear a single (driver, service class) eligibility override. INCLUDE forces the driver eligible regardless of dynamic criteria. EXCLUDE forces the driver ineligible regardless of dynamic criteria. CLEAR removes any existing override; eligibility falls back to pure criteria evaluation (or to manual-roster check on Manual classes). Note: this only persists the override row. The driver's currently cached eligible-set updates next time they go online; for an immediate effect, an admin can also force-offline the driver. # Authorization Requires TenantAdmin or PlatformAdmin role.

Toggle a driver's VIP-class eligibility. Default is true for all drivers; admins flip to false to exclude a specific driver from VIP-tier dispatch (without revoking the qualifying ratings/vehicle). Requires TenantAdmin or PlatformAdmin role.

Toggle one or more taxi-operations availability flags for the calling tenant. Requires TenantOwner, TenantAdmin or PlatformAdmin.

Driver submits metered fee at end of ride

Submit vehicle details during driver onboarding This mutation: - Validates that the driver is in Pending status - Validates that the vehicle model and color exist - Updates the driver's vehicle information - Changes driver status to PendingReview for admin approval After calling this mutation, the driver must wait for admin approval before they can start accepting rides.

Remove a global make ID from the tenant's hidden list.

Update the dispatch configuration. Creates a new version and sets it as current. Requires TenantAdmin role.

Update an existing driver. Updates driver profile, license, vehicle, and photo information. Vehicle and photo updates trigger a pending review status. # Authorization Requires TenantAdmin or PlatformAdmin role.

Update driver's GPS location while online This mutation: - Updates driver's GPS coordinates in Redis cache - Recalculates H3 geospatial indexes if location changed significantly - Updates zone in PostgreSQL if driver moved to a different zone - Does NOT update PostgreSQL on every location ping (only Redis for performance)

Update an existing group flat fare. # Authorization Requires TenantAdmin role.

Update the wait/stopover time for an active taxi order. Recalculates the stopover fee based on the service class per-minute rate and updates the order total accordingly.

Update an existing ride option pricing. # Authorization Requires TenantAdmin role.

Update driver's preferred search radius for ride offers This mutation: - Persists the search radius to PostgreSQL - Updates Redis cache if the driver is currently online (dual-write) - Can be called whether driver is online or offline - Set to null to use service class default radius

Update an existing service class. # Authorization Requires TenantAdmin role.

Update the three include-globals toggles. Preserves any per-row hidden globals already set — switching the toggle off doesn't erase the cherry-picked suppressions.

Update an existing vehicle color. # Authorization Requires TenantAdmin role.

Update an existing vehicle make. # Authorization Requires TenantAdmin role.

Update an existing vehicle model. # Authorization Requires TenantAdmin role.

Update an existing zone flat fare. # Authorization Requires TenantAdmin role.

Update an existing zone surcharge. # Authorization Requires TenantAdmin role.

Subscribe to driver events (Taxi service) Receive real-time events relevant to taxi drivers: - New ride offers dispatched to you - Ride acceptance confirmations - Trip lifecycle events (start, complete, cancel) - Chat messages from passengers - Earnings updates - Notifications **Requirements:** - Must be authenticated - Must have Driver role - Must be using Taxi app Example:

graphqlsubscription {
driverEvents {
__typename
... on RideOfferEvent {
orderId
pickupAddress
fare
expiresAt
}
... on TripStartedEvent {
orderId
startedAt
}
}
}

Subscribe to passenger events (Taxi service) Receive real-time events relevant to taxi passengers: - Driver assignment notifications - Driver real-time location updates - Driver arrival notifications - Trip lifecycle events (start, complete, cancel) - Chat messages from driver - Notifications **Requirements:** - Must be authenticated - Must have Customer role - Must be using Taxi app Example:

graphqlsubscription {
passengerEvents {
__typename
... on DriverLocationUpdateEvent {
driverId
location {
lat
lng
}
eta
}
... on DriverArrivedEvent {
driverId
arrivedAt
}
}
}