REST API and webhooks for your chauffeur site

Bookings, quotes, customers and catalogue in JSON, on your site's domain. Signed webhooks for every event. Included in the Pro+ and Leader plans, with no per-call costs.

GET /site

Request

curl https://tuodominio.it/connect/api/v1/site \
  -H "Authorization: Bearer $TOSIU_API_KEY"
$ch = curl_init('https://tuodominio.it/connect/api/v1/site');
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('TOSIU_API_KEY')],
  CURLOPT_RETURNTRANSFER => true,
]);
$site = json_decode(curl_exec($ch), true)['data'];
const res = await fetch('https://tuodominio.it/connect/api/v1/site', {
  headers: { Authorization: `Bearer ${process.env.TOSIU_API_KEY}` },
});
const { data: site } = await res.json();

Response 200 OK

JSON
{
  "data": {
    "name": "Example Transfers",
    "domain": "tuodominio.it",
    "languages": {
      "primary": "it",
      "supported": [
        "it",
        "en"
      ]
    },
    "currency": "EUR",
    "timezone": "Europe/Rome",
    "booking_mode": "vehicle_class",
    "pricing_method": "manual",
    "payment_methods": {
      "cash": true,
      "card_on_arrival": false,
      "online_providers": [
        "stripe"
      ]
    },
    "booking_rules": {
      "max_passengers": 16,
      "min_booking_days": 0,
      "cancellation_hours": 24
    },
    "tours_available": true,
    "api_version": "v1"
  }
}
Base URL
https://tuodominio.it/connect/api/v1
Format
JSON, UTF-8, HTTPS only
Authentication
Bearer token with permissions
Version
v1, updated on 2 November 2026
Endpoints
32 endpoints, 11 events

Overview

Every Tosiu site exposes its API on its own domain. Bookings created through the API go through the same chain as the site: same price calculation, same emails to the customer, same availability rules. The booking's history records which key created it.

Your back office uses it to stay in sync, your developer uses it for an app or a price list, partners use it to book on behalf of their customers.

What lives where

API
tuodominio.it/connect/api/v1
Keys, permissions, call log
Panel, Integrations, Public API
Full documentation
tuodominio.it/connect/docs
OpenAPI contract
tuodominio.it/connect/openapi.json

Resources

ResourceEndpointsPermissions
Site profile1any key
Bookings8bookings:read bookings:write
Quotes2quotes:read quotes:write
Catalogue6catalog:read
Availability3availability:read
Customers4customers:read customers:write
Drivers and fleet2drivers:read fleet:read
Webhooks3webhooks:manage
Other3partners:read

Authentication

Every request carries the key in the Authorization header, never in the URL. Alternatively you can use the X-Api-Key header. Of the plain value only the copy we show you at creation remains: we store the fingerprint.

curl https://tuodominio.it/connect/api/v1/bookings \
  -H "Authorization: Bearer tsk_live_3kP9..."
curl https://tuodominio.it/connect/api/v1/bookings \
  -H "X-Api-Key: tsk_live_3kP9..."
  • A key is valid for a single domain: used elsewhere it answers 403 site_mismatch.
  • You can restrict it to your supplier's IP addresses.
  • Every key has only the permissions you give it: without the right permission the response is 403 missing_scope, with the name of the permission.
  • Revocation from the panel is immediate and final. To rotate a key you create a new one and revoke the old one.

Permissions

PermissionWhat it unlocks
any keyGET /site
bookings:readGET /bookingsGET /bookings/{ref}GET /bookings/{ref}/events
bookings:writePOST /bookingsPATCH /bookings/{ref}POST /bookings/{ref}/cancelPOST /bookings/{ref}/payment-linkPOST /bookings/{ref}/pay-request
quotes:readGET /quotes/{number}
quotes:writePOST /quotes
customers:readGET /customersGET /customers/{id}
customers:writePOST /customersPATCH /customers/{id}
webhooks:manageGET /webhooksPOST /webhooksDELETE /webhooks/{id}
catalog:readGET /locationsGET /routesGET /vehicle-classesGET /extrasGET /toursGET /shuttles
availability:readGET /tours/{slug}/availabilityGET /shuttles/{slug}/runsGET /schedule-blocks
partners:readGET /partner-requestsGET /partner-requests/{id}GET /partner-requests/{id}/documents/{doc}
drivers:readGET /drivers
fleet:readGET /fleet

Requests and responses

A few rules, the same for every endpoint.

