Developer documentation · v1

Medical transportation quote API

Submit authorized private-pay NEMT requests, check progress and retrieve actual provider responses. This API uses MedicalRide’s existing quote operation, not a separate provider marketplace. Submission does not reserve a ride.

OpenAPI 3.1 contract · Current capabilities · Request API credentials

Individual assistants do not need developer credentials. Use the plain-text address form or email support@medicalride.org. No phone number, map selection or client Place ID is required.

Authentication and sandbox

Private operations require Authorization: Bearer YOUR_CREDENTIAL. MedicalRide issues revocable credentials scoped to a principal, with create/read permissions and either live or sandbox access. Keep credentials on your server—not in browser JavaScript. Every request and quote read checks ownership.

Request a sandbox credential first. Its mode is server-owned and cannot be overridden in a payload. Sandbox submissions are saved, but cannot geocode, create live ride requests, contact providers, send email/SMS or create real quotes. Use synthetic information only.

Create and retry safely

POST /api/agent/v1/quote-requests with Content-Type: application/json and an Idempotency-Key of 8–128 printable characters.

{
  "requesterName": "Example assistant",
  "email": "assistant@example.com",
  "role": "ai_assistant",
  "pickupAddress": "123 Example Street, Example City, NY 10001",
  "dropoffAddress": "456 Sample Road, Example City, NY 10002",
  "pickupCountry": "US",
  "dropoffCountry": "US",
  "rideType": "wheelchair",
  "date": "",
  "timing": "not_confirmed",
  "authorization": true,
  "contactConsent": true,
  "sensitiveDataConsent": true,
  "privatePay": true,
  "termsAccepted": true
}
Synthetic example only. These locations are not verified addresses. An unconfirmed date remains unconfirmed; never substitute today’s date or a dummy phone.

Return: HTTP 202 with a stable request_id, status, missing information, next action and a 30-second polling interval. The original acceptance response is returned for the same principal, key and normalized payload. A different payload with the same key returns 409. Keys are retained at least seven days. On a timeout or 503, retry the same key and payload with exponential backoff; do not create a new key.

Addresses, timing and clarification

Pickup and destination accept typed text. Include street, city, state/province and country; postal codes help. Optional endpoint city, region and postal-code fields are checked against the geocoder. Original text and access notes are preserved privately. Ambiguous facilities, partial matches, conflicting fields and materially changed addresses require clarification before routing. No city-centre coordinates are used as exact pickup points.

Dates use YYYY-MM-DD. Omit or leave the date empty if not confirmed. Timing can be exact, a same-day local-time window or not confirmed. Exact/window times use HH:mm. The pickup location determines the time zone shown on the private review page and API status. Nonexistent daylight-saving times need correction. No appointment time is invented.

For round trips or recurring travel, send returnDetails or recurringDetails, including uncertainty. Additional requested assistance is not a clinical or equipment suitability determination.

Geocoding failures do not discard the request. Use the private review link/access code emailed to the requester, or reply in the MedicalRide email thread with the reference. Update the existing request rather than resubmitting. After routing, changes go through Operations to preserve the current quote and provider-contact trail.

Read progress and provider quotes

GET /api/agent/v1/quote-requests/{request_id}

  • received: saved and awaiting validation.
  • needs_information: clarification is needed; read the questions.
  • finding_providers: valid request in the ordinary quote pathway.
  • quotes_available: provider responses are ready for review.
  • no_provider_found: no suitable response presently available; this is not a guarantee that none exists.
  • closed: no further quote search; this status alone does not confirm a booked ride.

GET /api/agent/v1/quote-requests/{request_id}/quotes returns provider, actual price text/currency, known inclusions/exclusions, conditions, cancellation policy and quote/expiry dates when supplied. Unknown terms remain null. An empty list is normal while waiting. MedicalRide does not generate provider prices, availability or cancellation policies to fill gaps.

Poll no faster than every 30 seconds. The patient or authorized representative chooses an option through the existing private tracking and booking flow.

Limits, errors and privacy

JSON bodies are limited to 24,000 bytes. Creation: 30 requests/minute per IP and 30/day per live principal (100/day sandbox), including retries. Reads: 60 status requests/minute and 30 quote reads/minute per IP. The form has separate rate limits. These are abuse limits, not an availability promise.

400 invalid JSON/key; 401 missing/revoked credentials; 404 unavailable or not owned; 409 key/payload conflict; 413 oversized body; 415 wrong content type; 422 invalid fields; 429 limit reached (obey Retry-After); 503 temporary issue (retry the same key). Stored requests and durable outreach work survive restarts.

Requester contact stays separate from passenger contact. Use a real requester email. Authorization assertions are recorded, not independently verified merely because the requester is an AI platform. Existing provider-sharing and booking rules apply. Email-only requests cannot expose a nonexistent patient phone or open a phone bridge. Share only necessary, authorized information. Private requests, API responses and tokens are not sitemap entries and are not cached for public use.

Privacy Policy · Terms