← moovlogic.com
Docs›BookingAPI›Create a Booking

Create a booking

Once you have a price quote and the passenger has confirmed, use this endpoint to submit the booking. The response includes the booking reference (tagName) you use for all subsequent operations.

The booking flow

ℹ️
Always call /api/v1/pricing/quotes first to get the fare. Pass the quoted accountFare back in quotedFare when creating the booking — this confirms the price shown to the customer.
1. GET  /api/v1/pricing/service-types        → choose vehicle type
2. POST /api/v1/pricing/quotes               → get live fare estimate
3. Customer reviews and confirms price
4. POST /api/v1/bookings                     → create booking → receive tagName
5. GET  /api/v1/bookings/{tagName}           → confirm booking details

Create a booking

POST /api/v1/bookings

Required fields

ParameterTypeDescription
serviceTypeId string (UUID) Vehicle category. Obtain from List service types.
pickupDateTimeUtc string (ISO 8601) Requested pickup time in UTC. Example: 2026-05-01T14:00:00Z. Must be in the future.
pickupAddress Address object Full pickup address. See Address object below.
dropoffAddress Address object Full drop-off address.
passengerName string Lead passenger's full name.
passengerEmail string (email) Passenger email address for confirmation and driver contact.
passengerPhone string Passenger phone number in international format, e.g. +447911123456.
quotedFare number (decimal) The fare amount from the pricing endpoint. Locks the price shown to the customer.
currency string (ISO 4217) Currency code, e.g. GBP, EUR, USD.

Optional fields

ParameterTypeDescription
passengers integer Number of passengers. Default: 1.
luggage integer Pieces of luggage. Default: 0.
flightNumber string For airport pickups. Enables automatic flight monitoring — if the flight is delayed, the dispatch system adjusts the pickup time.
notes string Special instructions visible to the driver (e.g. "Meet in arrivals hall, Terminal 5").
viaAddresses array of Address Intermediate stops, in order of visit. Each is an Address object.
returnJourney boolean Set to true if this booking includes a return leg.
returnDateTimeUtc string (ISO 8601) Return pickup time in UTC. Required when returnJourney is true.
accountId string (UUID) Customer account ID for billing and account-rate pricing.
externalReference string Your own booking reference. Stored and returned in GET responses. Max 100 characters.

Address object

Both pickupAddress and dropoffAddress (and each entry in viaAddresses) use this structure:

FieldTypeDescription
premiseName string Full formatted address string from Google Places (e.g. "Heathrow Airport Terminal 5, Longford, Hounslow TW6 2GA, UK").
addressLine1 string Street number and street name (e.g. "15 Baker Street").
addressLine2 string Sub-locality or neighbourhood. May be empty.
town string Town or city.
county string County, state, or region.
postCode string Postal or ZIP code.
country string Country display name (e.g. "United Kingdom").
countryCode string (ISO 3166-1 alpha-2) Two-letter country code (e.g. "GB", "US").
latitude number Decimal degrees latitude.
longitude number Decimal degrees longitude.
💡
Use the Google Places API to resolve a searched address into the full Address object structure. The premiseName field should hold place.formatted_address, and latitude/longitude come from place.geometry.location.
Request — airport pickup with flight number 
curl -X POST https://api.moovlogic.com/api/v1/bookings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serviceTypeId":     "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "pickupDateTimeUtc": "2026-05-01T14:00:00Z",
    "pickupAddress": {
      "premiseName":   "Heathrow Airport Terminal 5, Longford, Hounslow TW6 2GA, UK",
      "addressLine1":  "Heathrow Airport Terminal 5",
      "town":          "Hounslow",
      "postCode":      "TW6 2GA",
      "country":       "United Kingdom",
      "countryCode":   "GB",
      "latitude":      51.4775,
      "longitude":    -0.4614
    },
    "dropoffAddress": {
      "premiseName":   "10 Downing Street, Westminster, London SW1A 2AA, UK",
      "addressLine1":  "10 Downing Street",
      "town":          "London",
      "postCode":      "SW1A 2AA",
      "country":       "United Kingdom",
      "countryCode":   "GB",
      "latitude":      51.5034,
      "longitude":    -0.1276
    },
    "passengerName":     "Jane Smith",
    "passengerEmail":    "jane@example.com",
    "passengerPhone":    "+447911123456",
    "quotedFare":        85.00,
    "currency":          "GBP",
    "passengers":        1,
    "flightNumber":      "BA286",
    "notes":             "Meet in arrivals, holding name sign",
    "externalReference": "HOTEL-2026-04821"
  }'
import requests

booking = {
    'serviceTypeId':     '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    'pickupDateTimeUtc': '2026-05-01T14:00:00Z',
    'pickupAddress': {
        'premiseName':  'Heathrow Airport Terminal 5, Longford, Hounslow TW6 2GA, UK',
        'addressLine1': 'Heathrow Airport Terminal 5',
        'town':         'Hounslow',
        'postCode':     'TW6 2GA',
        'country':      'United Kingdom',
        'countryCode':  'GB',
        'latitude':      51.4775,
        'longitude':    -0.4614
    },
    'dropoffAddress': {
        'premiseName':  '10 Downing Street, Westminster, London SW1A 2AA, UK',
        'addressLine1': '10 Downing Street',
        'town':         'London',
        'postCode':     'SW1A 2AA',
        'country':      'United Kingdom',
        'countryCode':  'GB',
        'latitude':      51.5034,
        'longitude':    -0.1276
    },
    'passengerName':     'Jane Smith',
    'passengerEmail':    'jane@example.com',
    'passengerPhone':    '+447911123456',
    'quotedFare':        85.00,
    'currency':          'GBP',
    'passengers':        1,
    'flightNumber':      'BA286',
    'externalReference': 'HOTEL-2026-04821'
}