Amounts as strings
Always text ("180.00") with the currency code next to it: no floating-point rounding.
Site local time
Pickup and return are the local clock. The updated_since filters are ISO 8601 in UTC.
Paginated lists
page and per_page (maximum 100), with data and meta in every response.
Language
?lang= selects the language of the catalogue names, among those active on the site.
A list
{
  "data": [
    {
      "booking_ref": "TCV1042",
      "status": "confirmed",
      "pickup_datetime": "2026-08-02 10:30:00",
      "price": {
        "currency": "EUR",
        "total": "180.00"
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 41,
    "has_more": true
  }
}

Errors

Every error returns with the right HTTP status and an error object: a stable code, a readable message and, when needed, the field that is wrong. Your program reads the code: within v1 it never changes.

422 Unprocessable Entity
{
  "error": {
    "code": "invalid_parameter",
    "message": "pickup_datetime must be YYYY-MM-DD HH:MM",
    "field": "pickup_datetime"
  }
}

HTTP statuses

400
Invalid request: broken JSON or HTTP without the S.
401
Key missing, unknown, expired or revoked.
403
Wrong domain, IP address or permission.
404
Resource does not exist on this site.
409
State conflict, for example a booking already cancelled.
422
Parameter missing or out of range, or the engine rejected the request.
429
Per-minute limit exceeded: Retry-After says how long to wait.
5xx
Error on our side or the payment provider's: nothing was changed.
All 54 error codes
CodeStatusMeaning
https_required400The request arrived over plain HTTP. This API is HTTPS only.
missing_key401No API key was sent. Use Authorization: Bearer, or the X-Api-Key header.
invalid_key401The key is malformed or unknown.
key_revoked401The key was revoked by the website operator. Revocation is permanent: ask for a new key.
key_expired401The key passed its expiry date.
site_mismatch403The key belongs to a different website than the domain it was sent to. A key works on exactly one domain.
ip_not_allowed403The key has an IP allowlist and the request did not come from it.
missing_scope403The key does not carry the scope this endpoint needs. The scope name is in the body.
rate_limited429The key passed its per-minute limit. Retry-After says how long to wait.
not_found404No such endpoint in v1.
unknown_api_version404The path names an API version this site does not serve. The current version is v1.
method_not_allowed405The resource exists but not with that method. The Allow header lists the methods it does answer.
invalid_json400The request body is not valid JSON.
invalid_parameter422A parameter is missing, malformed or out of range. The offending one is named in "field".
invalid_idempotency_key422Idempotency-Key must be 1-128 characters of A-Z a-z 0-9 . _ : and -
idempotency_key_reuse422This Idempotency-Key was already used on this endpoint with a different body. Use a fresh key for a new request.
idempotency_in_progress409The original request with this Idempotency-Key is still running. Retry after the seconds in Retry-After; do not send a new key, or you may create a second booking.
booking_not_found404No booking with that reference on this site. Abandoned searches and trashed bookings are never exposed.
booking_not_editable409The booking is in a state that can no longer be edited (for example already cancelled).
booking_not_cancellable409The booking is in a state that cannot be cancelled.
booking_not_awaiting_payment409The booking is not awaiting an online payment, so there is no payment link to send.
payment_not_online409The booking uses an offline payment method (cash, bank transfer): nothing to pay online.
email_failed502The customer email could not be sent (the site's mail transport refused it). The payment link itself is valid.
booking_conflict409The booking engine refused because of a conflict, for example a tour departure that filled up while the request was in flight.
booking_create_failed422The booking engine refused to create the booking. The message says why.
booking_confirm_failed422The trip was priced but the confirmation step was refused. Nothing was created.
own_google_key_required403Pricing a trip runs on the site's own Google key and this site has none. POST /bookings takes the price you send.
account_limited403The site's account has no active plan: pricing a trip is not available.
quote_failed422The trip could not be priced: usually an address outside the service area, or a route the site does not sell.
reprice_failed422The edit could not be repriced by the site's pricing engine, so nothing was changed.
luggage_does_not_fit422The luggage and equipment asked for do not fit the chosen vehicle class. Pick a larger class.
location_not_found422No active location with that id on this site. See GET /locations.
vehicle_class_required422This site sells by vehicle class, so vehicle_class_id is required. See GET /vehicle-classes.
vehicle_class_not_found422No enabled vehicle class with that id on this site.
invalid_payment_method422That payment method is not enabled on this site. See GET /site.
payment_provider_unavailable503The online payment provider could not be reached, so the booking was not created. Retry, or use an offline payment method.
tour_extra_invalid422A tour add-on was addressed with a malformed key or quantity.
tour_not_found404No active tour with that slug on this site. See GET /tours.
booking_awaiting_payment409The booking is still awaiting its checkout payment: use POST /bookings/{ref}/payment-link.
booking_not_payable409A pay request needs a confirmed transfer or tour.
booking_already_paid409Nothing is owed on this booking.
online_payment_unavailable409This site cannot take online payments: no provider is switched on, or the plan does not include them.
pay_request_failed422The pay request could not be created.
quote_not_found404No quote with that number on this site. Deleted quotes are never exposed.
shuttle_not_found404No active shuttle with that slug on this site. See GET /shuttles.
tour_not_bookable409The tour is sold on request (sale_mode "request" in GET /tours): it has no online availability or checkout.
customer_not_found404No customer with that id on this site.
customer_email_taken409Another live customer on this site already uses that email address.
webhook_not_found404No webhook subscription with that id on this site.
webhook_url_exists409A subscription for that URL already exists. Delete it first; that is also how a secret is rotated.
webhook_limit_reached422A site can hold at most 10 webhook subscriptions.
partner_request_not_found404No partner request with that id on this site. Deleted requests are not readable by id.
document_not_found404No document with that id on this partner request. Use the url listed in its documents.
internal_error500Something failed on this server. Nothing was changed. If it persists, contact the website operator.

Limits and idempotency

Every key has a per-minute request limit, chosen in the panel. Every response says how many remain; beyond the limit you get a 429 in JSON with Retry-After. POST requests accept an Idempotency-Key: if the same request is sent twice, for example after a timeout, the second one receives the original response and does not create a second booking.

curl -X POST https://tuodominio.it/connect/api/v1/bookings \
  -H "Authorization: Bearer $TOSIU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8812" \
  -d @booking.json
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 18

{"error":{"code":"rate_limited","message":"..."}}
  • Idempotency-Key: 1 to 128 characters, valid for 24 hours.
  • Same key and same body: identical response, with Idempotency-Replay: true.
  • Same key and different body: 422 idempotency_key_reuse.

Webhooks

You register an HTTPS address with POST /webhooks and choose the events. At every event you receive the complete booking, with the same structure as GET /bookings/{ref}, signed with the secret you receive only once at registration.

Headers of every delivery

X-Tosiu-Event
the event name
X-Tosiu-Delivery
unique id, to discard duplicates
X-Tosiu-Timestamp
Unix seconds of the attempt
X-Tosiu-Signature
sha256= HMAC of timestamp.body

Retries

A delivery succeeds if your server answers 2xx within 10 seconds. Otherwise we retry:

  1. 11 min
  2. 25 min
  3. 330 min
  4. 42 hours
  5. 56 hours

From the panel you see the delivery log and can resend one. Up to 10 addresses per site.

Webhook deliverieshttps://gestionale.tuosito.it/hooks/tosiu

  • booking.creatednow delivered
  • booking.payment_updated12 min delivered
  • booking.assigned41 min delivered

Signed HMAC SHA-256

Verifying the signature

import crypto from 'node:crypto';

// rawBody: the request body exactly as received, before JSON.parse
function isFromTosiu(rawBody, headers, secret) {
  const ts = headers['x-tosiu-timestamp'];
  const expected = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(ts + '.' + rawBody).digest('hex');
  const given = headers['x-tosiu-signature'] || '';
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}
$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_TOSIU_TIMESTAMP'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_TOSIU_SIGNATURE'] ?? '')) {
  http_response_code(401);
  exit;
}
$event = json_decode($body, true);

Events

booking.createdA booking was created and confirmed (status may be awaiting_payment for online methods). For a tour booking, tour.booked fires as well.
booking.updatedA booking was edited: dates, passengers, price, status or any other field. Deliveries carry the full updated booking object.
booking.cancelledA booking was cancelled (customer-visible cancellation, never a deletion).
booking.payment_updatedA payment changed the booking's payment status (e.g. an online payment completed).
booking.assignedA driver or partner was assigned to a booking leg (or the leg was unassigned).
booking.deletedA booking was moved to trash by the operator. Unlike booking.cancelled this is a back-office action: the booking disappears from API reads. A restore fires booking.updated.
quote.acceptedA quote was accepted and converted into a booking; the payload carries the quote number and the new booking_ref.
partner_request.createdA partner application was submitted from the site's "become a partner" form (a draft that gets submitted fires this too, with the same id).
partner_request.updatedThe operator decided a partner application (approved, rejected) or archived it. Deliveries carry the full updated object; review.decided_at and review.partner_id say what happened.
partner_request.deletedThe operator deleted a partner application: it disappears from reads (GET /partner-requests?include_deleted=true still lists it with deleted_at). The payload carries deleted_at.
tour.bookedA tour was booked (fires alongside booking.created when service_type is tour).

Endpoints

Generated from the API's public contract: when v1 changes, this list changes too. Open an endpoint to see parameters and examples.

Site profile

GET/siteThe site's public profile: languages, currency, booking mode, pricing method, payment methods, booking rules. Call this FIRST: it tells you which shape of quote or booking request this site accepts.any key

The site's public profile: languages, currency, booking mode, pricing method, payment methods, booking rules. Call this FIRST: it tells you which shape of quote or booking request this site accepts.

curl https://tuodominio.it/connect/api/v1/site \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": {
    "name": "Example Transfers",
    "domain": "tuodominio.it",
    "languages": {
      "primary": "it",
      "supported": [
        "it",
        "en"
      ]
    },
    "currency": "EUR",
    "timezone": "Europe/Rome",
    "booking_mode": "vehicle_class",
    "pricing_method": "manual",
    "payment_methods": {
      "cash": true,
      "card_on_arrival": false,
      "online_providers": [
        "stripe"
      ]
    },
    "booking_rules": {
      "max_passengers": 16,
      "min_booking_days": 0,
      "cancellation_hours": 24
    },
    "tours_available": true,
    "api_version": "v1"
  }
}

Bookings

