Introduction
Welcome to the Homebox Partner API! This is a simple RESTful API that can be used to access our bill packages and create orders. The purpose of this API is to provide a means for you to integrate Homebox into your service.
We provide two separate environments for you to use. One for production and a sandbox environment for testing purposes:
Production: https://accounts.billingbetter.co.uk
Sandbox: https://sandbox.billingbetter.co.uk
You can view code examples in the dark area to the right.
Authentication
To authorize, you can just pass the correct header with each request:
curl "https://sandbox.billingbetter.co.uk/api/path/to/endpoint"
-H "Authorization: Bearer YOUR_TOKEN_HERE"
Make sure to replace
YOUR_TOKEN_HEREwith your API key.
The Homebox Partner API uses tokens to authorize requests.
If you do not have an account, and you are interested in becoming a partner, please contact us at info@homebox.co.uk for a sandbox API token.
Our API expects all requests to include a valid token in the header:
Authorization: Bearer YOUR_TOKEN_HERE
Endpoints
Properties
Find an Address
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/address/find/BN11AB'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"data": [
{
"address": "35 Ship Street, Brighton, BN1 1AB",
"address_id": "UN5Iu2KV9zOVJbacTYozt"
},
{
"address": "36 Ship Street, Brighton, BN1 1AB",
"address_id": "kFkwDze86qhQDpWc8v7Cd"
},
{
"address": "37 Ship Street, Brighton, BN1 1AB",
"address_id": "o8dsMjMQAb2qOvVGfB66a"
}
]
}
This endpoint will return a list of addresses for a given query. The address_id can be used in other API requests.
HTTP Request
GET /api/partner/address/find/{query}
Create a Property
You must send the property details in JSON within the body of the request. Here is an example:
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/property'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "address": { "address_id" : "VglSD9KF3EKcNz_RRXPVV" }}'
{
"address" : {
"address_id" : "VglSD9KF3EKcNz_RRXPVV"
}
}
Although it's preferred that you send the address_id, you can also send the full address of the property. Here is an example:
{
"address": {
"line1": "123 Test Lane",
"line2": "",
"city": "London",
"county": "Greater London",
"postcode": "EC1V2NX"
}
}
The above command returns JSON structured like this:
{
"data": {
"id": 1,
"address_line1": "123 Test Lane",
"address_line2": null,
"address_line3": null,
"address_line4": null,
"address_city": "London",
"address_county": "Greater London",
"address_postcode": "EC1V2NX",
"status_id": 1,
"status": "New Tenancy",
"created_at": "2022-01-06T10:27:12.000000Z",
"updated_at": "2022-01-06T10:27:12.000000Z",
"external_id": null,
"retrieved_at": null,
"mpan": null,
"mprn": null,
"uprn": null
}
}
This endpoint is used to add a property to your portfolio.
HTTP Request
POST /api/partner/property
Body Data
The property details must be provided in JSON in the body of the request (see example on the right).
| Parameter | Description |
|---|---|
| address | A JSON object containing either the address_id (which you can get from the Find an Address endpoint), or the complete address of the property (line1, line2, city, county and postcode). |
| property_reference | The reference of the property in your system. This value is optional and will be null by default. |
List Properties
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/property?filter=eyAic3RhdHVzIjogWzJdIH0=&q=London'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"data": {
"id": 1,
"address_line1": "123 Test Lane",
"address_line2": null,
"address_line3": null,
"address_line4": null,
"address_city": "London",
"address_county": "Greater London",
"address_postcode": "...",
"status_id": 2,
"status": "Tenant Package",
"created_at": "2021-12-20T00:00:00.000000Z",
"updated_at": "2021-12-20T00:00:00.000000Z",
"external_id": "3kgdu-I5NgnObELdIq2AK",
"retrieved_at": "2022-11-22T11:20:00.000000Z",
"mpan": null,
"mprn": null,
"uprn": null,
"partner_properties": [
{
"id": 1,
"partner": {
"id": 1,
"name": "Partner Account",
"name_url": "...",
"reference_number": "PARTNER1",
"image_path": "...",
"theme_color_primary": "#40BF67",
"status": "active",
"type": 0,
"type_name": "reseller",
"management_fee": "0",
"commission_allowed": true,
"reseller": {
"name": "Partner Account",
"logo": "..."
}
},
"property_reference": null
}
]
}
}
This endpoint lists all the properties that are associated with your partner account. It is also paginated and, by default, the page will be set to 1 if no page is specified.
You can apply filters, as shown in the parameters bellow.
Example: /api/partner/property?filter=eyAic3RhdHVzIjogWzJdIH0=&q=London
This would retrieve all the properties in London that have a status_id of 2.
Here are the possible property statuses:
| ID | Status | Description |
|---|---|---|
| 1 | Pending | A lead has been trigger for this property but a tenancy has not been created yet |
| 2 | Tenant Package | This property currently has an active bills package with Homebox |
| 3 | Tenants Organising | An external party is responsible for the bills for this tenancy |
| 4 | Void Period | An external party is responsible for the bills for this tenancy |
| 5 | Unknown | The current status of this property is not known |
| 6 | Partner Package | This property currently has an active partner-responsible bills package with Homebox |
HTTP Request
GET /api/partner/property
URL Parameters
| Parameter | Description |
|---|---|
| filter | Base64 Encoded JSON Object of Filters (e.g. { "status": [2] } ) |
| q | Keywords for address |
| page | Page of results |
List Property
This endpoint returns an individual property.
HTTP Request
GET /api/partner/property/{property_id}
Bills Packages
Bills packages are a way to pay for all the household bills related to a property in one payment per month.
We have 2 types of bills packages available:
- Tenant Packages: The resident(s) living in the property can split the monthly payments between them.
- Partner Packages: A business is responsible for paying the utility bills in the property.
Below are a list of endpoints which are general to bills packages.
For specific endpoints related to Tenant Packages and Partner Packages, please go to the relevant section.
List Bills Packages
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/order'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"partner_id": 1,
"package_id": 2,
"from_lead_id": 1,
"package": "Bronze",
"household": {
"id": 1,
"bill_payers": 1,
"housemates": 1,
"status": "Active",
"status_id": 4,
"tenancy_start": "2024-05-20T00:00:00.000000Z",
"tenancy_end": "2050-12-31T00:00:00.000000Z",
"responsibility": "Tenant Package",
"move_in_date": "2024-05-20T00:00:00.000000Z",
"address": {
"address_line1": "123 Test Lane",
"address_line2": null,
"address_city": "London",
"address_county": "Greater London",
"address_postcode": "EC1V2NX"
}
},
"add_ons": [ 35 ],
"negotiator": "John Doe",
"reference": "HOMEBOX1",
"origin": "API",
"created_at": "2024-05-20T09:26:30.000000Z"
}
],
"meta": {
"order_count": 1
}
}
This endpoint can be used to retrieve all the orders you’ve created. You can also retrieve a specific order by specifying the ID .e.g /api/partner/order/1.
HTTP Request
GET /api/partner/order
URL Parameters
| Parameter | Description |
|---|---|
| page | Page of results |
List Bills
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/bill'
-H 'Accept: application/json'
This endpoint returns a list of all chosen bills within a single order.
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"name": "Standard Plan",
"title": "Renewable Energy",
"provider": "truEnergy",
"logo_path": ...,
"date_setup": null,
"state": "No status",
"price_per_housemate": "80.00",
"installation_date": null
},
{
"id": 2,
"name": "Standard Plan",
"title": "TV Licence",
"provider": "TV Licensing",
"logo_path": null,
"date_setup": "2023-02-02",
"state": "Install Date Booked",
"price_per_housemate": "15.00",
"installation_date": "2023-02-02"
},
...
],
"service_charge": "6.50",
"service_charge_per_housemate": "6.50",
"total_price": "101.5",
"total_per_bill_payer": "101.5",
"next_payment_date": "2023-04-02"
}
HTTP Request
GET /api/partner/order/{order_id}/bill
List Payments
curl --location --request GET 'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/payments' \
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"amount": "165.00",
"status": "success",
"payment_method": "bank-transfer",
"status_id": 2,
"attempt": 1,
"previous_attempt_id": null,
"next_attempt_id": null,
"user": {
"email": "john.doe@example.test",
"first_name": "John",
"last_name": "Doe"
},
"paid_at": "2021-06-20 14:00:00",
"created_at": "2021-06-20 13:57:22"
},
{
"id": 2,
"amount": "290.00",
"status": "success",
"status_id": 2,
"payment_method": "bank-transfer",
"attempt": 1,
"previous_attempt_id": null,
"next_attempt_id": null,
"user": {
"email": "jane.doe@example.test",
"first_name": "Jane",
"last_name": "Doe"
},
"paid_at": "2021-06-20 14:00:00",
"created_at": "2021-06-20 13:57:22"
}
]
}
This endpoint returns a list of the payments that have been attempted to be taken from customers for a specific order.
HTTP Request
GET /api/partner/order/{order_id}/payments
Replace Payment
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/payments/{payment_id}/replace'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "payment_method": "bank-transfer" }'
The above command returns JSON structured like this:
{
"data": {
"id": 2,
"amount": "290.00",
"status": "pending",
"status_id": 1,
"payment_method": "bank-transfer",
"attempt": 1,
"previous_attempt_id": 1,
"next_attempt_id": null,
"user": {
"email": "john.doe@example.test",
"first_name": "John",
"last_name": "Doe"
},
"paid_at": null,
"created_at": "2021-06-20 13:57:22"
}
}
This endpoint will cancel the payment and generate a new one with the desired payment method.
HTTP Request
POST /api/partner/order/{order_id}/payments/{payment_id}/replace
Body Data
The payment_method must be provided in JSON in the body of the request (see example on the right).
| Parameter | Description |
|---|---|
| payment_method | Types allowed are "direct-debit" or "bank-transfer". |
List Payouts
curl --location --request GET 'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/supplier'
The above command returns JSON structured like this:
{
"data": [
{
"id": 915,
"status": "Pending",
"bill": "Standard Plan",
"provider": "Southern Water",
"group": "Water",
"created_at": "2021-06-20T16:08:51.000000Z",
"paid_at": null
},
{
"id": 916,
"status": "Success",
"bill": "Standard Plan",
"provider": "Lewes District Council",
"group": "Council Tax",
"created_at": "2021-06-20T16:08:51.000000Z",
"paid_at": "2021-06-20T16:08:51.000000Z"
}
]
}
This endpoint will return all the outgoing supplier payments for a specific order.
HTTP Request
GET /api/partner/order/{order_id}/supplier
Get Property Details
curl --location --request GET 'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/property'
The above command returns JSON structured like this:
{
"data": {
"housemates": 1,
"tenancy_start": "2021-06-01T00:00:00.000000Z",
"tenancy_end": "2021-06-30T00:00:00.000000Z",
"move_in_date": "2021-06-01T00:00:00.000000Z",
"status": {
"id": 10,
"name": "bill-setup",
"text": "Bills Being Setup"
},
"address": {
"line_one": "Oxford Road",
"line_two": null,
"city": "Oxford",
"county": "Oxfordshire",
"postcode": "OX24 2CV"
}
}
}
This endpoint will return all the information about the property, including the address, status, move in dates and the number of housemates.
HTTP Request
GET /api/partner/order/{order_id}/property
Tenant Packages
Tenant packages are a type of bills package where the resident(s) living in the property can split the monthly payments between them.
Get Tenant Package Quote
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/packages?is_student=true&postcode=SW155PU'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"packages": [
{
"id": 1,
"name": "Bronze",
"title": "Essentials",
"description": "Gas, electricity, clean & waste water",
"bills": [
{
"id": 1,
"group_id": 1,
"name": "Renewable Energy",
"provider": "Rebel Energy",
"title": "Renewable Energy",
"description": "Standard Plan",
"description_html": "<h3>Tariffs</h3> ...",
"logo_path": "https://sandbox.billingbetter.co.uk/img/providers/southern_water_logo.png",
"prices": [ ... ]
}
],
"addons": [ ... ]
},
{
"id": 2,
"name": "Silver",
"title": "Essentials + WiFi",
"description": "Gas, electricity, clean & waste water, unlimited Plusnet broadband (speeds up to 18MBPS)",
"bills": [ ... ],
"addons": [ ... ]
},
{
"id": 3,
"name": "Gold",
"title": "Essentials + WiFi & TV",
"description": " Gas, electricity, clean & waste water, unlimited Plusnet broadband (speeds up to 18MBPS), Sky TV (Entertainment Package)",
"bills": [ ... ],
"addons": [ ... ]
}
]
}
This endpoint returns an array of the packages available. Each package contains an array of bills included within that package and each bill contains an array of prices.
HTTP Request
GET /api/partner/packages
Query Parameters
| Parameter | Description |
|---|---|
| postcode | The postcode of the property. This will be used to retrieve their water supplier and council tax provider. |
| is_student | If set to true, the council tax add-on will not be present. False by default. |
| coupon | Coupon code (optional). |
Create Tenant Bills Package
You must send the order details in JSON within the body of the request. Here is an example:
{
"package_id": 2,
"add_ons": [ 35 ],
"address": {
"address_id": "VglSD9KF3EKcNz_RRXPVV"
},
"reference": "HOMEBOX1",
"total_occupants": 5,
"bill_payers": 2,
"household_type": "student",
"tenancy_move_in": "01/10/19",
"tenancy_start": "01/10/19",
"tenancy_end": "01/10/20"
}
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/order'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "package_id": 2, "add_ons": [ 35 ], "address": {"address_id": "VglSD9KF3EKcNz_RRXPVV"}, "reference": "HOMEBOX1", "total_occupants": 5, "bill_payers": 2, "household_type": "student", "tenancy_move_in": "01/10/19", "tenancy_start": "01/10/19", "tenancy_end": "01/10/20"}'
The above command returns JSON structured like this:
{
"data": {
"order_id": 1,
"property_id": 1,
"tenancy_start": "2019-10-01T00:00:00.000000Z",
"tenancy_end": "2020-10-01T00:00:00.000000Z",
"tenancy_type": "Tenant Bills Package",
"tenancy": { ... },
"property": { ... }
"created_at": "2019-09-28T10:59:21.000000Z",
"updated_at": "2019-09-28T10:59:21.000000Z"
},
"meta": {
"links": {
"index": "https://sandbox.billingbetter.co.uk/api/partner/order/",
"show": "https://sandbox.billingbetter.co.uk/api/partner/order/1"
}
}
}
This endpoint is used for sending orders to Homebox. The endpoint returns the integer ID of the saved order. You must use this ID when adding bill payers to the plan with the Add Bill Payer endpoint.
HTTP Request
POST /api/partner/order
Body Data
The details of the order must be provided in JSON in the body of the request (see example on the right).
| Parameter | Description |
|---|---|
| package_id | The numerical ID of the chosen package. The package IDs can be retrieved from the Retrieve Packages endpoint. |
| add_ons | An array of the chosen add-on IDs. This can be excluded if no add-ons were selected. |
| address | A JSON object containing either the address_id (which you can get from the Find an Address endpoint), or the complete address of the property (line1, line2, city, county and postcode). |
| total_occupants | The number of tenants within the property. |
| bill_payers | The number of tenants within the property that will be paying for the bill package. The number of bill_payers must be less than or equal to the number of total_occupants. This parameter is optional and if omitted, the number of bill_payers will default to the number of total_occupants. |
| household_type | This should either student or professional-tenant depending on the property type |
| tenancy_start | The date the tenancy starts. This must be in DD/MM/YY format. |
| tenancy_end | The date the tenancy ends. This must be in DD/MM/YY format. |
| tenancy_move_in | The date the tenants move into their household. This must be in DD/MM/YY format. |
| reference | This field allows you to store a reference against the order which you may use to match the order against its ID in your system. |
| property_reference | The reference of the property in your system. This value is optional and will be null by default. |
| coupon | Coupon code (optional). |
The address parameter can be arranged like below
{
"address" : {
"address_id" : "VglSD9KF3EKcNz_RRXPVV"
}
}
Although it's preferred that you send the address_id, you can also send the full address of the property. Here is an example:
{
"address": {
"line1": "123 Test Lane",
"line2": "",
"city": "London",
"county": "Greater London",
"postcode": "EC1V2NX"
}
}
Invite Bill Payer
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/order/1/invite'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "first_name" : "John", "last_name" : "Appleseed", "phone_number" : "+441234567890" }'
The above command returns JSON structured like this:
{
"data": [
"Tenant was successfully added to order 1"
]
}
This endpoint is used to invite bill payers to an order. Upon success, the tenant will be sent a text message with a unique sign up link. Only bill payers should be added to the order - you must not add tenants who will not be paying for the package. This endpoint should be used after creating an order using the Create Order endpoint.
HTTP Request
POST /api/partner/order/{order_id}/invite
Body Data
The details of the bill-paying tenant must be provided in JSON in the body of the request.
| Parameter | Description |
|---|---|
| first_name | First name of the tenant |
| last_name | Last name of the tenant |
| phone_number | Mobile number of the tenant. This should include the country code e.g. +441234567890 |
List Invites
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/invite'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"first_name": "Jane",
"last_name": "Smith",
"phone_number": "+441234567890",
"total_sent": "1"
}
]
}
This endpoint returns a list of all invited bill payers within a single order. Once a bill payer signs up, they will no longer appear in this list.
HTTP Request
GET /api/partner/order/{order_id}/invite
Delete Invite
curl -X DELETE
'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/invite/{invite_id}'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"message": "Invite has been deleted"
}
This endpoint deletes a bill payer invite.
HTTP Request
DELETE /api/partner/order/{order_id}/invite/{invite_id}
Add Bill Payer
You must send the order details in JSON within the body of the request. Here is an example:
{
"account_name": "Jane Smith",
"account_number": "12345678",
"billing_address": {
"line1": "Flat 1",
"line2": "New Road",
"city": "London",
"county": "Greater London",
"postcode": "NR3 2AG"
},
"birthday": "01/01/2000",
"email": "jane.smith917@example.com",
"first_name": "Jane",
"last_name": "Smith",
"nationality": "GB",
"phone_number": "+441234567890",
"sort_code": "000000"
}
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/order'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "account_name": "Jane Smith", "account_number": "12345678", "birthday": "01/01/2000", "email": "jane.smith917@example.com", "first_name": "Jane", "last_name": "Smith", "nationality": "GB", "phone_number": "+441234567890", "sort_code": "000000", "billing_address": { "line1": "Flat 1", "line2": "New Road", "city": "London", "county": "Greater London", "postcode": "NR3 2AG"} }'
The above command returns JSON structured like this:
{
"data": [
"Tenant was successfully added to order 1"
]
}
This endpoint is used to add a bill payer to a tenant bills package. Unlike the Invite Bill Payers to Tenant Package endpoint, the tenant will not be asked to set up their account via an SMS message. Instead, they will be sent confirmation that the direct debit has been created via email.
This will need to be triggered once for each bill payer in the order (i.e. if the "bill_payers" value in the Create Tenant Bills Package payload is 2, you'll need to add 2 bills payers to the order using this endpoint)
HTTP Request
POST /api/partner/order/{order_id}/tenant
Body Data
The details of the bill-paying tenant must be provided in JSON in the body of the request.
| Parameter | Description |
|---|---|
| first_name | First name of the tenant |
| last_name | Last name of the tenant |
| Email address of the tenant | |
| phone_number | Mobile number of the tenant. This should include the country code e.g. +441234567890 |
| nationality | Nationality of the tenant. This must be a country code in ISO 3166-1 alpha-2 format (e.g. GB) |
| birthday | Tenant's date of birth. This must be in DD/MM/YYYY format |
| account_name | The name on the bank account |
| account_number | Bank account number. |
| sort_code | Bank account sort code |
| billing_address | A JSON object containing the billing address. This should include entries for line1, line2, city, county and postcode. |
List Bill Payers
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/tenant'
-H 'Accept: application/json'
This endpoint returns a list of all bill payers within a single order.
HTTP Request
GET /api/partner/order/{order_id}/tenant
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"first_name": "John",
"last_name": "Appleseed",
"email": "john.appleseed@example.com",
"phone_number": "+441234567890",
"birthday": "15/01/1996",
"nationality": "GB"
},
{
"id": 2,
"first_name": "Jane",
"last_name": "Smith",
"email": "jane.smith917@example.com",
"phone_number": "+441234567891",
"birthday": "15/01/1996",
"nationality": "GB"
}
]
}
Update Bill Payer
You must send the bill payer details in JSON within the body of the request. Here is an example:
{
"first_name": "Jane",
"last_name": "Smith",
"email": "jane.smith917@example.com",
"phone_number": "+441234567890",
"birthday": "01/01/2000",
"nationality": "GB"
}
curl -X PATCH
'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/tenant/{tenant_id}'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "first_name": "Jane", "last_name": "Smith", "email": "jane.smith917@example.com", "phone_number": "+441234567890", "birthday": "01/01/2000", "nationality": "GB" }'
The above command returns JSON structured like this:
{
"data": {
"id": 1,
"first_name": "Jane",
"last_name": "Smith",
"email": "jane.smith917@example.com",
"phone_number": "+441234567890",
"birthday": "01/01/2000",
"nationality": "GB"
}
}
This endpoint is used to update the details of a bill payer.
HTTP Request
PATCH /api/partner/order/{order_id}/tenant/{tenant_id}
Body Data
The details of the bill-paying tenant must be provided in JSON in the body of the request. All parameters are optional, send only the fields you wish to update.
| Parameter | Description |
|---|---|
| first_name | First name of the tenant |
| last_name | Last name of the tenant |
| Email address of the tenant | |
| phone_number | Mobile number of the tenant. This should include the country code e.g. +441234567890 |
| birthday | Tenant's date of birth. This must be in DD/MM/YYYY format |
| nationality | Nationality of the tenant. This must be a country code in ISO 3166-1 alpha-2 format (e.g. GB) |
Delete Bill Payer
curl -X DELETE
'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/tenant/{tenant_id}'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"message": "Tenant has been removed"
}
This endpoint removes a bill payer from an order.
HTTP Request
DELETE /api/partner/order/{order_id}/tenant/{tenant_id}
Get Tenant Mandate
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/tenant/{tenant_id}/mandate'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"data": {
"name": "Jane Smith",
"status": "active"
}
}
This endpoint returns the mandate of a given tenant.
HTTP Request
GET /api/partner/order/{order_id}/tenant/{tenant_id}/mandate
Possible Status Values
| Status | Description |
|---|---|
| nomandate | A direct debit mandate does not exist for this bill payer |
| submitted | New direct debit details have been submitted |
| active | The direct debit mandate is active and funds can be taken |
| cancelled | The direct debit mandate has been cancelled |
| rejected | The bank account does not permit direct debits |
| pending | The direct debit is in the process of being set up |
| suspended | The bank has suspended the direct debit |
Update Tenant Mandate
curl -X PATCH
'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/tenant/{tenant_id}/mandate'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "account_name": "Jane Smith", "account_number": "12345678", "sort_code": "123456" }'
The above command returns JSON structured like this:
{
"data": {
"name": "Jane Smith",
"status": "pending"
}
}
This endpoint will update the mandate of a given tenant. Please note, the tenant's current mandate must have a status of nomandate, rejected, or cancelled before it can be updated. To update an active mandate, the tenant must cancel it first through their bank.
HTTP Request
PATCH /api/partner/order/{order_id}/tenant/{tenant_id}/mandate
Body Data
The payment details must be provided in JSON in the body of the request (see example on the right).
| Parameter | Description |
|---|---|
| account_name | The name on the bank account. This must be between 2 and 18 characters long. |
| account_number | Bank account number. This must be 8 digits. |
| sort_code | Bank account sort code. This must be 6 digits. |
Partner Packages
Partner packages are a type of bills package where a business is responsible for paying the utility bills in the property.
Get Partner Package Quote
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/quote?housemates=3&address_id=VglSD9KF3EKcNz_RRXPVV'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"name": "Renewable Energy",
"description": "...",
"is_hidden": false,
"is_essential": true,
"priority": 10,
"logo_path": "...",
"created_at": "2020-07-21T00:00:00.000000Z",
"updated_at": "2020-07-21T00:00:00.000000Z",
"bills": [
{
"id": 1,
"name": "Standard Plan",
"description": null,
"description_html": null,
"is_required": false,
"additional": null,
"provider": {
"id": 1,
"name": "...",
"email": "...",
"logo_path": "...",
"created_at": "2021-09-15T00:00:00.000000Z",
"updated_at": "2021-09-15T00:00:00.000000Z"
},
"prices": [
{
"id": 1,
"bill_id": 1,
"housemates": 3,
"price_per_housemate": "35.00",
"price_total": "105.00",
"created_at": "2021-09-15T00:00:00.000000Z",
"updated_at": "2021-09-15T00:00:00.000000Z"
}
]
}
]
}
],
"service_charge": "22.00",
"service_charge_per_housemate": "7.33"
}
This endpoint returns a quote with an array of the utilities we offer (e.g. Internet, Council Tax, etc.). Each utility contains an array of associated bills and their prices.
HTTP Request
GET /api/partner/quote
URL Parameters
| Parameter | Description |
|---|---|
| housemates | Number of housemates |
| address_id | The address_id of the property. You can get it from the Find an Address endpoint. It is the preferred way of providing the address but you may alternatively use the line1, city and postcode fields below. |
| line1 | The first line of the property address. This is required without the address_id. |
| line2 | The second line of the property address. |
| city | The city line of the property address. This is required without the address_id. |
| county | The county line of the property address. |
| postcode | The postcode of the property. This is required without the address_id. |
| is_student | If set to true, the council tax add-on will not be present. False by default. |
Create Partner Package
You must send the package details in JSON within the body of the request. Here is an example:
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/partner-order'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "bills": [ { "id" : "1", "account_number": "..." } ], "tenancy_start": "01/01/21", "tenancy_end": "01/31/21", "housemates": 2, "is_student": false, "address": { "address_id" : "VglSD9KF3EKcNz_RRXPVV" }, "account_name": "John Johnson", "account_number" : "12345678", "sort_code" : "123456", "billing_address" : { "line1": "...", "line2": "...", "city": "...", "county": "...", "postcode": "..." }, "tenants": [ { "first_name": "John", "last_name": "Johnson", "phone_number": "...", "email_address": "john@example.com" } ] }'
{
"bills": [
{
"id": "1",
"account_number": "..."
}
],
"tenancy_start": "01/01/21",
"tenancy_end": "01/12/21",
"housemates": 2,
"is_student": false,
"address": {
"address_id": "VglSD9KF3EKcNz_RRXPVV"
},
"account_name": "John Johnson",
"account_number": "12345678",
"sort_code": "123456",
"billing_address": {
"line1": "...",
"line2": "...",
"city": "...",
"county": "...",
"postcode": "..."
},
"tenants": [
{
"first_name": "John",
"last_name": "Johnson",
"phone_number": "...",
"email_address": "john@example.com"
}
]
}
The above command returns JSON structured like this:
{
"data": {
"id": 1,
"property_id": 7,
"tenancy_start": "2021-01-01T00:00:00.000000Z",
"tenancy_end": "2021-01-12T00:00:00.000000Z",
"tenancy_type": "Bills Included Package",
"tenancy": {
"id": 1,
"bill_payers": 1,
"housemates": 2,
"status": "Bills Being Setup",
"status_id": 10,
"responsibility": "Partner Package",
"move_in_date": "2021-01-01T00:00:00.000000Z",
"order": {
"id": 1,
"partner_id": 1,
"package_id": 1,
"package": "Bronze",
"add_ons": [],
"negotiator": "Un-assigned",
"reference": "C00Bhy",
"origin": "API",
"created_at": "2022-01-06T10:36:01.000000Z"
}
},
"property": {
"id": 772,
"address_line1": "123 Test Lane",
"address_line2": null,
"address_line3": null,
"address_line4": null,
"address_city": "London",
"address_county": "Greater London",
"address_postcode": "EC1V2NX",
"status_id": 5,
"status": "Unknown",
"created_at": "2022-12-06T15:39:00.000000Z",
"updated_at": "2022-12-06T15:39:03.000000Z",
"external_id": "o8dsMjMQAb2qOvVGfB66a",
"mpan": "1900000000001",
"mpan_top_line": "040000000001E20180314",
"mpan_economy7": true,
"mpan_profile_class": "04",
"mpan_energisation_status": "E",
"mprn": null,
"uprn": null,
"gspid": "_J",
"meter_type_electric": "RCAMY",
"serial_number_electric": "E11Z106041",
"serial_number_gas": null
},
"created_at": "2022-01-06T10:36:01.000000Z",
"updated_at": "2022-01-06T10:36:01.000000Z"
}
}
This endpoint is used to create partner package.
HTTP Request
POST /api/partner/partner-order
Body Data
The package details must be provided in JSON in the body of the request (see example on the right).
| Parameter | Description |
|---|---|
| bills | An array of JSON objects containing the bill id and the account_number (optional) of each bill. |
| tenancy_start | The date the tenancy starts. This must be in DD/MM/YY format. |
| tenancy_end | The date the tenancy ends. This must be in DD/MM/YY format. |
| housemates | Number of housemates. |
| is_student | A boolean that denotes the type of the bills package. Please set this to true for students or false for professional tenants. |
| payment_method | This should be either bank-transfer or direct-debit. This value is optional and will be direct-debit by default. |
| address | A JSON object containing either the address_id (which you can get from the Find an Address endpoint), or the complete address of the property (line1, line2, city, county and postcode). |
| account_name | The name on the bank account |
| account_number | Bank account number |
| sort_code | Bank account sort code |
| billing_address | A JSON object containing the billing address. This should include entries for line1, line2, city, county and postcode. |
| tenants | An array of JSON objects containing the first_name,last_name, phone_number and email_address of each tenant. The phone number must include the country code (e.g. +441234567890) |
| property_reference | The reference of the property in your system. This value is optional. |
Property Tenancies
List Tenancies
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/property/1/tenancy/1'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"data": {
"id": 1,
"property_id": 1,
"tenancy_start": "2021-12-20T00:00:00.000000Z",
"tenancy_end": "2022-12-20T00:00:00.000000Z",
"tenancy_type": "Void Period",
"tenancy": {
"id": 1,
"property_empty": true,
"responsible_tenant": {
"first_name": "...",
"last_name": "...",
"email_address": "...",
"phone_number": "..."
},
"responsible_address": {
"line1": "123 Test Lane",
"line2": null,
"city": "London",
"county": null,
"postcode": "..."
},
"sse": false
},
"property": {
"id": 1,
"address_line1": "...",
"address_line2": "...",
"address_line3": null,
"address_line4": null,
"address_city": "...",
"address_county": "...",
"address_postcode": "...",
"status_id": 5,
"status": "Unknown",
"created_at": "2021-12-06T00:00:00.000000Z",
"updated_at": "2021-12-06T00:00:00.000000Z",
"external_id": "o8dsMjMQAb2qOvVGfB66a",
"retrieved_at": "2022-12-06T15:39:03.000000Z",
"mpan": "...",
"mprn": "...",
"uprn": "..."
},
"created_at": "2021-12-06T00:00:00.000000Z",
"updated_at": "2021-12-06T00:00:00.000000Z"
}
}
This endpoint lists the tenancies associated with a property.
HTTP Request
GET /api/partner/property/{property_id}/tenancy/{tenancy_id}
Update tenancy dates
The above command returns JSON structured like this:
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/property/1/tenancy/1'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "tenancy_start": "23/07/21", "tenancy_end": "24/07/21" }'
This endpoint is used to update the dates of a tenancy.
HTTP Request
PATCH /api/partner/property/{property_id}/tenancy/{tenancy_id}
Body Data
The dates must be provided in JSON in the body of the request (see example on the right).
| Parameter | Description |
|---|---|
| tenancy_start | The date the tenancy starts. This must be in DD/MM/YY format. |
| tenancy_end | The date the tenancy ends. This must be in DD/MM/YY format. |
Leads
Create Lead
You must send the lead details in JSON within the body of the request. Here is an example:
{
"tenancy_start": "01/07/22",
"tenancy_end": "01/07/23",
"existing_tenancy": false,
"notifications": true,
"managing_party_name": "Tom's Letting Agent",
"address": {
"line1": "123 Test Lane",
"line2": "",
"city": "London",
"county": "Greater London",
"postcode": "EC1V2NX"
},
"tenants": [
{
"first_name": "Bill",
"last_name": "Appleseed",
"phone_number": "+441234567890",
"email_address": "bill.appleseed@example.com"
}
]
}
Instead of the complete address, you can send the postcode and the address_id. Here is an example:
{
"tenancy_start": "01/07/22",
"tenancy_end": "01/07/23",
"existing_tenancy": false,
"notifications": true,
"managing_party_name": "Tom's Letting Agent",
"address": {
"address_id": "VglSD9KF3EKcNz_RRXPVV",
"postcode": "BN108AP"
},
"tenants": [
{
"first_name": "Bill",
"last_name": "Appleseed",
"phone_number": "+441234567890",
"email_address": "bill.appleseed@example.com"
}
]
}
An address is only required when
notificationsis true. Ifnotificationsis false, the address object can be omitted:
{
"tenancy_start": "01/07/22",
"tenancy_end": "01/07/23",
"existing_tenancy": false,
"notifications": false,
"managing_party_name": "Tom's Letting Agent",
"tenants": [
{
"first_name": "Bill",
"last_name": "Appleseed",
"phone_number": "+441234567890",
"email_address": "bill.appleseed@example.com"
}
]
}
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/lead'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "tenancy_start": "01/07/22", "tenancy_end": "01/07/23", "notifications": true, "existing_tenancy": true, "managing_party_name": "Example Agent", "address": { "line1": "123 Test Lane", "line2": "", "city": "London", "county": "Greater London", "postcode": "EC1V2NX" }, "tenants": [{ "first_name": "Bill", "last_name": "Appleseed", "phone_number": "+441234567890", "email_address": "bill.appleseed@example.com" }]}'
The above command returns JSON structured like this:
{
"data": {
"id": 1,
"partner_id": 1,
"tenancy_start": "2022-07-01T00:00:00.000000Z",
"tenancy_end": "2023-07-01T00:00:00.000000Z",
"tenancy_type": "New Tenancy",
"completed_at": null,
"managing_party_name": "Example Agent",
"property": {
"id": 1,
"address_line1": "123 Test Lane",
"address_line2": null,
"address_line3": null,
"address_line4": null,
"address_city": "London",
"address_county": "Greater London",
"address_postcode": "EC1V2NX",
"status_id": 1,
"status": "New Tenancy",
"created_at": "2020-05-01 12:00:00",
"updated_at": "2020-05-01 12:00:00",
"external_id": null,
"mpan": null,
"mpan_top_line": null,
"mpan_economy7": null,
"mpan_profile_class": null,
"mpan_energisation_status": null,
"mprn": null,
"uprn": null,
"gspid": null,
"meter_type_electric": null,
"serial_number_electric": null,
"serial_number_gas": null
},
"property_reference": null,
"tenants": [
{
"id": 1,
"first_name": "Bill",
"last_name": "Appleseed",
"phone_number": "+441234567890",
"email_address": "bill.appleseed@example.com",
"unsubscribed": false,
"created_at": "2020-05-01 12:00:00",
"updated_at": "2020-05-01 12:00:00"
}
],
"created_at": "2020-04-23T18:04:07.000000Z"
},
"meta": {
"links": {
"index": "https://sandbox.billingbetter.co.uk/api/partner/lead/",
"show": "https://sandbox.billingbetter.co.uk/api/partner/lead/1"
}
}
}
This endpoint is used to create a new lead within the Homebox platform. Leads provide a way to invite new users to find out more about our services.
Upon creation, if the tenancy_start date is within two weeks, each tenant will be sent an SMS message and email inviting them to sign up to a bills package. If they do not sign up after 72 hours, a reminder message is sent to them.
After another 72 hours, we'll automatically contact the relevant bill providers and inform them of a change in the tenancy for that property. We will also notify the tenants of this. To disable these utility notifications, you may set the notifications parameter to false when creating the lead. If omitted, this parameter will default to true and utility notifications will be sent.
When creating a lead, there are two ways to provide the property address:
An object with the full address details (line1, city, postcode).
An object with the postcode and the address_id (which you can get from the Find an Address endpoint)
Please note, an address is only required when notifications is true. If notifications is false, the address object can be omitted.
HTTP Request
POST /api/partner/lead
Body Data
The details of the lead must be provided in JSON in the body of the request (see example on the right).
| Parameter | Description |
|---|---|
| tenancy_start | The date the tenancy starts. This must be in DD/MM/YY format. |
| tenancy_end | The date the tenancy ends. This must be in DD/MM/YY format. |
| address | A JSON object containing either the address_id (which you can get from the Find an Address endpoint), or the complete address of the property (line1, line2, city, county and postcode). This is required when notifications is true. |
| tenants | An array of JSON objects containing the tenant details. Each tenant should include entries for their first_name, last_name, phone_number and email_address. Please ensure the phone number includes the country code e.g. +441234567890. |
| notifications | A boolean that specifies if the bill providers should receive tenancy occupancy notifications. This parameter is optional and will default to true if it is omitted. |
| existing_tenancy | A boolean value which denotes whether the tenant is moving into a new tenancy, or an existing tenancy. This value changes the notifications we send the bill providers. If omitted, this value defaults to false indicating a new tenancy. |
| property_reference | The reference of the property in your system. This value is optional and will be null by default. |
| managing_party_name | The name of the business or individual who is managing the tenancy move-in (usually a letting agent or landlord e.g. Tom's Lettings Agent or John Smith). This parameter is optional and will default to NULL if it is omitted. |
List Leads
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/lead'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"partner_id": 1,
"tenancy_start": "2020-05-01T00:00:00.000000Z",
"tenancy_end": "2021-10-01T00:00:00.000000Z",
"tenancy_type": "New Tenancy",
"completed_at": null,
"managing_party_name": "Example Agent",
"property": { ... },
"property_reference": "t0013981",
"tenants": [...],
"created_at": "2020-04-23T18:04:07.000000Z"
}
],
"links": {
"first": "https://sandbox.billingbetter.co.uk/api/partner/lead?page=1",
"last": "https://sandbox.billingbetter.co.uk/api/partner/lead?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://sandbox.billingbetter.co.uk/api/partner/lead",
"per_page": 50,
"to": 1,
"total": 1
}
}
This endpoint can be used to retrieve all the leads you have created. You can also retrieve a specific lead by specifying the ID .e.g /api/partner/lead/1.
HTTP Request
GET /api/partner/lead
URL Parameters
| Parameter | Description |
|---|---|
| page | Page of results |
Meter Readings
Create Meter Reading for an Order
curl --location --request POST 'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/readings' \
--form 'date_of_reading="2021/06/20"' \
--form 'reading="299"' \
--form 'type="gas"' \
--form 'image=@"/path/to/file"'
The above command returns JSON structured like this:
{
"id": 3,
"source": "path/to/file.jpg",
"state": "complete",
"reading": "299",
"reading2": null,
"date_of_reading": "2021-06-20T00:00:00.000000Z",
"created_at": "2021-06-21T19:31:05.000000Z",
"type": "Gas",
"updated_at": "2021-06-21T19:31:05.000000Z",
"property": {
"id": 1,
"address_line1": "Oxford Road",
"address_line2": null,
"address_line3": null,
"address_line4": null,
"address_city": "Oxford",
"address_county": "Oxfordshire",
"address_postcode": "OX84 1DD",
"status_id": 2,
"status": "Bills Package",
"created_at": "2021-06-15T21:31:56.000000Z",
"updated_at": "2021-06-15T21:32:42.000000Z",
"external_id": "o8dsMjMQAb2qOvVGfB66a",
"retrieved_at": "2022-12-06T15:39:03.000000Z",
"mpan": null,
"mprn": null,
"uprn": null
}
}
This endpoint creates a new meter reading against a given order. An optional image can be submitted with the meter reading.
HTTP Request
POST /api/partner/order/{order_id}/readings
Form Data
The request of the body must follow the following format:
| Parameter | Description |
|---|---|
| date_of_reading | Date that the reading was taken, in format of YYYY-MM-DD |
| reading | This must be an integer greater than 0. |
| reading2 | This must be an integer greater than 0. Should only be sent for readings of the type "electric" and that belong to a property that has an Economy7 meter. (optional) |
| type | Types allowed are "electric", "gas" or "water". |
List Meter Readings for an Order
curl --location --request GET 'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/readings'
The above command returns JSON structured like this:
{
"data": [
{
"id": 2,
"source": null,
"state": "complete",
"reading": "299",
"reading2": null,
"date_of_reading": "2021-06-20T00:00:00.000000Z",
"created_at": "2021-06-21T19:31:05.000000Z",
"type": "Gas",
"updated_at": "2021-06-21T19:31:05.000000Z",
"bill_provider": null,
"property": {
"id": 1,
"address_line1": "Oxford Road",
"address_line2": null,
"address_city": "Oxford",
"address_county": "Oxfordshire",
"address_postcode": "OX84 1DD",
"status_id": 2,
"status": "Bills Package",
"created_at": "2021-06-15T21:31:56.000000Z",
"updated_at": "2021-06-15T21:32:42.000000Z",
"external_id": null,
"uprn": null
}
}
]
}
This endpoint will return a list of all Meter Readings associated with a given order.
HTTP Request
GET /api/partner/order/{order_id}/readings
Body Data
| Parameter | Description |
|---|---|
| limit | Limit the number of results |
| page | Retrieve the given page number |
Create Meter Reading for a Property
curl --location --request POST 'https://sandbox.billingbetter.co.uk/api/partner/property/{property_id}/readings' \
--form 'date_of_reading="2021/06/20"' \
--form 'reading="299"' \
--form 'type="gas"' \
--form 'image=@"/path/to/file"'
The above command returns JSON structured like this:
{
"id": 3,
"source": "path/to/file.jpg",
"state": "complete",
"reading": "299",
"reading2": null,
"date_of_reading": "2021-06-20T00:00:00.000000Z",
"created_at": "2021-06-21T19:31:05.000000Z",
"type": "Gas",
"updated_at": "2021-06-21T19:31:05.000000Z",
"bill_provider": null,
"property": {
"id": 1,
"address_line1": "Oxford Road",
"address_line2": null,
"address_city": "Oxford",
"address_county": "Oxfordshire",
"address_postcode": "OX84 1DD",
"status_id": 2,
"status": "Bills Package",
"created_at": "2021-06-15T21:31:56.000000Z",
"updated_at": "2021-06-15T21:32:42.000000Z",
"external_id": null,
"uprn": null
}
}
This endpoint creates a new meter reading against a given property. An optional image can be submitted with the meter reading.
HTTP Request
POST /api/partner/property/{property_id}/readings
Form Data
The request of the body must follow the following format:
| Parameter | Description |
|---|---|
| date_of_reading | Date that the reading was taken, in format of YYYY-MM-DD |
| reading | This must be an integer greater than 0. |
| reading2 | This must be an integer greater than 0. Should only be sent for readings of the type "electric" and that belong to a property that has an Economy7 meter. (optional) |
| type | Types allowed are "electric", "gas" or "water". |
List Meter Readings for a Property
curl --location --request GET 'https://sandbox.billingbetter.co.uk/api/partner/property/{property_id}/readings'
The above command returns JSON structured like this:
{
"data": [
{
"id": 2,
"source": null,
"state": "complete",
"reading": "299",
"reading2": null,
"date_of_reading": "2021-06-20T00:00:00.000000Z",
"created_at": "2021-06-21T19:31:05.000000Z",
"type": "Gas",
"updated_at": "2021-06-21T19:31:05.000000Z",
"bill_provider": null,
"property": {
"id": 1,
"address_line1": "Oxford Road",
"address_line2": null,
"address_city": "Oxford",
"address_county": "Oxfordshire",
"address_postcode": "OX84 1DD",
"status_id": 2,
"status": "Bills Package",
"created_at": "2021-06-15T21:31:56.000000Z",
"updated_at": "2021-06-15T21:32:42.000000Z",
"external_id": null,
"uprn": null
}
}
]
}
This endpoint will return a list of all Meter Readings associated with a given property.
HTTP Request
GET /api/partner/property/{property_id}/readings
Body Data
| Parameter | Description |
|---|---|
| limit | Limit the number of results |
| page | Retrieve the given page number |
Postal Bills
Create Postal Bill
curl --location --request POST 'https://sandbox.billingbetter.co.uk/api/partner/order/{order_id}/postal-bills' \
--form 'tenant_notes="Tenant note"' \
--form 'file=@"path/to/file"'
The above command returns JSON structured like this:
{
"data": [
{
"id": 3,
"name": "kyFbpW5dC0lMk7q2jMthQuLA1xP0BaZzFYFItyJk.png",
"source": "https://path_to_file.com/kyFbpW5dC0lMk7q2jMthQuLA1xP0BaZzFYFItyJk.png",
"notes": "Tenant note",
"feedback": null,
"state": "Requires Action",
"type": "-",
"created_at": "2021-06-21"
}
]
}
This endpoint will store the given postal bill against the order and return the postal bill data.
HTTP Request
POST /api/partner/order/{order_id}/postal-bills
List Postal Bills
curl --location --request GET 'https://sandbox.billingbetter.co.uk/api/partner/order/1/postal-bills'
The above command returns JSON structured like this:
{
"data": [
{
"id": 3,
"name": "kyFbpW5dC0lMk7q2jMthQuLA1xP0BaZzFYFItyJk.png",
"source": "https://billing-better-account-managers.s3.eu-west-2.amazonaws.com/postal-bills/kyFbpW5dC0lMk7q2jMthQuLA1xP0BaZzFYFItyJk.png",
"notes": "Testing note",
"feedback": null,
"state": "Requires Action",
"type": "Renewable Energy",
"created_at": "2021-06-21"
}
]
}
This endpoint will return the postal bills associated with a specific order.
HTTP Request
GET /api/partner/order/{order_id}/postal-bills
Query Data
| Parameter | Description |
|---|---|
| limit | Limit the number of results you see |
| page | Retrieve the given page number. |
Void Periods
Create Void Period
You must send the tenancy details in JSON within the body of the request. Here is an example:
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/void'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "property_id": 1, "tenancy_start": "01/07/22", "tenancy_end": "15/07/22", "is_premium" : true, "property_empty" : true, "notifications" : true, "responsible_tenant" : { "first_name" : "John", "last_name" : "Doe", "phone_number" : "+441234567891", "email_address" : "john.doe@example.test" }, "responsible_address" : { "line1" : "123 Test", "line2" : "Example Road", "city" : "London", "county" : "Greater London", "postcode" : "BN108UE" } }'
{
"property_id": 1,
"tenancy_start": "01/07/22",
"tenancy_end": "15/07/22",
"is_premium" : true,
"property_empty" : true,
"notifications" : true,
"responsible_tenant" : {
"first_name" : "John",
"last_name" : "Doe",
"phone_number" : "+441234567891",
"email_address" : "john.doe@example.test"
},
"responsible_address" : {
"line1" : "123 Test",
"line2" : "Example Road",
"city" : "London",
"county" : "Greater London",
"postcode" : "BN108UE"
}
}
Although it's preferred that you send the property_id, you can also send the address_id or the complete address of the property. Here is an example:
{
"address": {
"address_id" : "VglSD9KF3EKcNz_RRXPVV"
}
}
or
{
"address": {
"line1": "123 Test Lane",
"line2": "",
"city": "London",
"county": "Greater London",
"postcode": "EC1V2NX"
}
}
The above command returns JSON structured like this:
{
"data": {
"id": 1,
"property_id": 1,
"tenancy_start": "2022-07-01T00:00:00.000000Z",
"tenancy_end": "2022-07-15T00:00:00.000000Z",
"tenancy_type": "Void Period",
"tenancy": {
"id": 1,
"property_empty": true,
"responsible_tenant": {
"first_name": "John",
"last_name": "Doe",
"email_address": "john.doe@example.test",
"phone_number": "+441234567891"
},
"responsible_address": {
"line1" : "123 Test",
"line2" : "Example Road",
"city" : "London",
"county" : "Greater London",
"postcode" : "BN108UE"
}
},
"property": {
"id": 1,
"address_line1": "123 Test",
"address_line2": null,
"address_line3": null,
"address_line4": null,
"address_city": "London",
"address_county": "Greater London",
"address_postcode": "BN108UE",
"status_id": 5,
"status": "Unknown",
"created_at": "2022-01-05T00:00:00.000000Z",
"updated_at": "2022-01-05T00:00:00.000000Z",
"external_id": "o8dsMjMQAb2qOvVGfB66a",
"retrieved_at": "2022-12-06T15:39:03.000000Z",
"mpan": null,
"mprn": null,
"uprn": null
},
"created_at": "2022-01-10T00:00:00.000000Z",
"updated_at": "2022-01-10T00:00:00.000000Z"
}
}
This endpoint is used to add a void period to a property.
HTTP Request
POST /api/partner/void
Body Data
The tenancy details must be provided in JSON in the body of the request (see example on the right).
| Parameter | Description |
|---|---|
| address | A JSON object containing either the address_id (which you can get from the endpoint Find an address), or the complete address of the property (line1, line2, city, county and postcode). |
| tenancy_start | The date the tenancy starts. This must be in DD/MM/YY format. |
| tenancy_end | The date the tenancy ends. This must be in DD/MM/YY format and is optional. |
| is_premium | A boolean that specifies if the void should use our premium service. If this value is true, we will contact all utility suppliers for the void period and provide you with a single list of bills to pay to cover the void period. Please note the energy will be switched to our chosen void supplier using the cheapest tariff avaliable for the void (the standard variable tariff). This parameter is optional and will default to false if it is omitted. |
| property_empty | A boolean that specifies if the property will be empty during the void tenancy. |
| notifications | A boolean that specifies if the bill providers should receive tenancy occupancy notifications. This parameter is optional and will default to false if it is omitted. |
| responsible_tenant | A JSON object containing the first_name, last_name, phone_number and email_address of the tenant responsible for the tenancy. |
| responsible_address | A JSON object containing the line1,line2,city,county and postcode of the property responsible for the tenancy. |
| forwarding_details | An optional JSON object containing the name, phone_number, email_adress,line1,line2,city,county and postcode of the previous lead tenant. |
| property_reference | The reference of the property in your system. This value is optional. |
Account
Get Account Details
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/account'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"data": {
"name": "Partner Account",
"management_fee": "10",
"reference_number": "PARTNER1",
"image_path": "...",
"theme_color_primary": "#000000"
}
}
This endpoint is used to retrieve the details of the authenticated partner account.
HTTP Request
GET /api/partner/account
Update Account Details
You must send the partner details in JSON within the body of the request. Here is an example:
{
"name": "Partner Account Renamed",
"reference_number": "PARTNER1",
"image_path": "...",
"theme_color_primary": "#000000"
}
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/account'
-H 'Content-Type: application/json'
-H 'Accept: application/json'
-d '{"name" : "Partner Account Renamed", "theme_color_primary": "#000000", "reference_number": "PARTNER1" }'
The above command returns JSON structured like this:
{
"data": {
"name": "Partner Account Renamed",
"management_fee": "25",
"reference_number": "PARTNER1",
"image_path": "...",
"theme_color_primary": "#000000",
"name_url": "partner-account-renamed"
}
}
This endpoint is used to update the account settings of an authenticated partner account. Only parameters that are included in the request will be actioned and saved. The response will return the partner account with the changed values.
HTTP Request
POST /api/partner/account
Body Data
The details of the partner must be provided in JSON in the body of the request (see example on the right).
| Parameter | Description |
|---|---|
| name | Name of your company |
| theme_color_primary | Your chosen colour. This will be used to style components to match your brand. This should be sent as a hex value (eg. #E3E3E3). |
| reference_number | Your chosen reference number. |
Branch Accounts
Create Branch Accounts
curl -X POST
https://sandbox.billingbetter.co.uk/api/partner/child/store
-H 'Accept: application/json'
-H 'Content-Type: multipart/form-data; boundary=--------------------------112373993866134523006304'
-F 'name=Child Partner'
-F 'theme_color_primary="#000000"'
-F email=child.partner1@example.com
-F reference_number=123456789
-F image_path=@/C:/path/to/logo.png
The above command returns JSON structured like this:
{
"data": {
"id": 1,
"message": "Child partner has been successfully created."
}
}
This endpoint is used to create a new child partner within your partner account. Creating a child partner will automatically send an email invite prompting them to set up their account. The invite email will be styled using the name and colours associated with your partner account.
HTTP Request
POST /api/partner/child/store
Update a Branch Account
curl -X POST
https://sandbox.billingbetter.co.uk/api/partner/child/1
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "name" : "Child Partner Renamed", "theme_color_primary": "#000000", "reference_number": "123456789" }'
The above command returns JSON structured like this:
{
"data": [
{
"id": 30,
"name": "Child Partner Renamed",
"management_fee": "25",
"theme_color_primary": "#000000",
"image_path": "...",
"reference_number": "123456789"
}
]
}
This endpoint is used to update a child partner’s account settings. This endpoint works in the same way as updating a regular partner except, the management fee which is inherited. The response returns the updated child partner.
HTTP Request
POST /api/partner/child/{id}
Body Data
The details of the partner must be provided in JSON in the body of the request (see example on the right).
| Parameter | Description |
|---|---|
| name | Name of child company |
| theme_color_primary | Your chosen colour. This will be used to style components to match your brand. This should be sent as a hex value (eg. #E3E3E3) |
| reference_number | Your chosen reference number. |
List Branch Accounts
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/child?page=1'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"name": "Child Partner",
"theme_color_primary": "#000000",
"image_path": "...",
"reference_number": "123456789"
}
]
}
This endpoint is used to list all Child Partners which are associated your partner account. This endpoint is also paginated and by default, the page will be set to 1 if no page is specified. You can also retrieve a single partner by specifying the ID .e.g /api/partner/child/1
HTTP Request
GET /api/partner/child
URL Parameters
| Parameter | Description |
|---|---|
| page | Page of results |
Create Property for a Branch Account
You must send the property details in JSON within the body of the request. Here is an example:
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/child/{child_id}/property'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "address": { "address_id" : "VglSD9KF3EKcNz_RRXPVV" }}'
{
"address" : {
"address_id" : "VglSD9KF3EKcNz_RRXPVV"
}
}
Although it's preferred that you send the address_id, you can also send the full address of the property. Here is an example:
{
"address": {
"line1": "123 Test Lane",
"line2": "",
"city": "London",
"county": "Greater London",
"postcode": "EC1V2NX"
}
}
The above command returns JSON structured like this:
{
"data": {
"id": 1,
"address_line1": "123 Test Lane",
"address_line2": null,
"address_line3": null,
"address_line4": null,
"address_city": "London",
"address_county": "Greater London",
"address_postcode": "EC1V2NX",
"status_id": 1,
"status": "New Tenancy",
"created_at": "2022-01-06T10:27:12.000000Z",
"updated_at": "2022-01-06T10:27:12.000000Z",
"external_id": "UN5Iu2KV9zOVJbacTYozt",
"retrieved_at": null,
"mpan": null,
"mprn": null,
"uprn": null
}
}
This endpoint creates a new property on behalf of a Child Partner. The Child Partner is specified using their ID in the URL of the request.
HTTP Request
POST /api/partner/child/{child_id}/property
Body Data
The property details must be provided in JSON in the body of the request (see example on the right).
| Parameter | Description |
|---|---|
| address | A JSON object containing either the address_id (which you can get from the Find an Address endpoint), or the complete address of the property (line1, line2, city, county and postcode). |
| property_reference | The reference of the property in your system. This value is optional and will be null by default. |
Create Tenant Package for Branch Account
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/child/1/order'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "package_id": 2, "add_ons": [ 27 ], "address": { "address_id" : "xQGCuZ3irsRyb-zZkJ6OD" }, "reference": "HOMEBOX1", "total_occupants": 2, "bill_payers": 1, "household_type": "student", "tenancy_move_in": "01/10/19", "tenancy_start": "01/10/19", "tenancy_end": "01/10/20" }'
{
"package_id": 2,
"add_ons": [ 27 ],
"address" : {
"address_id" : "xQGCuZ3irsRyb-zZkJ6OD"
},
"reference": "HOMEBOX1",
"total_occupants": 2,
"bill_payers": 1,
"household_type": "student",
"tenancy_move_in": "01/10/19",
"tenancy_start": "01/10/19",
"tenancy_end": "01/10/20"
}
Although it's preferred that you send the address_id, you can also send the full address of the property. Here is an example:
{
"package_id": 2,
"add_ons": [ 27 ],
"address" : {
"line1": "123 Test Lane",
"line2": "",
"city": "London",
"county": "Greater London",
"postcode": "EC1V2NX"
},
"reference": "HOMEBOX1",
"total_occupants": 2,
"bill_payers": 1,
"household_type": "student",
"tenancy_move_in": "01/10/19",
"tenancy_start": "01/10/19",
"tenancy_end": "01/10/20"
}
The above command returns JSON structured like this:
{
"data": {
"order_id": 1
},
"meta": {
"links": {
"index": "https://sandbox.billingbetter.co.uk/api/partner/order/",
"show": "https://sandbox.billingbetter.co.uk/api/partner/order/1"
}
}
}
This endpoint is used to send orders to Homebox on behalf of a Child Partner. The Child Partner is specified using their ID in the URL of the request. Just like the Create Order endpoint, this endpoint returns the integer ID of the saved order.
HTTP Request
POST /api/partner/child/{child_id}/order
Body Data
The details of the order must be provided in JSON in the body of the request (see example on the right).
| Parameter | Description |
|---|---|
| package_id | The numerical ID of the chosen package. The package IDs can be retrieved from the Retrieve Packages endpoint. |
| add_ons | An array of the chosen add-on IDs. This can be excluded if no add-ons were selected. |
| address | A JSON object containing either the address_id (which you can get from the Find an Address endpoint), or the complete address of the property (line1, line2, city, county and postcode). |
| total_occupants | The number of tenants within the property. |
| bill_payers | The number of tenants within the property that will be paying for the bill package. The number of bill_payers must be less than or equal to the number of total_occupants. This parameter is optional and if omitted, the number of bill_payers will default to the number of total_occupants. |
| household_type | This should either student or professional-tenant depending on the property type |
| tenancy_start | The date the tenancy starts. This must be in DD/MM/YY format. |
| tenancy_end | The date the tenancy ends. This must be in DD/MM/YY format. |
| tenancy_move_in | The date the tenants move into their household. This must be in DD/MM/YY format. |
| reference | This field allows you to store a reference against the order which you may use to match the order against its ID in your system. |
| property_reference | The reference of the property in your system. This value is optional and will be null by default. |
| coupon | Coupon code (optional). |
Invite Bill Payers to Branch Tenant Package
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/child/1/order/tenant/api/partner/order/1/invite'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "first_name" : "John", "last_name" : "Appleseed", "phone_number" : "+441234567890" }'
The above command returns JSON structured like this:
{
"data": [
"Tenant was successfully added to order 1"
]
}
This endpoint is used for inviting bill payers to a child order. Only bill payers should be added to the order - you must not add tenants who will not be paying for the package. This endpoint should be used after creating an order using the Create Child Order endpoint.
HTTP Request
POST /api/partner/child/{child_id}/order/{order_id}/invite
Body Data
The details of the bill-paying tenant must be provided in JSON in the body of the request.
| Parameter | Description |
|---|---|
| first_name | First name of the tenant |
| last_name | Last name of the tenant |
| phone_number | Mobile number of the tenant. This should include the country code e.g. +441234567890 |
List Branch Bills Packages
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/child/1/orders'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"partner_id": 1,
"package_id": 2,
"package": "Silver",
"household": {
"id": 1,
"bill_payers": 1,
"housemates": 2,
"status": "Active",
"status_id": 4,
"tenancy_start": "2019-10-01T00:00:00.000000Z",
"tenancy_end": "2020-10-01T00:00:00.000000Z",
"responsibility": "Tenant Package",
"move_in_date": "2019-10-01T00:00:00.000000Z",
"address": {}
}
}
],
"meta": {
"current_page" : 1,
"page_count" : 1,
"total_count": 1
}
}
This endpoint can be used to retrieve all the orders that belong to your child partner. You can also retrieve a specific order by specifying the ID .e.g /api/partner/child/{child_id}/order/1.
HTTP Request
GET /api/partner/child/{child_id}/orders
URL Parameters
| Parameter | Description |
|---|---|
| page | Page of results |
Create Lead for a Branch Account
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/child/1/lead'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "tenancy_start": "01/05/20", "tenancy_end": "01/05/21", "managing_party_name": "Example Agent", "address": { "line1": "123 Test Lane", "line2": "", "city": "London", "county": "Greater London", "postcode": "EC1V2NX" }, "tenants": [{ "first_name": "Bill", "last_name": "Appleseed", "phone_number": "+441234567890", "email_address": "bill.appleseed@example.com" }]}'
The above command returns JSON structured like this:
{
"data": {
"id": 1,
"partner_id": 1,
"tenancy_start": "2020-05-01T00:00:00.000000Z",
"tenancy_end": "2021-10-01T00:00:00.000000Z",
"tenancy_type": "New Tenancy",
"completed_at": null,
"managing_party_name": "Example Agent",
"property": {
"id": 1,
"address_line1": "123 Test Lane",
"address_line2": null,
"address_line3": null,
"address_line4": null,
"address_city": "London",
"address_county": "Greater London",
"address_postcode": "EC1V2NX",
"status_id": 1,
"status": "New Tenancy",
"created_at": "2020-05-01 12:00:00",
"updated_at": "2020-05-01 12:00:00",
"external_id": null,
"mpan": null,
"mpan_top_line": null,
"mpan_economy7": null,
"mpan_profile_class": null,
"mpan_energisation_status": null,
"mprn": null,
"uprn": null,
"gspid": null,
"meter_type_electric": null,
"serial_number_electric": null,
"serial_number_gas": null
},
"property_reference": null,
"tenants": [
{
"id": 1,
"first_name": "Bill",
"last_name": "Appleseed",
"phone_number": "+441234567890",
"email_address": "bill.appleseed@example.com",
"unsubscribed": false,
"created_at": "2020-05-01 12:00:00",
"updated_at": "2020-05-01 12:00:00"
}
],
"created_at": "2020-04-23T18:04:07.000000Z"
},
"meta": {
"links": {
"index": "https://sandbox.billingbetter.co.uk/api/partner/lead/",
"show": "https://sandbox.billingbetter.co.uk/api/partner/lead/1"
}
}
}
This endpoint is used to create a new lead on behalf of a Child Partner. The Child Partner is specified using their ID in the URL of the request. Please see the Create Lead endpoint for more details.
HTTP Request
POST /api/partner/child/{child_id}/lead
Body Data
The details of the lead must be provided in JSON in the body of the request.
| Parameter | Description |
|---|---|
| tenancy_start | The date the tenancy starts. This must be in DD/MM/YY format. |
| tenancy_end | The date the tenancy ends. This must be in DD/MM/YY format. |
| address | A JSON object containing either the address_id (which you can get from the Find an Address endpoint), or the complete address of the property (line1, line2, city, county and postcode). |
| tenants | An array of JSON objects containing the tenant details. Each tenant should include entries for their first_name, last_name, phone_number and email_address. Please ensure the phone number includes the country code e.g. +441234567890. |
| notifications | A boolean that specifies if the bill providers should receive tenancy occupancy notifications. This parameter is optional and will default to true if it is omitted. |
| existing_tenancy | A boolean value which denotes whether the tenant is moving into a new tenancy, or an existing tenancy. This value changes the notifications we send the bill providers. If omitted, this value defaults to false indicating a new tenancy. |
| property_reference | The reference of the property in your system. This value is optional and will be null by default. |
| managing_party_name | The name of the business or individual who is managing the tenancy move-in (usually a letting agent or landlord e.g. Tom's Lettings Agent or John Smith). This parameter is optional and will default to NULL if it is omitted. |
List Leads for a Branch Account
curl -X GET
'https://sandbox.billingbetter.co.uk/api/partner/child/1/lead'
-H 'Accept: application/json'
The above command returns JSON structured like this:
{
"data": [
{
"id": 1,
"partner_id": 1,
"tenancy_start": "2020-05-01T00:00:00.000000Z",
"tenancy_end": "2021-10-01T00:00:00.000000Z",
"completed_at": null,
"managing_party_name": "Example Agent",
"property": { ... },
"property_reference": "t0013981",
"tenants": [...],
"created_at": "2020-04-23T18:04:07.000000Z"
}
],
"links": {
"first": "https://sandbox.billingbetter.co.uk/api/partner/child/1/lead?page=1",
"last": "https://sandbox.billingbetter.co.uk/api/partner/child/1/lead?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"path": "https://sandbox.billingbetter.co.uk/api/partner/child/1/lead",
"per_page": 50,
"to": 1,
"total": 1
}
}
This endpoint can be used to retrieve all leads belonging to a child. You can also retrieve a specific lead by specifying the ID .e.g /api/partner/child/1/lead/1.
HTTP Request
GET /api/partner/child/{child_id}/lead
URL Parameters
| Parameter | Description |
|---|---|
| page | Page of results |
Create Void for a Branch Account
You must send the tenancy details in JSON within the body of the request. Here is an example:
curl -X POST
'https://sandbox.billingbetter.co.uk/api/partner/child/1/void'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-d '{ "property_id": 1, "tenancy_start": "01/07/22", "tenancy_end": "15/07/22", "is_premium" : true, "property_empty" : true, "notifications" : true, "responsible_tenant" : { "first_name" : "John", "last_name" : "Doe", "phone_number" : "+441234567891", "email_address" : "john.doe@example.test" }, "responsible_address" : { "line1" : "123 Test", "line2" : "Example Road", "city" : "London", "county" : "Greater London", "postcode" : "BN108UE" } }'
{
"property_id": 1,
"tenancy_start": "01/07/22",
"tenancy_end": "15/07/22",
"is_premium" : true,
"property_empty" : true,
"notifications" : true,
"responsible_tenant" : {
"first_name" : "John",
"last_name" : "Doe",
"phone_number" : "+441234567891",
"email_address" : "john.doe@example.test"
},
"responsible_address" : {
"line1" : "123 Test",
"line2" : "Example Road",
"city" : "London",
"county" : "Greater London",
"postcode" : "BN108UE"
}
}
The above command returns JSON structured like this:
{
"data": {
"id": 1,
"property_id": 1,
"tenancy_start": "2022-07-01T00:00:00.000000Z",
"tenancy_end": "2022-07-15T00:00:00.000000Z",
"tenancy_type": "Void Period",
"tenancy": {
"id": 1,
"property_empty": true,
"responsible_tenant": {
"first_name": "John",
"last_name": "Doe",
"email_address": "john.doe@example.test",
"phone_number": "+441234567891"
},
"responsible_address": {
"line1" : "123 Test",
"line2" : "Example Road",
"city" : "London",
"county" : "Greater London",
"postcode" : "BN108UE"
}
},
"property": {
"id": 1,
"address_line1": "123 Test",
"address_line2": null,
"address_line3": null,
"address_line4": null,
"address_city": "London",
"address_county": "Greater London",
"address_postcode": "BN108UE",
"status_id": 5,
"status": "Unknown",
"created_at": "2022-01-05T00:00:00.000000Z",
"updated_at": "2022-01-05T00:00:00.000000Z",
"external_id": "o8dsMjMQAb2qOvVGfB66a",
"retrieved_at": "2022-12-06T15:39:03.000000Z",
"mpan": null,
"mprn": null,
"uprn": null
},
"created_at": "2022-01-10T00:00:00.000000Z",
"updated_at": "2022-01-10T00:00:00.000000Z"
}
}
This endpoint is used to add a void period on behalf of a Child Partner. The Child Partner is specified using their ID in the URL of the request. Please see the Create Void Period endpoint for more details.
HTTP Request
POST /api/partner/child/{child_id}/void
Body Data
The tenancy details must be provided in JSON in the body of the request (see example on the right).
| Parameter | Description |
|---|---|
| address | A JSON object containing either the address_id (which you can get from the endpoint Find an address), or the complete address of the property (line1, line2, city, county and postcode). |
| tenancy_start | The date the tenancy starts. This must be in DD/MM/YY format. |
| tenancy_end | The date the tenancy ends. This must be in DD/MM/YY format and is optional. |
| is_premium | A boolean that specifies if the void should use our premium service. If this value is true, we will contact all utility suppliers for the void period and provide you with a single list of bills to pay to cover the void period. Please note the energy will be switched to our chosen void supplier using the cheapest tariff avaliable for the void (the standard variable tariff). This parameter is optional and will default to false if it is omitted. |
| property_empty | A boolean that specifies if the property will be empty during the void tenancy. |
| notifications | A boolean that specifies if the bill providers should receive tenancy occupancy notifications. This parameter is optional and will default to false if it is omitted. |
| responsible_tenant | A JSON object containing the first_name, last_name, phone_number and email_address of the tenant responsible for the tenancy. |
| responsible_address | A JSON object containing the line1,line2,city,county and postcode of the property responsible for the tenancy. |
| forwarding_details | An optional JSON object containing the name, phone_number, email_adress,line1,line2,city,county and postcode of the previous lead tenant. |
| property_reference | The reference of the property in your system. This value is optional. |
Metrics
All metric endpoints return JSON with this structure:
{
"data": {
"name": "New Orders",
"description": "This is the number of new orders for bills packages you have received this month so far.",
"value": "0",
"prefix": null,
"suffix": null,
"formatted": "0"
}
}
We offer several endpoints for retrieving metrics on your orders and their payments. A response will contain the name of the metric, a description and a value. There will also be a prefix, suffix and formatted value. The formatted value is a combination of the metric's value and any prefixes/suffixes.
For all metrics except the Approval Orders and Active Orders metrics, you can optionally specify a custom range. The from and to query parameters allow you to view the value of a metric between two dates (inclusive). These dates must be in YYYY-MM-DD format, for example, ?from=2019-01-01&to=2020-01-01. If only a from date is set, the to date will default to the current date. When no custom range is set, the endpoints will return the month to date value by default.
New Orders
GET /api/partner/metrics/orders/new
Shows the number of new orders.
Approval Orders
GET /api/partner/metrics/orders/approval
Shows the total number of orders that are currently awaiting approval from the Homebox team.
Active Orders
GET /api/partner/metrics/orders/active
Shows the total number of orders that are currently active and are paying each month.
Failed Payments
GET /api/partner/metrics/payments/failed
Shows the number of payments which have failed.
Pending Payments
GET /api/partner/metrics/payments/pending
Shows the number of pending payments.
Successful Payments
GET /api/partner/metrics/payments/successful
Shows the number of payments which have succeeded.
New Leads
GET /api/partner/metrics/leads/new
Shows the number of properties you have submitted for utility notifications.
Orders from Leads
GET /api/partner/metrics/leads/orders
Shows the number of properties that have signed up a bills package as a result of a lead.
Notifications Completed
GET /api/partner/metrics/notifications/completed
Shows the number of properties where utility notifications have been completed.
Calculating Prices
You can find the list of packages we offer using the Retrieve Packages endpoint. Each package contains a list of the different household bills included within the package. There is also another list which contains the extra add-ons which are not included in the package but may be chosen by the customer at an additional cost.
Both the bills and the add-ons within a package include a list of the prices for that bill/add-on. The prices vary depending on the number of tenants in the property. This is indicated by the value of housemates in the price list. For example, if the value of housemates is 2 then the price_per_housemate value is based on two tenants living at the property (per tenant). When implementing our API into your platform, you'll need to ensure you're using the correct price depending on how many tenants are living at the property.
To calculate the monthly price for a package, you must iterate over the bills in the package and sum the price_per_housemate value. This gives the total cost of the package per tenant. To calculate the total price for the household, you must multiply this by the number of tenants. The price for each bill payer can then be calculated by dividing the total price for the household by the number of bill payers.
The service charge bill is included in every package and specifies the amount of commission taken by yourself and Homebox for the order.
Custom Package
If you do not wish to offer our preset packages to your customers, there is also the ability to create a custom bills package through our API. The custom package works in the same way as our preset packages, but there are no bills included by default (except the service charge). Instead, bills must be added to the package as add-ons. This allows tenants to build a package containing only the bills they desire.
To use this package, it must be enabled on your account. You can request this by contacting us at info@homebox.co.uk.
If enabled, you will see an extra package called Custom when calling our Retrieve Packages endpoint. You can create an order using this package with the Create Order endpoint. The value of add_ons should be an array of ids for the desired bills (e.g. [ 54, 55 ]).
Errors
The Homebox Partner API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 403 | Forbidden -- You do not have permission. |
| 404 | Not Found -- The resource could not be found. |
| 422 | Unprocessable Entity -- The given date is invalid. |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |