Tenant API Service

Integration documentation and guide for the eCabs Tenant API.

Welcome to the Tenant API Service documentation. This guide provides an overview of all available API endpoints and instructions to help you integrate and interact with the Tenant API efficiently.

🔑 Account Setup

To obtain access credentials and begin your integration, please send an email to help@ecabstech.com requesting an API key.

Configuration & Authentication

Base URL: {{baseUrl}}/api/v1

All endpoints require authentication via the X-Api-Key header:

X-Api-Key: {{api-key}}

Note: IP limited access may apply.

1. Pricing Zone Operations (Optional)

POST Create Pricing Zone

Creates a new pricing zone with geographical boundaries (name, radius, coordinate points).

curl -X POST "{{baseUrl}}/api/v1/pricing-zones" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "name": "Test Zone",
    "radius": 20,
    "points": [
      {"lat": 35.850035911668925, "lng": 14.494603872299194}
    ]
  }'

GET Get All Pricing Zones

Retrieves all pricing zones in the system.

curl -X GET "{{baseUrl}}/api/v1/pricing-zones" \
  -H "X-Api-Key: {{api-key}}"

GET Get Pricing Zone by ID

Retrieves a specific pricing zone by its ID, including all coordinate points.

curl -X GET "{{baseUrl}}/api/v1/pricing-zones/123" \
  -H "X-Api-Key: {{api-key}}"

PUT Update Pricing Zone

Updates an existing pricing zone (name, radius, points, etc.).

curl -X PUT "{{baseUrl}}/api/v1/pricing-zones/123" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "name": "Updated Test Pricing Zone",
    "radius": 1500,
    "points": [
      {"lat": 35.9000, "lng": 14.5150, "address": "Updated Valletta, Malta"},
      {"lat": 35.9050, "lng": 14.5200, "address": "Updated Sliema, Malta"}
    ]
  }'

DELETE Delete Pricing Zone

Permanently deletes a pricing zone by its ID.

curl -X DELETE "{{baseUrl}}/api/v1/pricing-zones/123" \
  -H "X-Api-Key: {{api-key}}"

2. Pricing Rule Operations (Optional)

POST Create Pricing Rule

Creates a pricing rule with booking criteria, payment types, vehicle types, date/time constraints, and settings (quota, surge map, etc.).

curl -X POST "{{baseUrl}}/api/v1/pricing-rules" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "name": "Test Pricing Rule",
    "description": "Example description",
    "status": "DRAFT",
    "type": "GENERAL",
    "quota": {
      "type": "COMMON",
      "value": 40.0,
      "unit": "FIXED"
    },
    "criteria": {
      "booking": {
        "sources": ["WEB"],
        "types": ["ASAP"]
      },
      "payment": {
        "paymentTypes": ["CASH"]
      },
      "vehicle": {
        "types": ["cab"]
      },
      "dateRange": {
        "dateFrom": "2025-11-05",
        "dateTo": "2025-11-06",
        "daysOfWeek": ["FRIDAY"],
        "isExtendedWeekend": false,
        "timeFrom": "00:30",
        "timeTo": "00:40"
      },
      "zonesIds": [1],
      "pointsIds": [2]
    },
    "settings": {
      "waitingTime": {
        "waitTimeGracePeriod": 2
      },
      "pricePerMinute": {
        "isFinalPriceRecalculationEnabled": false
      },
      "surgeMap": {
        "showRule": true,
        "showRuleValue": true
      }
    }
  }'

GET Get All Pricing Rules

Retrieves all pricing rules with their criteria and settings.

curl -X GET "{{baseUrl}}/api/v1/pricing-rules" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{}'

GET Get Pricing Rule by ID

Retrieves a specific pricing rule by its ID.

curl -X GET "{{baseUrl}}/api/v1/pricing-rules/123" \
  -H "X-Api-Key: {{api-key}}"

PUT Update Pricing Rule

Updates an existing pricing rule (quota, criteria, date ranges, etc.).