GET/bookingsList bookings, newest pickup first (or oldest update first with updated_since, for sync clients). Abandoned searches and trashed bookings are never returned.bookings:read

List bookings, newest pickup first (or oldest update first with updated_since, for sync clients). Abandoned searches and trashed bookings are never returned.

Parameters

NameWhereTypeDescription
pagequeryintegerPage number, from 1.
per_pagequeryintegerRows per page, 1-100 (default 25).
statusquerystringOne of: pending, awaiting_payment, confirmed, cancelled, completed, no_show.
service_typequerystring"transfer", "tour" or "shuttle".
from_datequerystringYYYY-MM-DD, site-local pickup date (inclusive lower bound).
to_datequerystringYYYY-MM-DD, site-local pickup date (inclusive upper bound).
customer_emailquerystringExact customer email (case-insensitive).
booking_refquerystringExact booking reference.
updated_sincequerystringISO 8601 timestamp (UTC assumed without offset); switches ordering to updated_at ascending.
curl "https://tuodominio.it/connect/api/v1/bookings?status=confirmed&per_page=2" \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "booking_ref": "TCV1042",
      "status": "confirmed",
      "payment_status": "pending",
      "service_type": "transfer",
      "trip_type": "one_way",
      "pickup_datetime": "2026-08-02 10:30:00",
      "return_datetime": null,
      "from": {
        "location_id": 12,
        "address": null,
        "place_id": null,
        "iata": "TRN",
        "lat": 45.2008000000000009777068044058978557586669921875,
        "lng": 7.64970000000000016626700016786344349384307861328125
      },
      "to": {
        "location_id": 15,
        "address": null,
        "place_id": null,
        "iata": null,
        "lat": 45.9365999999999985448084771633148193359375,
        "lng": 7.6296999999999997044142219237983226776123046875
      },
      "passengers": {
        "adults": 2,
        "children": 0,
        "infants": 0,
        "total": 2
      },
      "price": {
        "currency": "EUR",
        "total": "180.00",
        "base": "180.00",
        "amount_online": null,
        "amount_due": "180.00",
        "amount_paid": "0.00",
        "amount_outstanding": "180.00"
      },
      "payment_method": "cash",
      "created_at": "2026-07-28 09:12:44",
      "updated_at": "2026-07-28 09:13:02"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 2,
    "total": 41,
    "has_more": true
  }
}
GET/bookings/{ref}One booking by its reference. The same object shape every webhook delivery carries in data.booking.bookings:read

One booking by its reference. The same object shape every webhook delivery carries in data.booking.

Parameters

NameWhereTypeDescription
refrequiredpathstringThe booking reference (e.g. TCV1042).
curl https://tuodominio.it/connect/api/v1/bookings/TCV1042 \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": {
    "booking_ref": "TCV1042",
    "status": "confirmed",
    "payment_status": "pending",
    "service_type": "transfer",
    "trip_type": "one_way",
    "pickup_datetime": "2026-08-02 10:30:00",
    "from": {
      "location_id": 12,
      "lat": 45.2008000000000009777068044058978557586669921875,
      "lng": 7.64970000000000016626700016786344349384307861328125
    },
    "to": {
      "location_id": 15,
      "lat": 45.9365999999999985448084771633148193359375,
      "lng": 7.6296999999999997044142219237983226776123046875
    },
    "passengers": {
      "adults": 2,
      "children": 0,
      "infants": 0,
      "total": 2
    },
    "vehicle": {
      "vehicle_class_id": 3,
      "class_key": "sedan",
      "name": "Berlina",
      "max_passengers": 3,
      "luggage": 3,
      "quantity": 1,
      "price_per_vehicle": "180.00"
    },
    "customer": {
      "first_name": "Mario",
      "last_name": "Rossi",
      "email": "mario.rossi@example.com",
      "phone": "+39333000000",
      "language": "it"
    },
    "flight_number": "AZ1234",
    "pickup_sign": "Rossi family",
    "invoice": {
      "requested": false,
      "status": "none",
      "details": null
    },
    "price": {
      "currency": "EUR",
      "total": "180.00"
    },
    "payment_method": "cash",
    "payment_link": null,
    "extras": [],
    "created_at": "2026-07-28 09:12:44",
    "updated_at": "2026-07-28 09:13:02"
  }
}
GET/bookings/{ref}/eventsThe booking's change trail, oldest first: created, edited, status changes, payments, cancellations, assignments, emails sent - with who did it (website, operator, API key label) and when.bookings:read

The booking's change trail, oldest first: created, edited, status changes, payments, cancellations, assignments, emails sent - with who did it (website, operator, API key label) and when.

Parameters

NameWhereTypeDescription
refrequiredpathstringThe booking reference.
page, per_pagequeryintegerStandard pagination.
curl https://tuodominio.it/connect/api/v1/bookings/TCV1042/events \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "id": 901,
      "event": "created",
      "actor": {
        "type": "customer",
        "name": null
      },
      "summary": "Booking created",
      "note": null,
      "created_at": "2026-07-28 09:12:44"
    },
    {
      "id": 905,
      "event": "edited",
      "actor": {
        "type": "api",
        "name": "My integration"
      },
      "summary": "Pickup time changed",
      "note": null,
      "created_at": "2026-07-28 10:02:11"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 2,
    "has_more": false
  }
}
POST/bookingsCreate a confirmed booking in one call, at the price YOU send: the API does not calculate prices and never looks an address up.bookings:write

Create a confirmed booking in one call, at the price YOU send: the API does not calculate prices and never looks an address up. Returns 201 with the booking and its manage_url. The booking is recorded like one the operator enters by hand (price locked, to be paid as agreed with the method you name); no online checkout is started. Send an Idempotency-Key: a retry with the same key replays the first answer and creates nothing.

accepts Idempotency-Key

Parameters

NameWhereTypeDescription
Idempotency-KeyheaderstringCaller-chosen unique key (1-128 chars). A repeat within 24h replays the original response and creates nothing.
from_location_id / from_addressrequiredbodyinteger / stringPickup: a location id (GET /locations) OR the address as text in from_address (optional from_lat + from_lng). A Google place id alone is refused: the API does not look places up.
to_location_id / to_addressrequiredbodyinteger / stringDestination, same rules as the pickup.
pickup_datetimerequiredbodystring"YYYY-MM-DD HH:MM", site-local wall clock.
trip_typebodystring"one_way" (default) or "round_trip" (then return_datetime is required).
adults, children, infantsbodyintegerPassenger split (adults defaults to 1).
vehicle_class_idbodyintegerRequired on booking_mode=vehicle_class sites (GET /vehicle-classes).
pricerequiredbodynumberThe fare of the trip in the site currency, as a number (180 or "180.00"). Required: the API does not calculate prices. Extras are added on top at their catalogue price.
customerrequiredbodyobject{first_name, last_name, email, phone}, all required.
languagebodystringThe customer's language (one of the site's supported set); drives the confirmation emails.
payment_methodrequiredbodystringHow the booking will be paid: one of the site's payment methods (GET /site), recorded on the booking. The API charges nothing.
extrasbodyarray[{extra_type_id, quantity}] from GET /extras.
send_emailbodybooleantrue (default) sends the customer the site's confirmation email; false sends nothing.
flight_number, pickup_address, dropoff_address, customer_notes, ...bodystringTravel details, incl. the return_* twins on round trips; internal_notes is operator-only.
pickup_signbodystringName on the driver's pickup sign at airport pickups, optional, max 80; empty = the booking name.
invoice_requestedbodybooleantrue = the customer wants an invoice for this booking; the confirmation and the booking page then ask the customer for the billing details (read them back in invoice.details).
curl -X POST https://tuodominio.it/connect/api/v1/bookings \
  -H "Authorization: Bearer tsk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f9d2c1e-order-8812" \
  -d '{
    "from_location_id": 12, "to_location_id": 15,
    "pickup_datetime": "2026-08-02 10:30",
    "adults": 2, "vehicle_class_id": 3,
    "price": 180,
    "customer": {"first_name": "Mario", "last_name": "Rossi",
                 "email": "mario.rossi@example.com", "phone": "+39333000000"},
    "payment_method": "cash"
  }'
{
  "data": {
    "booking_ref": "TCV1043",
    "status": "confirmed",
    "payment_status": "pending",
    "price": {
      "currency": "EUR",
      "total": "180.00",
      "amount_due": "180.00"
    },
    "manage_url": "https://tuodominio.it/booking/TCV1043?pass=..."
  }
}
PATCH/bookings/{ref}Edit a booking: the operator-console field set (contact, addresses, travel details, passengers, dates, trip_type, vehicle_class_id, extras, promo_code, payment_method, price_override), repriced by the same engine.bookings:write

