Get Quotes

Endpoint

POST /api/external/getQuotes.php

Description

This endpoint retrieves quotes for bills based on a tenant’s postcode, number of tenants, and tenancy duration.

Authentication

Header: X-API-Key: <your-api-key> (Required)
The API key is validated against registered companies.

Request Format

Content-Type: application/json
Method: POST

Request Body


{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "contactNo": "+441234567890",
  "postcode": "M45 6TL",
  "numberOfTenants": 3,
  "startDate": "2024-09-01",
  "endDate": "2025-08-31"
}

Request Parameters

Parameter	Type	Required	Description
`firstName`	string	✅ Yes	First name of the tenant.
`lastName`	string	✅ Yes	Last name of the tenant.
`email`	string	✅ Yes	Email address of the tenant. Must be valid.
`contactNo`	string	✅ Yes	Contact number of the tenant. Must be a valid phone number.
`postcode`	string	✅ Yes	Postcode of the property where the quote is needed.
`numberOfTenants`	int	✅ Yes	Number of tenants living in the property.
`startDate`	string	✅ Yes	Start date of the tenancy (`YYYY-MM-DD`).
`endDate`	string	✅ Yes	End date of the tenancy (`YYYY-MM-DD`).

Response Format

Success Response

Status Code: 200 OK
Example Response:


{
  "status": "success",
  "data": {
    "quotes": [
      {
        "tariff": 0.095852,
        "estimate": 13999.85,
        "planType": "GREENSAVER",
        "utilityType": "gas",
        "weeklyQuote": 8.25,
        "standingCharge": 0.799505
      },
      {
        "planType": "LITE",
        "utilityType": "gas",
        "weeklyQuote": 0
      },
      {
        "tariff": 0,
        "estimate": 13999.85,
        "planType": "UNLIMITED",
        "utilityType": "gas",
        "weeklyQuote": 10.51,
        "standingCharge": 5.705238
      },
      {
        "tariff": 0.342849,
        "estimate": 3200,
        "planType": "GREENSAVER",
        "utilityType": "electric",
        "weeklyQuote": 7.2,
        "standingCharge": 0.8995,
        "electricOnlyEstimate": 7040,
        "weeklyQuoteElectricOnly": 13.84
      },
      {
        "planType": "LITE",
        "utilityType": "electric",
        "weeklyQuote": 0,
        "weeklyQuoteElectricOnly": 0
      },
      {
        "tariff": 0,
        "estimate": 6400,
        "planType": "UNLIMITED",
        "utilityType": "electric",
        "weeklyQuote": 8.53,
        "standingCharge": 4.628571,
        "electricOnlyEstimate": 14080,
        "weeklyQuoteElectricOnly": 8.53
      },
      {
        "utilityType": "water",
        "weeklyQuote": 3.56
      },
      {
        "utilityType": "tv",
        "weeklyQuote": 0.81
      },
      {
        "utilityType": "broadband",
        "weeklyQuote": 0,
        "broadbandSpeed": "400Mbps"
      },
      {
        "utilityType": "broadband",
        "weeklyQuote": 0,
        "broadbandSpeed": "600Mbps"
      },
      {
        "utilityType": "broadband",
        "weeklyQuote": 0,
        "broadbandSpeed": "800Mbps"
      }
    ]
  }
}

Error Responses

Missing API Key

Status Code: 401 Unauthorized
Response:


{
  "status": "error",
  "message": "Missing API key"
}

Invalid API Key

Status Code: 401 Unauthorized
Response:


{
  "status": "error",
  "message": "Invalid API key"
}

Missing Required Fields

Status Code: 400 Bad Request
Response:


{
  "status": "error",
  "message": "Tenant email is required"
}

Invalid Data Format

Status Code: 400 Bad Request
Example Error (Invalid Email)


{
  "status": "error",
  "message": "Invalid email format"
}

Invalid Date Format

Status Code: 400 Bad Request
Response:


{
  "status": "error",
  "message": "Invalid date format (YYYY-MM-DD)"
}

Database Error

Status Code: 500 Internal Server Error
Response:


{
  "status": "error",
  "message": "Failed to add user to database"
}

Logic Overview

Validates API Key using X-API-Key header.
Validates request fields (required fields, correct formats).
Retrieves quotes using the getQuotes utility function.
Handles API response errors.
Checks if tenant exists in the database:
- If not, inserts the tenant details.
Returns quote details.

Example Usage (cURL)


curl -X POST https://your-api.com/api/get-quotes.php \
     -H "Content-Type: application/json" \
     -H "X-API-Key: your_api_key" \
     -d '{
       "firstName": "John",
       "lastName": "Doe",
       "email": "john.doe@example.com",
       "contactNo": "+441234567890",
       "postcode": "M45 6TL",
       "numberOfTenants": 3,
       "startDate": "2024-09-01",
       "endDate": "2025-08-31"
     }'

Notes

Ensure API keys are valid before making requests.
Ensure date format is YYYY-MM-DD.
Ensure valid email & phone number formats.
The API may return suggested addresses if the postcode is incorrect.