curl -X PUT "{{baseUrl}}/api/v1/pricing-rules/123" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "name": "Updated Pricing Rule",
    "description": "Updated test pricing rule",
    "status": "DRAFT",
    "type": "GENERAL",
    "quota": {
      "type": "COMMON",
      "value": 7.5,
      "unit": "PERCENT"
    },
    "criteria": {
      "booking": {
        "sources": ["WEB"],
        "types": ["ASAP"]
      },
      "payment": {
        "paymentTypes": ["CASH"]
      },
      "vehicle": {
        "types": ["cab"]
      },
      "dateRange": {
        "dateFrom": "2025-11-05",
        "dateTo": "2025-11-06",
        "daysOfWeek": ["FRIDAY"],
        "isExtendedWeekend": false,
        "timeFrom": "00:30",
        "timeTo": "00:40"
      },
      "zonesIds": [1, 2],
      "pointsIds": [1, 2]
    }
  }'

DELETE Delete Pricing Rule

Permanently deletes a pricing rule by its ID.

curl -X DELETE "{{baseUrl}}/api/v1/pricing-rules/123" \
  -H "X-Api-Key: {{api-key}}"

3. Customer Service Operations

POST Create Customer

Creates a new customer with personal information.

curl -X POST "{{baseUrl}}/api/v1/customers" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "firstName": "Bruce",
    "lastName": "Wayne",
    "email": "bruce.wayne@waynenterprice.com",
    "mobilePhone": "+35612345678",
    "locale": "en_US"
  }'

GET Get Customer by ID

Retrieves a specific customer by their UUID.

curl -X GET "{{baseUrl}}/api/v1/customers/123e4567-e89b-12d3-a456-426614174000" \
  -H "X-Api-Key: {{api-key}}"

GET Get All Customers

Retrieves all customers, with optional mobile phone filtering.

curl -X GET "{{baseUrl}}/api/v1/customers" \
  -H "X-Api-Key: {{api-key}}"

GET Get Customers with Pagination

Retrieves customers with specific page and size parameters.

curl -X GET "{{baseUrl}}/api/v1/customers?page=0&size=10" \
  -H "X-Api-Key: {{api-key}}"

GET Search Customers by Mobile Phone

Searches for customers using their mobile phone number.

curl -X GET "{{baseUrl}}/api/v1/customers?mobilePhone=%2B35612345678" \
  -H "X-Api-Key: {{api-key}}"

4. Vehicle Type Operations

GET Get All Vehicle Types

Retrieves all available vehicle types with capacity, icons, and pricing information.

curl -X GET "{{baseUrl}}/api/v1/vehicle-types" \
  -H "X-Api-Key: {{api-key}}"

GET Get Vehicle Types with Pagination

Lists vehicle types with pagination control for better data management.

curl -X GET "{{baseUrl}}/api/v1/vehicle-types?page=0&size=10" \
  -H "X-Api-Key: {{api-key}}"

5. Vehicle Location Operations

GET Get All Vehicle Locations

Retrieves all vehicle locations with filtering by status (IDLE, JOB_AWAITING, ACCEPTED, PICKED_UP, SHIFT_ENDED) and pagination.

curl -X GET "{{baseUrl}}/api/v1/vehicle-locations?status=IDLE&page=0&size=25" \
  -H "X-Api-Key: {{api-key}}"

GET Get Vehicle Location by Number Plate

Retrieves detailed location information for a specific vehicle by its number plate.

curl -X GET "{{baseUrl}}/api/v1/vehicle-locations/ABC123" \
  -H "X-Api-Key: {{api-key}}"

6. Waiting Time Operations

GET Get Waiting Times

Gets waiting time estimates based on latitude and longitude coordinates.

curl -X GET "{{baseUrl}}/api/v1/waiting-times?lat=35.8997&lng=14.5146" \
  -H "X-Api-Key: {{api-key}}"

7. Quotation Operations

POST Create Quotation

Creates a new quotation for trip pricing estimation.

