Rivelys API

Getting started

1. Create a partner account on rivelys.com and have your file approved.
2. In your account, API tab, create a test key (rv_test_…): bookings are simulated and never sent to chauffeurs.
3. Once your integration works, create a live key (rv_live_…): bookings become real rides.

API base URL: https://api.rivelys.com/v1. Send the key in the Authorization: Bearer rv_… header. Requests and responses are JSON (UTF-8), dates are ISO 8601. Keep the key on your server: never put it in a page your customers can see.

curl https://api.rivelys.com/v1 -H "Authorization: Bearer rv_test_••••••••"

Rules

• Fixed price. Rivelys calculates the price of each ride: the average of the prices of available, compatible chauffeurs (each with their own rates), without the highest and the lowest; with too few chauffeurs, the reference grid of the vehicle type. Ask for it with POST /v1/quotes, then book with this price in expected_price: if it changed in the meantime, the booking is refused with the new price (code price_changed). Once booked, the ride keeps its price.
• Minimum notice. Pick-up must be at least 48 hours after the request (current value returned in min_notice_hours).
• Payment, chosen by the partner: agency_card (the card saved in your account, charged ride by ride), monthly_invoice (monthly invoice of completed rides, paid by SEPA direct debit or bank transfer; enabled by Rivelys for your account, with a limit) or client_link (a link is sent to the passenger, who confirms and pays the chauffeur by card or in cash).
• Confirmation. The first vetted, compatible chauffeur who takes the ride gets it. When the partner pays, the ride is then confirmed; with client_link, the passenger confirms it on their link.
• Never cancelled automatically. If no chauffeur takes the ride, it is not cancelled: the Rivelys dispatch is alerted and finds a solution.
• Cancellation by the partner. Free until the ride is confirmed (POST /v1/bookings/{id}/cancel). After that, contact the Rivelys dispatch.
• Rate limit. 60 requests per minute per IP address.

Get a price

POST /v1/quotes: same fields as a booking (passenger and payment are optional). Nothing is booked.

curl https://api.rivelys.com/v1/quotes \
  -H "Authorization: Bearer rv_test_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "transfer",
    "pickup_at": "2026-12-20T14:30:00+01:00",
    "pickup_address": "Aéroport Nice Côte d'Azur, Terminal 2",
    "dropoff_address": "Hôtel de Paris, Monaco",
    "passengers": 2,
    "vehicle_type": "Business"
  }'

Response:

{
  "price": 92,
  "currency": "EUR",
  "price_basis": "average",
  "distance_km": 28,
  "duration_min": 40,
  "vehicle_type": "Business",
  "min_notice_hours": 48
}

price_basis: average (average of available chauffeurs) or reference_grid (reference grid).

Book

POST /v1/bookings: creates the booking (201). With an external_ref you already sent, the existing booking is returned (200): you can safely retry after a network error.

curl https://api.rivelys.com/v1/bookings \
  -H "Authorization: Bearer rv_test_••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "AG-2026-00042",
    "service": "transfer",
    "pickup_at": "2026-12-20T14:30:00+01:00",
    "pickup_address": "Aéroport Nice Côte d'Azur, Terminal 2",
    "dropoff_address": "Hôtel de Paris, Monaco",
    "flight_number": "AF7300",
    "passengers": 2,
    "luggage_hold": 2,
    "vehicle_type": "Business",
    "passenger": { "name": "John Smith", "phone": "+44 7700 900123", "language": "en" },
    "notes": "Name sign at arrivals",
    "payment": "agency_card",
    "expected_price": 92
  }'

Response:

{
  "id": "RV-4F2A9C",
  "external_ref": "AG-2026-00042",
  "environment": "live",
  "status": "searching",
  "service": "transfer",
  "pickup_at": "2026-12-20T13:30:00.000Z",
  "pickup_address": "Aéroport Nice Côte d'Azur, Terminal 2",
  "dropoff_address": "Hôtel de Paris, Monaco",
  "passengers": 2,
  "vehicle_type": "Business",
  "price": 92,
  "currency": "EUR",
  "payment": "agency_card",
  "passenger": { "name": "John Smith", "phone": "+44 7700 900123", "language": "en" },
  "client_link": "https://rivelys.com/suivi?t=…",
  "chauffeur": null,
  "created_at": "2026-12-01T09:12:44.000Z"
}

Track a booking

GET /v1/bookings/{id} (for example RV-4F2A9C) returns the up-to-date booking. GET /v1/bookings returns the latest ones (status and limit parameters, 100 at most). Poll a booking every few minutes, no more than once a minute.

As soon as a chauffeur takes the ride, chauffeur gives their name and car; once the ride is confirmed, their phone number and plate:

"status": "confirmed",
"chauffeur": {
  "name": "Karim B.",
  "vehicle": "Mercedes-Benz Classe E",
  "color": "Noir",
  "phone": "+33 6 12 34 56 78",
  "plate": "AB-123-CD"
}

Cancel

POST /v1/bookings/{id}/cancel: free while the status is searching or awaiting_client. For a confirmed ride, the response is 409 (cannot_cancel): contact the Rivelys dispatch.

Booking fields

Statuses

Errors

An error returns an HTTP status and an error object, with a message in English and in French:

{
  "error": {
    "code": "price_changed",
    "message": "The price is now 95 EUR. Check it and send the booking again with this expected_price.",
    "message_fr": "Le prix vient d’être recalculé : 95 €.",
    "price": 95,
    "currency": "EUR"
  }
}

Test keys

With an rv_test_… key, everything is checked as in live (fields, notice, real price), but nothing is sent to chauffeurs or charged. Bookings get a TEST-… reference and change status by themselves: searching for 1 minute, then a test chauffeur takes them (confirmed when the partner pays; awaiting_client then confirmed one minute later with client_link).

Help

A question about the API: contact@rivelys.com. For a ride in progress, contact the Rivelys dispatch from your account (“Contact the dispatch” button).