Edit a booking: the operator-console field set (contact, addresses, travel details, passengers, dates, trip_type, vehicle_class_id, extras, promo_code, payment_method, price_override), repriced by the same engine. An ABSENT key leaves the stored value alone, extras included; an explicit [] clears them. A price_override PINS the total (price_locked=true in the booking): later edits keep it whatever else changes; send price_override "" or null to unpin and re-price. A captured online amount is never rewritten; the balance adjusts. notify_customer=true sends the operator's own "booking updated" email. The API never asks Google: an edit never looks an address up or recalculates a route; set the price yourself with price_override.

Parameters

NameWhereTypeDescription
refrequiredpathstringThe booking reference.
notify_customerbodybooleanSend the customer the updated-booking email (default false).
pickup_signbodystringName on the driver's pickup sign at airport pickups, max 80; "" or null clears it (the driver uses the booking name).
invoice_requestedbodybooleantrue = the customer wants an invoice for this booking; the confirmation and the booking page then ask the customer for the billing details (read them back in invoice.details).
curl -X PATCH https://tuodominio.it/connect/api/v1/bookings/TCV1043 \
  -H "Authorization: Bearer tsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"pickup_datetime": "2026-08-02 11:15", "notify_customer": true}'
{
  "data": {
    "booking_ref": "TCV1043",
    "status": "confirmed",
    "pickup_datetime": "2026-08-02 11:15:00",
    "price": {
      "currency": "EUR",
      "total": "180.00"
    }
  },
  "notified": true
}
POST/bookings/{ref}/cancelCancel a booking (customer-visible; the API never deletes). Optional reason code, note and refund_amount; notify_customer=true sends the cancellation email.bookings:write

Cancel a booking (customer-visible; the API never deletes). Optional reason code, note and refund_amount; notify_customer=true sends the cancellation email.

accepts Idempotency-Key

Parameters

NameWhereTypeDescription
refrequiredpathstringThe booking reference.
reasonbodystringOne of: customer_request, no_show, duplicate, payment_failed, unavailable, weather, other.
notebodystringFree-text note stored on the cancellation.
refund_amountbodynumberRecorded refund; a positive amount sets payment_status to refunded.
notify_customerbodybooleanSend the cancellation email (default false).
curl -X POST https://tuodominio.it/connect/api/v1/bookings/TCV1043/cancel \
  -H "Authorization: Bearer tsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"reason": "customer_request", "notify_customer": true}'
{
  "data": {
    "booking_ref": "TCV1043",
    "status": "cancelled",
    "cancellation_reason": "customer_request",
    "cancelled_at": "2026-07-30 15:04:11"
  },
  "notified": true
}
POST/bookings/{ref}/payment-linkResend the payment link of a booking that is still awaiting its online payment (the card failed, the customer closed the gateway tab).bookings:write

Resend the payment link of a booking that is still awaiting its online payment (the card failed, the customer closed the gateway tab). Emails the customer the "complete your payment" message and returns payment_link: the customer's booking page, whose "Pay now" restarts the gateway checkout, so the same link works until the payment goes through (share it by WhatsApp or SMS too). 409 booking_not_awaiting_payment on any other status; 409 payment_not_online on an offline method.

accepts Idempotency-Key

Parameters

