Booking Services API

Integrate tractor discovery and booking creation via the Hello Tractor booking-services API.

Overview

• Path prefix: /booking-services/
• All requests and responses are JSON (Content-Type: application/json).

Authentication

Send your portal-created Api-Key on every request:

Authorization: Api-Key <your-key>

Keys are scoped per endpoint. A valid key without scope for the endpoint returns 401. Create keys in the partner dashboard — the plain key is shown once; store it securely.

Find tractors

Available Available now

Nearby tractors

GET /booking-services/tractor/nearby/{lat}/{lng}/

Returns tractors near a coordinate. Rate limit: ~60 requests/minute.

Response fields include _id, TractorID, PositionLatitude, PositionLongitude, minsAway, distance.

Tractor details

GET /booking-services/tractor/{tractorId1,tractorId2,...}/detail/

Comma-separated tractor IDs. Rate limit: ~60 requests/minute.

Create booking

Available Available now

POST /booking-services/booking-agent/service-booking/

Response: { "bookingID": <int>, "clusterID": <int> }

Keep the bookingID — it is your handle to the booking.

Rate limit: ~50 requests/minute.

curl -X POST "$API_BASE/booking-services/booking-agent/service-booking/" \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tractorId": 99,
    "serviceType": 1,
    "serviceDate": "2026-07-20",
    "landArea": 2.5,
    "areaType": "ha",
    "farmerName": "Adaobi",
    "farmerPhone": "+2348000000000",
    "gender": 1,
    "latitude": 9.08,
    "longitude": 7.49,
    "farmLocation": "Kaduna",
    "crop": "maize"
  }'

Set $API_BASE and $API_KEY from your partner dashboard.

Booking status

Available Available now

Requires scope booking:bookings:read. Your key can only read bookings created under your organization.

Poll by ID

GET /booking-services/partner/booking/{booking_id}

Returns current status and booking details. Unknown booking or cross-org access returns 404.

curl "$API_BASE/booking-services/partner/booking/12345" \
  -H "Authorization: Api-Key $API_KEY"

Example response fields: bookingID, bookingStatus (integer code — see status table below), tractorPairedTo, serviceDate, hectaresServiced, farmerName, farmerPhone, createdAt, updatedAt.

Map bookingStatus to the label using the status table below.

List bookings

GET /booking-services/partner/booking/{page}/{count}

Paginated list of your organization's bookings.

curl "$API_BASE/booking-services/partner/booking/1/20" \
  -H "Authorization: Api-Key $API_KEY"

Status values

Errors & limits