response = requests.post(
    'https://api.moovlogic.com/api/v1/bookings',
    json=booking,
    headers={'Authorization': f'Bearer {token}'}
)
tag_name = response.json()['tagName']
print(f"Booking created: {tag_name}")
<?php
$booking = [
    'serviceTypeId'     => '3fa85f64-5717-4562-b3fc-2c963f66afa6',
    'pickupDateTimeUtc' => '2026-05-01T14:00:00Z',
    'pickupAddress'     => [
        'premiseName'  => 'Heathrow Airport Terminal 5, Longford, Hounslow TW6 2GA, UK',
        'addressLine1' => 'Heathrow Airport Terminal 5',
        'town'         => 'Hounslow',
        'postCode'     => 'TW6 2GA',
        'country'      => 'United Kingdom',
        'countryCode'  => 'GB',
        'latitude'     => 51.4775,
        'longitude'    => -0.4614
    ],
    'dropoffAddress' => [
        'premiseName'  => '10 Downing Street, Westminster, London SW1A 2AA, UK',
        'addressLine1' => '10 Downing Street',
        'town'         => 'London',
        'postCode'     => 'SW1A 2AA',
        'country'      => 'United Kingdom',
        'countryCode'  => 'GB',
        'latitude'     => 51.5034,
        'longitude'    => -0.1276
    ],
    'passengerName'     => 'Jane Smith',
    'passengerEmail'    => 'jane@example.com',
    'passengerPhone'    => '+447911123456',
    'quotedFare'        => 85.00,
    'currency'          => 'GBP',
    'passengers'        => 1,
    'flightNumber'      => 'BA286',
    'externalReference' => 'HOTEL-2026-04821'
];

$ch = curl_init('https://api.moovlogic.com/api/v1/bookings');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer $token",
        'Content-Type: application/json'
    ],
    CURLOPT_POSTFIELDS => json_encode($booking)
]);
$data    = json_decode(curl_exec($ch), true);
$tagName = $data['tagName'];
curl_close($ch);
const response = await fetch('https://api.moovlogic.com/api/v1/bookings', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        serviceTypeId:     '3fa85f64-5717-4562-b3fc-2c963f66afa6',
        pickupDateTimeUtc: '2026-05-01T14:00:00Z',
        pickupAddress: {
            premiseName:  'Heathrow Airport Terminal 5, Longford, Hounslow TW6 2GA, UK',
            addressLine1: 'Heathrow Airport Terminal 5',
            town:         'Hounslow',
            postCode:     'TW6 2GA',
            country:      'United Kingdom',
            countryCode:  'GB',
            latitude:      51.4775,
            longitude:    -0.4614
        },
        dropoffAddress: {
            premiseName:  '10 Downing Street, Westminster, London SW1A 2AA, UK',
            addressLine1: '10 Downing Street',
            town:         'London',
            postCode:     'SW1A 2AA',
            country:      'United Kingdom',
            countryCode:  'GB',
            latitude:      51.5034,
            longitude:    -0.1276
        },
        passengerName:     'Jane Smith',
        passengerEmail:    'jane@example.com',
        passengerPhone:    '+447911123456',
        quotedFare:        85.00,
        currency:          'GBP',
        passengers:        1,
        flightNumber:      'BA286',
        externalReference: 'HOTEL-2026-04821'
    })
});

if (!response.ok) throw new Error(`Booking failed: ${response.status}`);
const { tagName } = await response.json();
console.log(`Booking created: ${tagName}`);

Response — 201 Created

Response 201 Created 
{
  "tagName":           "MV-20260501-4821",
  "bookingId":         "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "status":            "Pending",
  "quotedFare":        85.00,
  "currency":          "GBP",
  "pickupDateTimeUtc": "2026-05-01T14:00:00Z",
  "externalReference": "HOTEL-2026-04821",
  "createdAt":         "2026-04-19T10:23:00Z"
}

The booking reference (tagName)

The tagName is your booking reference — store it immediately. Use it for all subsequent operations:

  • GET /api/v1/bookings/{tagName} — retrieve booking details
  • PUT /api/v1/bookings/{tagName} — update booking
  • DELETE /api/v1/bookings/{tagName} — cancel booking
  • POST /api/v1/bookings/{tagName}/status — update ride status
⚠️
Store tagName immediately after creating a booking. If you lose it, retrieve it via GET /api/v1/bookings filtered by externalReference — which is why providing your own externalReference is strongly recommended.

Airport bookings

If the pickup location is an airport, always include flightNumber. This enables automatic flight monitoring — if the flight is delayed, the dispatch system adjusts the pickup time automatically and notifies the assigned driver.

Next steps

Manage Bookings
Retrieve, update, and cancel bookings using the tagName.
Status Updates
Push real-time ride status changes to the dispatch screen.
Errors
Understand booking creation error codes.