NameWhereTypeDescription
refrequiredpathstringThe booking reference.
send_emailbodybooleanEmail the customer the payment link (default true). false only returns the link.
curl -X POST https://tuodominio.it/connect/api/v1/bookings/TCV1043/payment-link \
  -H "Authorization: Bearer tsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"send_email": true}'
{
  "data": {
    "booking_ref": "TCV1043",
    "status": "awaiting_payment",
    "payment_status": "failed",
    "payment_method": "sumup",
    "payment_link": "https://tuodominio.it/my-booking?ref=TCV1043&pass=..."
  },
  "emailed": true
}
POST/bookings/{ref}/pay-requestAsk the customer to pay a CONFIRMED booking online (the operator panel's "Richiedi pagamento"): returns pay_url, a link on the site's own /pay page, paid through the site's gateway.bookings:write

Ask the customer to pay a CONFIRMED booking online (the operator panel's "Richiedi pagamento"): returns pay_url, a link on the site's own /pay page, paid through the site's gateway. The money lands on the booking and booking.payment_updated fires. One open request per booking: asking again returns the open one (200, existing true) unless replace is true. No email is sent unless send_email is true. Cancelling the booking, or lowering what is owed below the amount asked, closes the link. For a booking still awaiting_payment use /payment-link. 409 booking_awaiting_payment, booking_not_payable, booking_already_paid, online_payment_unavailable.

accepts Idempotency-Key

Parameters

NameWhereTypeDescription
refrequiredpathstringThe booking reference.
purposebodystringbalance (default: all that is still owed), deposit or custom.
percentbodyintegerdeposit: 1 to 99 (default the site's deposit percent).
amountbodynumbercustom: the amount, from 1 up to what is still owed.
expiry_daysbodyinteger0 (no expiry), 7 (default), 30 or 90.
send_emailbodybooleanEmail the customer the link too (default false).
replacebodybooleanCancel the open request and make a new one (default false).
curl -X POST https://tuodominio.it/connect/api/v1/bookings/TCV1043/pay-request \
  -H "Authorization: Bearer tsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"purpose": "balance"}'
{
  "data": {
    "booking_ref": "TCV1043",
    "request_ref": "P7KQ2M9X",
    "purpose": "balance",
    "amount": "184.00",
    "currency": "EUR",
    "expires_at": "2026-11-09 10:00:00",
    "pay_url": "https://tuodominio.it/pay/P7KQ2M9X",
    "amount_outstanding": "184.00"
  },
  "existing": false,
  "emailed": false
}

Quotes

GET/quotes/{number}One quote document by its number (e.g. PREV-0001): the trip, passengers, price, validity, customer, delivery trail, public_url (the page the customer opens, null until shared), and the booking_ref once accepted.quotes:read

One quote document by its number (e.g. PREV-0001): the trip, passengers, price, validity, customer, delivery trail, public_url (the page the customer opens, null until shared), and the booking_ref once accepted. `expired` is derived from valid_until at read time. Deleted quotes are never returned.

Parameters

NameWhereTypeDescription
numberrequiredpathstringThe quote number as shown to the operator and the customer (case-insensitive).
curl https://tuodominio.it/connect/api/v1/quotes/PREV-0001 \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": {
    "quote_number": "PREV-0001",
    "status": "sent",
    "public_url": "https://tuodominio.it/quote/HX7ZQ6J8",
    "valid_until": "2026-08-10",
    "trip_type": "one_way",
    "pickup_datetime": "2026-08-05 10:30:00",
    "return_datetime": null,
    "from": {
      "location_id": 12,
      "address": null,
      "place_id": null,
      "lat": 45.92999999999999971578290569595992565155029296875,
      "lng": 7.62000000000000010658141036401502788066864013671875
    },
    "to": {
      "location_id": 15,
      "address": null,
      "place_id": null,
      "lat": 45.469999999999998863131622783839702606201171875,
      "lng": 9.1899999999999995026200849679298698902130126953125
    },
    "distance_km": 98.400000000000005684341886080801486968994140625,
    "duration_minutes": 95,
    "passengers": {
      "adults": 2,
      "children": 0,
      "infants": 0,
      "total": 2
    },
    "vehicle_class_id": 3,
    "price": {
      "total": "180.00",
      "currency": "EUR"
    },
    "customer": {
      "first_name": "Mario",
      "last_name": "Rossi",
      "email": "mario.rossi@example.com",
      "phone": "+39333000000"
    },
    "notes": null,
    "booking_ref": null,
    "created_at": "2026-07-30 09:12:00",
    "sent_at": "2026-07-30 09:15:02",
    "viewed_at": null,
    "accepted_at": null
  }
}
POST/quotesPrice a trip WITHOUT creating anything: the full breakdown (base, extras, discounts, deposit split) from the same engine the checkout uses; optional extras, promo_code and payment_method are priced in.quotes:write

Price a trip WITHOUT creating anything: the full breakdown (base, extras, discounts, deposit split) from the same engine the checkout uses; optional extras, promo_code and payment_method are priced in. Only on a site that uses its OWN Google key (else 403 own_google_key_required).

accepts Idempotency-Key

Parameters

NameWhereTypeDescription
(trip fields)requiredbodyobjectfrom_location_id / to_location_id (see GET /locations), or on formula sites from_place_id / to_place_id (Google place ids) with from_address / to_address (the label); pickup_datetime, trip_type, return_datetime on a round trip, adults / children / infants, vehicle_class_id where the site sells by class.
curl -X POST https://tuodominio.it/connect/api/v1/quotes \
  -H "Authorization: Bearer tsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"from_location_id": 12, "to_location_id": 15,
       "pickup_datetime": "2026-08-02 10:30", "adults": 2, "vehicle_class_id": 3}'
{
  "data": {
    "currency": "EUR",
    "trip": {
      "from_location_id": 12,
      "to_location_id": 15,
      "pickup_datetime": "2026-08-02 10:30:00",
      "return_datetime": null,
      "trip_type": "one_way",
      "passengers": {
        "adults": 2,
        "children": 0,
        "infants": 0
      },
      "vehicle_class_id": 3,
      "distance_km": 98.400000000000005684341886080801486968994140625,
      "duration_minutes": 95
    },
    "breakdown": {
      "base_price": "180.00",
      "route_discount": "0.00",
      "outbound_price": "180.00",
      "outbound_night_supplement": null,
      "return_price": null,
      "return_night_supplement": null,
      "roundtrip_discount": null,
      "extras": [],
      "extras_total": "0.00",
      "promo_code": null,
      "promo_discount": null,
      "payment_discount": null,
      "grand_total": "180.00"
    },
    "payment": {
      "method": null,
      "payment_type": "full",
      "deposit_percent": null,
      "amount_online": null,
      "amount_due": "180.00"
    }
  }
}

Catalogue

GET/locationsThe site's active preset locations (the from/to ids POST /bookings accepts). ?lang= picks the display language.catalog:read

The site's active preset locations (the from/to ids POST /bookings accepts). ?lang= picks the display language.

Parameters

NameWhereTypeDescription
langquerystringOne of the site's supported languages.
page, per_pagequeryintegerStandard pagination.
curl https://tuodominio.it/connect/api/v1/locations \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "id": 12,
      "name": "Torino Airport",
      "slug": "torino-airport",
      "type": "Airport",
      "iata": "TRN",
      "lat": 45.2008000000000009777068044058978557586669921875,
      "lng": 7.64970000000000016626700016786344349384307861328125,
      "country": "IT",
      "fixed_address": null
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 9,
    "has_more": false
  }
}
GET/routesThe site's active routes with stored prices where the site publishes them (per fleet tier in capacity mode, per vehicle class otherwise; formula-pricing sites expose no stored prices).catalog:read

The site's active routes with stored prices where the site publishes them (per fleet tier in capacity mode, per vehicle class otherwise; formula-pricing sites expose no stored prices).

Parameters

NameWhereTypeDescription
lang, page, per_pagequerymixedDisplay language + standard pagination.
curl https://tuodominio.it/connect/api/v1/routes \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "id": 31,
      "slug": "torino-airport-cervinia",
      "from": {
        "location_id": 12,
        "name": "Torino Airport"
      },
      "to": {
        "location_id": 15,
        "name": "Cervinia"
      },
      "distance_km": 98.400000000000005684341886080801486968994140625,
      "duration_minutes": 95,
      "class_prices": [
        {
          "vehicle_class_id": 3,
          "price": "180.00"
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 14,
    "has_more": false
  }
}
GET/vehicle-classesThe enabled vehicle classes on a booking_mode=vehicle_class site: capacity, luggage, the id POST /bookings wants. A class the operator sells on request only is not listed (and not bookable here).catalog:read

The enabled vehicle classes on a booking_mode=vehicle_class site: capacity, luggage, the id POST /bookings wants. A class the operator sells on request only is not listed (and not bookable here).

Parameters

NameWhereTypeDescription
lang, page, per_pagequerymixedDisplay language + standard pagination.
curl https://tuodominio.it/connect/api/v1/vehicle-classes \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "id": 3,
      "class_key": "sedan",
      "category": "sedan",
      "name": "Berlina",
      "min_passengers": 1,
      "max_passengers": 3,
      "luggage": 3,
      "carryon": 3,
      "models": "Mercedes E-Class",
      "badge": null
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 4,
    "has_more": false
  }
}
GET/extrasThe bookable extras (child seats, luggage, equipment): the extra_type_id, price, free flag, max quantity and boot-space units the booking engine enforces. Extras the operator created carry category "custom".catalog:read

The bookable extras (child seats, luggage, equipment): the extra_type_id, price, free flag, max quantity and boot-space units the booking engine enforces. Extras the operator created carry category "custom".

Parameters

NameWhereTypeDescription
lang, page, per_pagequerymixedDisplay language + standard pagination.
curl https://tuodominio.it/connect/api/v1/extras \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "extra_type_id": 10,
      "name": "Baby seat (0-13 kg)",
      "category": "child_safety",
      "child_related": true,
      "free": true,
      "price": null,
      "max_quantity": 2,
      "qty_basis": "per_booking",
      "space_units": 0
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 7,
    "has_more": false
  }
}
GET/toursThe site's active tours with their variants and prices, and the public URL of each tour page.catalog:read

The site's active tours with their variants and prices, and the public URL of each tour page. sale_mode says how a tour is sold: "book" (online, through the availability endpoint and the checkout) or "request" (enquiry-only: no availability, no online price).

Parameters

