Create Bills Package

Endpoint

POST /api/external/createBillsPackage.php

Description

This endpoint externally creates a tenant and associates them with a house contract. It checks if the user’s email is already registered with Housr and creates an account for them if not. Finally, it stores the contract and tenant details along with the user’s ID in the huddle_contracts table.

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": "Jane",
  "lastName": "Doe",
  "birthday": "1995-04-21",
  "email": "jane.doe@example.com",
  "contactNo": "+441234567890",
  "address": "123 High Street, Manchester, M4 5AB",
  "broadband": "400mbps",
  "numberOfTenants": 4,
  "startDate": "2024-09-01",
  "endDate": "2025-08-31",
  "selectedServices": {
    "gas": "true",
    "electricity": "true",
    "water": "true",
    "tv": "true",
    "wifi": "true"
  }
}

Request Parameters

Parameter	Type	Required	Description
`firstName`	string	✅ Yes	First name of the tenant.
`lastName`	string	✅ Yes	Last name of the tenant.
`birthday`	string	✅ Yes	Date of birth of the tenant (`YYYY-MM-DD`).
`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.
`address`	string	✅ Yes	Address of the rental property.
`broadband`	string	✅ Yes	Type of broadband connection (`Fibre`, `ADSL`, etc.).
`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`).
`selectedServices`	object	✅ Yes	JSON object specifying selected services.

Response Format

Success Response

Status Code: 200 OK
Example Response:


{
  "status": "success",
  "data": {
    "houseContractId": 2022051,
    "tenantId": 1000057,
    "message": "New Housr user created. Password is their initials plus date of birth (e.g. JS15012004)."
  }
}

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)"
}

Tenant Already Exists

Status Code: 400 Bad Request
Response:


{
  "status": "error",
  "message": "Tenant email already associated with a contract"
}

Possible Address Error (using Loqate to find possible similar addresses)

Status Code: 400 Bad Request
Response:


{
  "status": "error",
  "error": "Address not found. Please select from possible addresses.",
  "possibleAddresses": [
    {
      "addressId": "GB|RM|B|2066825",
      "address": "61 Bury Old Road Ainsworth, Bolton, BL2 5SD"
    },
    {
      "addressId": "GB|RM|B|14565601",
      "address": "61 Bury Old Road Prestwich, Manchester, M25 0FG"
    }
  ]
}

Database Error

Status Code: 500 Internal Server Error
Response:


{
  "status": "error",
  "message": "Failed to store external Huddle contract"
}

Logic Overview

Validates API Key using X-API-Key header.
Validates request fields (required fields, correct formats).
Creates a house contract using the createExternalHouse utility function.
Handles API response errors.
Checks if the address is valid and returns possible alternatives if necessary.
Creates a tenant using the createTenant utility function.
Stores contract and tenant information in the database.
Sends a confirmation email to the tenant.

Example Usage (cURL)


curl -X POST https://your-api.com/api/external/createExternalTenant.php \
     -H "Content-Type: application/json" \
     -H "X-API-Key: your_api_key" \
     -d '{
       "firstName": "Jane",
       "lastName": "Doe",
       "birthday": "2004-01-21",
       "email": "jane.doe@example.com",
       "contactNo": "+44 1234567890",
       "address": "123 High Street, Manchester, M4 5AB",
       "broadband": "400mbps",
       "numberOfTenants": 4,
       "startDate": "2024-09-01",
       "endDate": "2025-08-31",
       "selectedServices": {
         "gas": "true",
         "electricity": "true",
         "water": "true",
         "tv": "true",
         "wifi": "true"
       }
     }'

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 an error if the tenant already exists with the same contract.
If the provided address is invalid, the API will suggest alternative addresses.