Getting Started with The Bunch Partner API

Overview

The Bunch Partner API enables you to integrate household bill quote creation and customer management into your application. The API follows RESTful principles and uses JSON for data exchange.

Base URL

https://development-backend.the-bunch.co.uk/partner-api

Authentication

The Bunch Partner API uses Auth0 Client Credentials Flow for authentication. You'll need to obtain an access token before making API requests.

Getting Your Credentials

Before you can start using the API, you'll need:

• Client ID: Your Auth0 application client ID
• Client Secret: Your Auth0 application client secret

Obtaining an Access Token

To get an access token, make a POST request to the /Auth/token endpoint:

curl -X POST "https://development-backend.the-bunch.co.uk/partner-api/Auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret"
  }'

Using the Access Token

Include the access token in the Authorization header of all subsequent requests:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Your First Request

Let's start with a simple request to lookup addresses by postcode. This is often the first step in creating a quote.

Looking Up Addresses

The address lookup endpoint allows you to find available properties at a given UK postcode:

curl -X GET "https://development-backend.the-bunch.co.uk/partner-api/Addresses/lookup?postcode=SW1P%202DX" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Understanding the Response

The response will contain an array of available addresses:

[
  {
    "addressLine1": "Apartment 1",
    "addressLine2": "Chimes Apartments 99-105 Horseferry Road",
    "city": "London",
    "country": "United Kingdom",
    "county": "",
    "postCode": "SW1P 2DX",
    "uprn": "100023123456",
    "addressUid": "4b61cc99-63a7-4639-aa4b-bc06988d4388"
  },
  {
    "addressLine1": "Flat 2",
    "addressLine2": "Chimes Apartments 99-105 Horseferry Road",
    "city": "London",
    "country": "United Kingdom",
    "county": "",
    "postCode": "SW1P 2DX",
    "uprn": "100023123456",
    "addressUid": "45n6cc99-63a7-4639-aa4b-bc06988d4388"
  }
]

Creating Quotes

Once you have an address UID, you can create a quote for household bill services at that property.

Basic Quote Creation

Create a new quote with the selected address and desired packages:

curl -X POST "https://development-backend.the-bunch.co.uk/partner-api/Quotes" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "addressUid": "4b61cc99-63a7-4639-aa4b-bc06988d4388",
    "packages": ["electricity", "gas"]
  }'

Adding Packages

After creating a quote, you can add specific packages and options:

curl -X POST "https://development-backend.the-bunch.co.uk/partner-api/Quotes/{quote-id}/add-packages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "packages": [
      {
        "type": "electricity",
        "tariff": "standard",
        "options": ["green-household-bills"]
      },
      {
        "type": "gas",
        "tariff": "standard"
      }
    ]
  }'

Adding Tenants

Add tenant information to the quote. The first tenant is typically the lead tenant:

curl -X POST "https://development-backend.the-bunch.co.uk/partner-api/Quotes/{quote-id}/add-tenants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "tenants": [
      {
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phoneNumber": "+44123456789",
        "isLeadTenant": true
      }
    ]
  }'

Managing Customers

Once tenants are added to a quote, they become customers. You can then manage their information and set up payments.

Getting Customer Information

Retrieve customer details using their customer ID:

curl -X GET "https://development-backend.the-bunch.co.uk/partner-api/Customers/{customer-id}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Adding Personal Information

Add PSR (Priority Services Register) information and contract dates:

curl -X POST "https://development-backend.the-bunch.co.uk/partner-api/Customers/{customer-id}/finalise-personal-information" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "dateOfBirth": "1990-01-01",
    "isVulnerablePerson": false,
    "psrCategory": [],
    "startDate": "2024-02-01",
    "endDate": "2025-02-01"
  }'

Getting Cost Breakdown

Retrieve the total cost breakdown for a customer:

curl -X GET "https://development-backend.the-bunch.co.uk/partner-api/Customers/{customer-id}/total-cost" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Error Handling

The API returns standard HTTP status codes and detailed error messages to help you handle different scenarios.

Common Status Codes

• 200: Success
• 400: Bad Request - Invalid input data
• 401: Unauthorized - Invalid or expired token
• 404: Not Found - Resource doesn't exist
• 422: Unprocessable Entity - Validation errors
• 500: Internal Server Error

Error Response Format

Error responses include detailed information about what went wrong:

{
  "success": false,
  "errors": [
    "Invalid postcode format",
    "Address not found"
  ],
  "value": null
}

Best Practices for Error Handling

• Always check the HTTP status code
• Parse error messages and display them to users
• Implement retry logic for transient errors (5xx)
• Log errors for debugging purposes
• Handle authentication errors by refreshing tokens

Best Practices

Follow these best practices to ensure reliable integration with The Bunch Partner API.

Authentication

• Store tokens securely and reuse them until expiration
• Implement automatic token refresh before expiration
• Never expose client secrets in client-side code
• Use environment variables for credentials in production

Rate Limiting

• Implement appropriate delays between requests
• Handle rate limit responses gracefully
• Use exponential backoff for retries

Data Validation

• Validate postcodes before sending requests
• Check required fields before API calls
• Sanitize user input to prevent errors

User Experience

• Show loading states during API calls
• Provide clear error messages to users
• Implement proper form validation
• Cache address lookup results when appropriate

Next Steps

Now that you understand the basics, here are some next steps to continue your integration:

Explore More Features

• Browse the complete API reference
• Learn about broadband integration in the API Reference
• Understand payment setup and contracts in the API Reference

Additional Resources

• Frequently Asked Questions
• API Changelog
• Contact Developer Support

Testing Your Integration

Use the development environment to test your integration thoroughly before going live. Make sure to:

• Test all error scenarios
• Verify data validation
• Test with various postcodes and addresses
• Ensure proper error handling