NameWhereTypeDescription
lang, page, per_pagequerymixedDisplay language + standard pagination.
curl https://tuodominio.it/connect/api/v1/tours \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "id": 5,
      "slug": "wine-tour",
      "title": "Wine Tour",
      "subtitle": "A day among the vineyards",
      "category": "food_wine",
      "tour_type": "private",
      "sale_mode": "book",
      "duration_minutes": 480,
      "min_participants": 2,
      "max_participants": 8,
      "url": "https://tuodominio.it/tours/wine-tour",
      "options": [
        {
          "id": 11,
          "name": "Full day",
          "price_model": "per_group",
          "price_group": "550.00",
          "price_tiers": [],
          "duration_minutes": 480
        }
      ],
      "resources": []
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 3,
    "has_more": false
  }
}
GET/shuttlesThe site's active shared shuttles (per-seat services, sold on the site at /shuttle): event, pickup mode, party-size rules, boarding cutoff, the lowest per-person one-way fare (price_from, null when nothing is priced yet), the public page URL, the origins the shuttle serves (fixed stops or door-to-door zones, each a fare_id with its own status) and the destination.catalog:read

The site's active shared shuttles (per-seat services, sold on the site at /shuttle): event, pickup mode, party-size rules, boarding cutoff, the lowest per-person one-way fare (price_from, null when nothing is priced yet), the public page URL, the origins the shuttle serves (fixed stops or door-to-door zones, each a fare_id with its own status) and the destination. ?lang= picks the display language. Shuttle bookings are read via GET /bookings with service_type "shuttle"; v1 has no shuttle write endpoints - seats are sold by the site's own checkout.

Parameters

NameWhereTypeDescription
lang, page, per_pagequerymixedDisplay language + standard pagination.
curl https://tuodominio.it/connect/api/v1/shuttles \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "id": 1,
      "slug": "navetta-monsterland-2026",
      "name": "Navetta Monsterland 2026",
      "status": "active",
      "event": {
        "id": 2,
        "name": "Halloween Imola 2026",
        "starts_on": "2026-10-31",
        "ends_on": "2026-11-01"
      },
      "pickup_mode": "stops",
      "min_pax_per_booking": 2,
      "max_pax_per_booking": 16,
      "boarding_cutoff_min": 15,
      "price_from": "20.00",
      "url": "https://tuodominio.it/shuttle/navetta-monsterland-2026",
      "origins": [
        {
          "fare_id": 7,
          "type": "stop",
          "name": "Faenza - Stazione FS",
          "status": "active"
        },
        {
          "fare_id": 8,
          "type": "zone",
          "name": "Castel San Pietro Terme",
          "status": "active"
        }
      ],
      "destination": {
        "stop_id": 5,
        "name": "Imola - Hub Evento Autodromo"
      }
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "has_more": false
  }
}

Availability

GET/tours/{slug}/availabilityLive availability for one tour, from the same engine the checkout uses: it never shows a slot the confirmation step would refuse.availability:read

Live availability for one tour, from the same engine the checkout uses: it never shows a slot the confirmation step would refuse. ?month=YYYY-MM answers a per-day grid (available / sold_out / closed with slot and seat counts; a fully closed month also carries next_open, the next date the schedule runs, or null); ?date=YYYY-MM-DD answers the bookable time slots per variant, with seats left. A request-only tour (sale_mode "request") answers 409 tour_not_bookable.

Parameters

NameWhereTypeDescription
slugrequiredpathstringThe tour slug (GET /tours).
monthquerystringYYYY-MM: one of month or date is required.
datequerystringYYYY-MM-DD: one of month or date is required.
optionqueryintegerA variant id from GET /tours; 0 or absent means any variant.
curl "https://tuodominio.it/connect/api/v1/tours/wine-tour/availability?date=2026-08-12" \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": {
    "tour_id": 5,
    "slug": "wine-tour",
    "date": "2026-08-12",
    "window": {
      "first": "2026-07-30",
      "last": "2027-01-26"
    },
    "options": [
      {
        "option_id": 11,
        "slots": [
          {
            "time": "09:00",
            "seats_left": 8,
            "sold_out": false
          }
        ]
      }
    ]
  }
}
GET/shuttles/{slug}/runsLive run availability for one shuttle, from the same engine the site checkout uses: it never shows a run the confirmation step would refuse.availability:read

Live run availability for one shuttle, from the same engine the site checkout uses: it never shows a run the confirmation step would refuse. Without ?date= it answers the upcoming service dates per direction (out / ret), each with the number of sellable runs. With ?date=YYYY-MM-DD it answers that day's runs: fixed time or time window, the final time once set, capacity, seats left, the derived state (available / nearly_full / sold_out), the confirming flag (departure below its minimum, still collecting) and confirmed flag (departure confirmed), and the per-person adult and child fares. ?direction= narrows to one leg. An unknown or inactive shuttle answers 404 shuttle_not_found.

Parameters

NameWhereTypeDescription
slugrequiredpathstringThe shuttle slug (GET /shuttles).
datequerystringYYYY-MM-DD: the day whose runs to list. Absent = the dates map per direction.
directionquerystring"out" (to the destination) or "ret" (the return). Absent = both.
curl "https://tuodominio.it/connect/api/v1/shuttles/navetta-monsterland-2026/runs?date=2026-10-31&direction=out" \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": {
    "shuttle_id": 1,
    "slug": "navetta-monsterland-2026",
    "date": "2026-10-31",
    "runs": [
      {
        "id": 10,
        "fare_id": 7,
        "direction": "out",
        "timing_mode": "window",
        "depart_time": null,
        "window_start": "15:00",
        "window_end": "17:00",
        "final_time": null,
        "capacity_max": 8,
        "min_seats": 2,
        "seats_left": 6,
        "state": "available",
        "confirming": true,
        "confirmed": false,
        "fare": {
          "adult": "25.00",
          "child": "25.00"
        }
      },
      {
        "id": 11,
        "fare_id": 7,
        "direction": "out",
        "timing_mode": "window",
        "depart_time": null,
        "window_start": "17:00",
        "window_end": "19:00",
        "final_time": null,
        "capacity_max": 8,
        "min_seats": 2,
        "seats_left": 0,
        "state": "sold_out",
        "confirming": false,
        "confirmed": true,
        "fare": {
          "adult": "25.00",
          "child": "25.00"
        }
      }
    ]
  }
}
GET/schedule-blocksThe operator's calendar blocks: date windows where transfer bookings are blocked or capped (block_type, optional daily time window, optional max_bookings). Useful before proposing a pickup date.availability:read

The operator's calendar blocks: date windows where transfer bookings are blocked or capped (block_type, optional daily time window, optional max_bookings). Useful before proposing a pickup date.

Parameters

NameWhereTypeDescription
from_datequerystringYYYY-MM-DD: only blocks overlapping this date or later.
to_datequerystringYYYY-MM-DD: only blocks overlapping this date or earlier.
page, per_pagequeryintegerStandard pagination.
curl "https://tuodominio.it/connect/api/v1/schedule-blocks?from_date=2026-08-01" \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "id": 36,
      "date_start": "2026-08-15",
      "date_end": "2026-08-16",
      "time_start": null,
      "time_end": null,
      "time_mode": "daily",
      "block_type": "blocked",
      "max_bookings": null,
      "reason": "Ferragosto",
      "created_at": "2026-07-22 00:49:26"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "has_more": false
  }
}

Customers

GET/customersList the operator's customer registry. Filters: email (exact), search (name, company, email, phone), updated_since, pagination.customers:read