curl -X POST "{{baseUrl}}/api/v1/quotations" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "customerId": "123e4567-e89b-12d3-a456-426614174000",
    "bookingChannel": "MOBILE_APP",
    "paymentType": "ON_ACCOUNT",
    "pickUpTime": "2024-01-01T10:00:00Z",
    "tripWaypoints": [
      {
        "lat": 35.8519165,
        "lng": 14.4863253,
        "address": "Malta International Airport, Malta"
      },
      {
        "lat": 35.922935,
        "lng": 14.486780,
        "address": "eCabs, St. Julian, Malta"
      }
    ]
  }'

GET Get Quotation by ID

Retrieves a specific quotation by its ID, including pricing for different vehicle types.

curl -X GET "{{baseUrl}}/api/v1/quotations/123" \
  -H "X-Api-Key: {{api-key}}"

8. Booking Operations

POST Create Booking

Creates a new booking with customer information, waypoints, vehicle type, passenger details, pricing, and payment information.

curl -X POST "{{baseUrl}}/api/v1/bookings" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "customerId": "123e4567-e89b-12d3-a456-426614174000",
    "b2bAccount": null,
    "pickupTime": "2024-01-01T10:00:00Z",
    "asap": false,
    "quotationId": 123,
    "bookingChannel": "CALL",
    "vehicleType": {
      "code": "van"
    },
    "tripWaypoints": [
      {
        "orderNumber": 1,
        "location": {
          "lat": 35.8997,
          "lng": 14.5146,
          "address": "Valletta, Malta"
        },
        "type": "PICKUP",
        "passengers": null,
        "lastStop": false
      },
      {
        "orderNumber": 2,
        "location": {
          "lat": 35.9042,
          "lng": 14.5189,
          "address": "Sliema, Malta"
        },
        "type": "DROPOFF",
        "passengers": null,
        "lastStop": true
      }
    ],
    "passenger": {
      "firstName": "John",
      "lastName": "Doe",
      "contactNumber": "+35612345678"
    },
    "price": {
      "manualPrice": {
        "amount": {
          "value": 20.00,
          "currency": "EUR"
        },
        "reason": "Special rate"
      },
      "quotationPrice": null,
      "priceRange": null,
      "bookingFee": {
        "value": 1.00,
        "currency": "EUR"
      },
      "waitingTimeFee": null
    },
    "payment": {
      "paymentType": "CASH",
      "channel": "IN_VEHICLE",
      "status": "NOT_SETTLED"
    }
  }'

GET Get Booking by ID

Retrieves a specific booking by its ID.

curl -X GET "{{baseUrl}}/api/v1/bookings/123" \
  -H "X-Api-Key: {{api-key}}"

GET Get All Bookings

Retrieves all bookings with pagination and filtering capabilities.

curl -X GET "{{baseUrl}}/api/v1/bookings" \
  -H "X-Api-Key: {{api-key}}"

PUT Update Booking Status

Updates booking status using BookingStatusEnum values (e.g. RESERVED, DISPATCHED, ACCEPTED, CAB_ARRIVED_AT_PICKUP, TRIP_STARTED, CANCELLED, etc.).

curl -X PUT "{{baseUrl}}/api/v1/bookings/123" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: {{api-key}}" \
  -d '{
    "status": "CANCELLED"
  }'

HTTP Status Codes & Errors

200 OK: Successful GET requests
201 Created: Successful POST requests (resource creation)
204 No Content: Successful PUT/DELETE requests
400 Bad Request: Invalid request data or validation errors
401 Unauthorized: Missing or invalid API key
403 Forbidden: Insufficient permissions (wrong role)
404 Not Found: Resource not found
409 Conflict: Resource already exists (e.g. duplicate API key)
500 Internal Server Error: Server-side errors

Error Response Format

{
  "error": "Error description",
  "message": "Detailed error message",
  "timestamp": "2024-01-01T10:00:00Z"
}

Implementation Notes

All endpoints require authentication via X-Api-Key header.
Admin endpoints (/admin/*) require ADMIN role.
Most endpoints support both ADMIN and USER roles.
Pagination parameters: page (0–10000), size (1–100).
Date formats use ISO 8601 standard.
Coordinates use decimal degrees format.
UUIDs are used for customer IDs.
All monetary amounts include currency specification.