List the operator's customer registry. Filters: email (exact), search (name, company, email, phone), updated_since, pagination.

Parameters

NameWhereTypeDescription
emailquerystringExact email match.
searchquerystringMatches name, company, email or phone.
updated_sincequerystringISO 8601 timestamp; switches ordering to updated_at ascending.
page, per_pagequeryintegerStandard pagination.
curl "https://tuodominio.it/connect/api/v1/customers?search=rossi" \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "id": 88,
      "type": "private",
      "first_name": "Mario",
      "last_name": "Rossi",
      "email": "mario.rossi@example.com",
      "phone": "+39333000000",
      "language": "it",
      "created_at": "2026-06-01 10:00:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "has_more": false
  }
}
GET/customers/{id}One customer by id.customers:read

One customer by id.

Parameters

NameWhereTypeDescription
idrequiredpathintegerThe customer id.
curl https://tuodominio.it/connect/api/v1/customers/88 \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": {
    "id": 88,
    "type": "private",
    "first_name": "Mario",
    "last_name": "Rossi",
    "email": "mario.rossi@example.com",
    "phone": "+39333000000",
    "language": "it",
    "vat_number": null,
    "created_at": "2026-06-01 10:00:00"
  }
}
POST/customersCreate a customer. At least one of first_name, last_name or company_name. A live customer already holding the email answers 409 customer_email_taken; a soft-deleted one is revived.customers:write

Create a customer. At least one of first_name, last_name or company_name. A live customer already holding the email answers 409 customer_email_taken; a soft-deleted one is revived.

accepts Idempotency-Key

Parameters

NameWhereTypeDescription
typebodystring"private" (default), "business", "association" (APS, ASD, non-profit: company_name + tax_code, vat_number optional; an Italian one gets sdi_code "0000000"), "ncc" (a chauffeur firm buying services) or "airline". Reads may also return agency, hotel, apartment or collaborator.
first_name, last_name, company_name, email, phone, language, vat_number, tax_code, sdi_code, pec_email, billing_*bodystringThe registry fields; billing_country is an ISO code.
curl -X POST https://tuodominio.it/connect/api/v1/customers \
  -H "Authorization: Bearer tsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Mario", "last_name": "Rossi", "email": "mario.rossi@example.com"}'
{
  "data": {
    "id": 89,
    "type": "private",
    "first_name": "Mario",
    "last_name": "Rossi",
    "email": "mario.rossi@example.com",
    "created_at": "2026-07-30 15:20:00"
  }
}
PATCH/customers/{id}Edit a customer: absent keys are left alone; the same email-collision rule as POST.customers:write

Edit a customer: absent keys are left alone; the same email-collision rule as POST.

Parameters

NameWhereTypeDescription
idrequiredpathintegerThe customer id.
curl -X PATCH https://tuodominio.it/connect/api/v1/customers/88 \
  -H "Authorization: Bearer tsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"phone": "+39334000000"}'
{
  "data": {
    "id": 88,
    "first_name": "Mario",
    "last_name": "Rossi",
    "phone": "+39334000000"
  }
}

Drivers and fleet

GET/driversThe operator's driver registry, for a dispatch integration: name, contact, licence number, calendar colour, status, and the partner id for partner-supplied drivers.drivers:read

The operator's driver registry, for a dispatch integration: name, contact, licence number, calendar colour, status, and the partner id for partner-supplied drivers.

Parameters

NameWhereTypeDescription
page, per_pagequeryintegerStandard pagination.
curl https://tuodominio.it/connect/api/v1/drivers \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "id": 30,
      "type": "own",
      "first_name": "Luca",
      "last_name": "Bianchi",
      "email": "luca@example.com",
      "phone": "+39333000000",
      "licence_number": null,
      "colour": "#2563eb",
      "status": "active",
      "partner_id": null,
      "created_at": "2026-07-18 18:53:56",
      "updated_at": "2026-07-18 18:53:56"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 4,
    "has_more": false
  }
}
GET/fleetThe operator's real vehicles (make, model, plate, seats, luggage, ownership, status) - not the bookable classes, which are GET /vehicle-classes. vehicle_class_id links a car to the class it serves.fleet:read

The operator's real vehicles (make, model, plate, seats, luggage, ownership, status) - not the bookable classes, which are GET /vehicle-classes. vehicle_class_id links a car to the class it serves.

Parameters

NameWhereTypeDescription
page, per_pagequeryintegerStandard pagination.
curl https://tuodominio.it/connect/api/v1/fleet \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "id": 12,
      "make": "Mercedes",
      "model": "Classe V",
      "plate": "GA123XY",
      "year": null,
      "colour": null,
      "seats": 8,
      "luggage": 6,
      "ownership": "owned",
      "status": "active",
      "vehicle_class_id": 7,
      "created_at": "2026-07-18 18:53:56",
      "updated_at": "2026-07-18 18:53:56"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 2,
    "has_more": false
  }
}

Webhooks

GET/webhooksList this site's webhook subscriptions. The secret is never returned here: it is shown once, in the POST response.webhooks:manage

List this site's webhook subscriptions. The secret is never returned here: it is shown once, in the POST response.

curl https://tuodominio.it/connect/api/v1/webhooks \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "id": 3,
      "url": "https://example-gestionale.com/hooks/tosiu",
      "events": [
        "booking.created",
        "booking.cancelled"
      ],
      "status": "active",
      "last_delivery": {
        "at": "2026-07-30 15:00:12",
        "status": 200,
        "error": null
      },
      "created_at": "2026-07-30 12:00:00"
    }
  ],
  "meta": {
    "total": 1
  }
}
POST/webhooksSubscribe a public HTTPS URL to events. The response carries the signing secret EXACTLY ONCE: store it, every delivery is signed with it. Max 10 subscriptions per site; one per URL (delete to rotate the secret).webhooks:manage

Subscribe a public HTTPS URL to events. The response carries the signing secret EXACTLY ONCE: store it, every delivery is signed with it. Max 10 subscriptions per site; one per URL (delete to rotate the secret).

accepts Idempotency-Key

Parameters

NameWhereTypeDescription
urlrequiredbodystringA public HTTPS URL. Private and loopback hosts are refused.
eventsrequiredbodyarrayNon-empty list from the event catalog above.
curl -X POST https://tuodominio.it/connect/api/v1/webhooks \
  -H "Authorization: Bearer tsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example-gestionale.com/hooks/tosiu",
       "events": ["booking.created", "booking.cancelled"]}'
{
  "data": {
    "id": 3,
    "url": "https://example-gestionale.com/hooks/tosiu",
    "events": [
      "booking.created",
      "booking.cancelled"
    ],
    "status": "active",
    "secret": "whsec_9f2c4a7e1b8d3f6c5a0e7b4d9c2f1a8e",
    "created_at": "2026-07-30 12:00:00"
  }
}
DELETE/webhooks/{id}Delete a subscription. Pending deliveries are dropped; the delivery history stays visible in the dashboard.webhooks:manage

Delete a subscription. Pending deliveries are dropped; the delivery history stays visible in the dashboard.

Parameters

NameWhereTypeDescription
idrequiredpathintegerThe subscription id (GET /webhooks).
curl -X DELETE https://tuodominio.it/connect/api/v1/webhooks/3 \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": {
    "id": 3,
    "deleted": true
  }
}

Other

GET/partner-requestsThe "become a partner" applications sent from the site. Default: every submitted one (new, approved, rejected, archived), newest first.partners:read

The "become a partner" applications sent from the site. Default: every submitted one (new, approved, rejected, archived), newest first. A sync client passes updated_since (ordering becomes updated_at ascending; the boundary second is re-read, dedupe by id) and include_deleted=true to see deletions. Drafts (started, never submitted) only with status=draft: they carry draft.missing and draft.continue_url.

Parameters

NameWhereTypeDescription
statusquerystringOne or more, comma separated: new, approved, rejected, archived, draft. Default: new,approved,rejected,archived.
updated_sincequerystringISO 8601 timestamp; switches ordering to updated_at ascending.
include_deletedquerybooleantrue also returns requests the operator deleted (deleted_at set). Default false.
langquerystringLanguage of the draft.missing labels (a supported site language); default the site's primary.
page, per_pagequeryintegerStandard pagination.
curl "https://tuodominio.it/connect/api/v1/partner-requests?updated_since=2026-09-27T06:00:00Z" \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": [
    {
      "id": 531,
      "status": "new",
      "company_name": "Rossi NCC S.r.l.",
      "legal_form": "srl",
      "vat_number": "IT01234567890",
      "fiscal_code": "01234567890",
      "city": "Rimini",
      "contact_name": "Mario Rossi",
      "phone": "+393331234567",
      "email": "info@rossincc.example",
      "pec": "rossincc@pec.example",
      "sdi_code": "M5UXCR1",
      "iban": "IT60X0542811101000000123456",
      "services": [
        "private_transfer"
      ],
      "vehicles": [
        {
          "plate": "AB123CD",
          "make": "Mercedes",
          "model": "Classe E",
          "year": 2022,
          "seats": 3,
          "luggage": 3,
          "licence_type": "ncc_auto",
          "licence_number": "7",
          "licence_comune": "Rimini"
        }
      ],
      "documents": [
        {
          "id": "3f9c2a7e1b8d4c6e",
          "kind": "libretto",
          "plate": "AB123CD",
          "name": "libretto.pdf",
          "size": 184220,
          "content_type": "application/pdf",
          "url": "https://tuodominio.it/connect/api/v1/partner-requests/531/documents/3f9c2a7e1b8d4c6e"
        }
      ],
      "consent": {
        "privacy": true,
        "marketing": false,
        "declaration": true,
        "accepted_at": "2026-09-27 06:12:40",
        "language": "it"
      },
      "review": {
        "decided_at": null,
        "note": null,
        "network_level": null,
        "partner_id": null,
        "notified_at": null
      },
      "draft": null,
      "created_at": "2026-09-27 06:12:40",
      "updated_at": "2026-09-27 06:12:40",
      "deleted_at": null
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "has_more": false
  }
}
GET/partner-requests/{id}One partner request by id, with every field of the form (the keys are the form's own, a new form field appears here as a new key), vehicles, documents (download each with its url, same key), consent, review, and for a draft: last_saved_at, continue_url and missing (fields, units, documents with their form labels).partners:read

One partner request by id, with every field of the form (the keys are the form's own, a new form field appears here as a new key), vehicles, documents (download each with its url, same key), consent, review, and for a draft: last_saved_at, continue_url and missing (fields, units, documents with their form labels).

Parameters

NameWhereTypeDescription
idrequiredpathintegerThe partner request id.
langquerystringLanguage of the draft.missing labels.
curl https://tuodominio.it/connect/api/v1/partner-requests/524 \
  -H "Authorization: Bearer tsk_live_..."
{
  "data": {
    "id": 524,
    "status": "draft",
    "company_name": "Bianchi Viaggi",
    "vat_number": "IT09876543210",
    "vehicles": [
      {
        "plate": "GL238EK",
        "make": "Mercedes",
        "model": "Classe V"
      }
    ],
    "documents": [],
    "consent": {
      "privacy": false,
      "marketing": false,
      "declaration": false,
      "accepted_at": null
    },
    "draft": {
      "last_saved_at": "2026-09-27 04:35:08",
      "continue_url": "https://tuodominio.it/portal/register?role=partner&draft=...",
      "missing": {
        "fields": [],
        "units_needed": false,
        "units": [],
        "documents": [
          {
            "plate": "GL238EK",
            "kinds": [
              {
                "key": "libretto",
                "label": "Carta di circolazione"
              },
              {
                "key": "licence",
                "label": "Licenza o documento autorizzativo"
              }
            ]
          }
        ],
        "documents_generic": false
      },
      "reminder": {
        "sent_at": null,
        "count": 0
      }
    },
    "created_at": "2026-09-27 04:20:11",
    "updated_at": "2026-09-27 04:35:08",
    "deleted_at": null
  }
}
GET/partner-requests/{id}/documents/{doc}Download one document of a partner request (PDF or JPEG, Content-Disposition attachment). {doc} is the id in the request's documents list; the documents[].url field is this exact URL.partners:read

Download one document of a partner request (PDF or JPEG, Content-Disposition attachment). {doc} is the id in the request's documents list; the documents[].url field is this exact URL. Authenticated like every call: never share the URL without the key.

Parameters

NameWhereTypeDescription
idrequiredpathintegerThe partner request id.
docrequiredpathstringThe document id (16 hex characters) from documents[].id.
curl -OJ https://tuodominio.it/connect/api/v1/partner-requests/531/documents/3f9c2a7e1b8d4c6e \
  -H "Authorization: Bearer tsk_live_..."
(binary: application/pdf or image/jpeg)

Partner widget

For those without a developer there's the embeddable booking form: you put it on a hotel's or an agency's site and their bookings come to you, already attributed to that partner.

  • One widget per partner, with its routes and its prices
  • Colours, language and steps are configured from the panel
  • It can be paused without removing the code from their site
HTML
<iframe src="https://tuodominio.it/connect/iframe/LA_CHIAVE_DEL_WIDGET"
        width="100%" height="720" style="border:0"
        title="Prenota un transfer"></iframe>

Versions and changes

v1 is a published contract: fields are added, they don't disappear and don't change name. A change that breaks integrations will become a v2, and v1 will keep answering. The latest additions:

  1. restricted_notes entries can now carry mode:'carfree': the trip touches a car-free area (the historic centre of Venice) and that side was driven to the closest point a car reaches (Piazzale Roma).

  2. New: POST /bookings/{ref}/pay-request (scope bookings:write) asks the customer to pay a confirmed booking online and returns pay_url, a link on the site's own /pay page to share by WhatsApp; no email unless send_email is true.

  3. Tour boats / vehicles (additive, read-only): GET /tours lists for each tour the resources a customer chooses between, resources [{id, kind (boat | vehicle | other), name, capacity, sale_mode (book | request), supplement}] ([] = no choice); tour bookings carry tour.resource {id, name, kind} (null when none); ?date= availability slots carry resources {id: free} when the tour has resources (seats_left = the largest capacity still free).

  4. GET /tours: every option carries an additive read-only field, price_tiers (group-size bands [{max, price}] of a per_group variant: a party of N pays the first band whose max is at least N; an empty list means the single price_group).

The full log is in the documentation on your domain.

Getting started

  1. 1
    Open Integrations, Public API

    In your panel you find keys, permissions, webhooks and the call log.

  2. 2
    Create the key

    Give it a name, choose only the permissions needed, copy the value: it's shown only once.

  3. 3
    Call GET /site

    It tells you languages, currency, payment methods and how this site wants its requests.

Your chauffeur website, ready in a few clicks.

You set it up yourself, with the AI guiding you: no expertise needed. No commitment, no automatic renewal.