API Reference
Complete documentation for The Bunch Partner API endpoints, parameters, and responses for household bill management.
Overview
Obtain an access token from Auth0 for API authentication. This endpoint requires your Auth0 client credentials and returns a JWT token that must be included in the Authorization header of all subsequent API requests.
Prerequisites
- Valid Auth0 client credentials (client_id and client_secret)
- Auth0 application configured with the correct audience
- Client credentials grant type enabled in Auth0
Flow
- Send POST request to Auth0 token endpoint with client credentials
- Auth0 validates credentials and returns access token
- Use the access token in Authorization header for API requests
- Token expires after 24 hours and must be refreshed
Best Practices
⚠️ Important Security Notes
- Never expose your client secret in client-side code or public repositories
- Store credentials securely on your server using environment variables
- Always use HTTPS for all API communications
- Implement proper token refresh logic to avoid expired token errors
- Monitor token usage and implement rate limiting
Request Fields
Request Body
{
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"audience": "https://api.the-bunch.co.uk",
"grant_type": "client_credentials"
}
Response Fields
Response Body
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik1yNS1BVWliZkJpaTdOZDFqQmViYXhib1hXMCJ9...",
"token_type": "Bearer",
"expires_in": 86400
}
Example Code
curl -X POST 'https://your-auth0-domain.auth0.com/oauth/token' \
-H 'Content-Type: application/json' \
-d '{
"client_id": "your_client_id",
"client_secret": "your_client_secret",
"audience": "https://api.the-bunch.co.uk",
"grant_type": "client_credentials"
}'
const response = await fetch('https://your-auth0-domain.auth0.com/oauth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
client_id: 'your_client_id',
client_secret: 'your_client_secret',
audience: 'https://api.the-bunch.co.uk',
grant_type: 'client_credentials'
})
});
const data = await response.json();
const accessToken = data.access_token;
import requests
response = requests.post('https://your-auth0-domain.auth0.com/oauth/token', json={
'client_id': 'your_client_id',
'client_secret': 'your_client_secret',
'audience': 'https://api.the-bunch.co.uk',
'grant_type': 'client_credentials'
})
data = response.json()
access_token = data['access_token']
using System.Net.Http;
using System.Text;
using Newtonsoft.Json;
var client = new HttpClient();
var requestBody = new {
client_id = "your_client_id",
client_secret = "your_client_secret",
audience = "https://api.the-bunch.co.uk",
grant_type = "client_credentials"
};
var json = JsonConvert.SerializeObject(requestBody);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://your-auth0-domain.auth0.com/oauth/token", content);
var responseContent = await response.Content.ReadAsStringAsync();
var data = JsonConvert.DeserializeObject<dynamic>(responseContent);
var accessToken = data.access_token;
Error Responses
400 Bad Request
Invalid request parameters or missing required fields.
{
"error": "invalid_request",
"error_description": "Missing required parameter: client_id"
}
401 Unauthorized
Invalid client credentials.
{
"error": "invalid_client",
"error_description": "Invalid client credentials"
}
Overview
Retrieves a list of all available addresses at a given postcode. This endpoint is essential for the quote creation process as it provides the address information needed to create quotes.
Prerequisites
- Valid authentication token
- Valid UK postcode format
Flow
- Call this endpoint with a valid postcode
- Present the returned addresses to the customer
- Customer selects their address
- Use the selected address in quote creation
Best Practices
⚠️ Important Notes
- Use the
AddressUidfrom the response when creating quotes - Do not manually construct address objects - always use lookup results
- Address availability may change over time
- Some postcodes may not have any available addresses
Request Fields
Request Body
This endpoint uses query parameters, no request body required.
Response Fields
Response Body
[
{
"addressLine1": "Apartment 1",
"addressLine2": "Chimes Apartments 99-105 Horseferry Road",
"city": "London",
"country": "United Kingdom",
"county": "",
"postCode": "SW1P 2DX",
"uprn": "100023123456",
"mpan": null,
"mprn": null,
"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",
"mpan": null,
"mprn": null,
"addressUid": "45n6cc99-63a7-4639-aa4b-bc06988d4388"
}
]
Example Code
curl -X GET "https://api.the-bunch.co.uk/partner-api/Addresses/lookup?postcode=SW1P%202DX" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json"
const response = await fetch('https://api.the-bunch.co.uk/partner-api/Addresses/lookup?postcode=SW1P%202DX', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
});
const addresses = await response.json();
console.log(addresses);
import requests
url = "https://api.the-bunch.co.uk/partner-api/Addresses/lookup"
params = {"postcode": "SW1P 2DX"}
headers = {
"Authorization": "Bearer YOUR_ACCESS_TOKEN",
"Content-Type": "application/json"
}
response = requests.get(url, params=params, headers=headers)
addresses = response.json()
print(addresses)
using System;
using System.Net.Http;
using System.Threading.Tasks;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
client.DefaultRequestHeaders.Add("Content-Type", "application/json");
var response = await client.GetAsync("https://api.the-bunch.co.uk/partner-api/Addresses/lookup?postcode=SW1P%202DX");
var addresses = await response.Content.ReadAsStringAsync();
Console.WriteLine(addresses);
Overview
Retrieves a list of available quoting tool versions that can be used when creating quotes. This endpoint is optional if you already know which version to use.
Prerequisites
- Valid authentication token
Version Selection Flow
- Fetch: Call this endpoint to get available versions
- Select: Choose the appropriate version (usually the default)
- Use: Include the version ID when creating quotes
Best Practices
⚠️ Important Notes
- Always use the latest stable version unless you have specific requirements
- Cache version information to reduce API calls
- Handle version changes gracefully in your application
Request Fields
No request parameters required for this endpoint.
Request Body
No request body required for this GET endpoint.
Response Fields
Response Body
{
"versions": [
{
"id": "v1.0",
"name": "Standard Quoting Tool",
"isDefault": true
},
{
"id": "v1.1",
"name": "Enhanced Quoting Tool",
"isDefault": false
}
]
}
Example Code
curl -X GET "https://api.the-bunch.co.uk/partner-api/Quotes/quoting-tool-versions" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json"
const response = await fetch('https://api.the-bunch.co.uk/partner-api/Quotes/quoting-tool-versions', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
});
const versions = await response.json();
console.log(versions);
import requests
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
response = requests.get('https://api.the-bunch.co.uk/partner-api/Quotes/quoting-tool-versions', headers=headers)
versions = response.json()
print(versions)
using System.Net.Http;
using System.Text.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
client.DefaultRequestHeaders.Add("Content-Type", "application/json");
var response = await client.GetAsync("https://api.the-bunch.co.uk/partner-api/Quotes/quoting-tool-versions");
var versions = await response.Content.ReadAsStringAsync();
Console.WriteLine(versions);
Overview
Creates a new quote for household bill services at a specific address. This is the first step in the quote creation process.
💡 Quick Start
Provide an address UID from the address lookup endpoint to create a new quote. The quote will be created in draft status with available packages.
Prerequisites
- Valid authentication token
- Valid address UID from address lookup
Quote Creation Flow
- Lookup: Get address UID from address lookup
- Create: Call this endpoint to create the quote
- Configure: Add packages, tenants, and broadband products
- Finalize: Complete the quote setup
Best Practices
⚠️ Important Notes
- Always validate address UID before creating quotes
- Handle quote creation failures gracefully
- Implement proper error handling for invalid addresses
- Consider rate limiting for quote creation requests
Request Fields
Request Body
{
"addressUid": "addr_123456789",
"quotingToolVersionId": "v1.0"
}
Response Fields
Response Body
{
"quoteId": "quote_987654321",
"status": "draft",
"address": {
"addressUid": "addr_123456789",
"addressLine1": "123 Main Street",
"city": "London",
"postCode": "SW1A 1AA"
},
"availablePackages": [
{
"packageId": "pkg_energy",
"name": "Energy Package",
"description": "Gas and electricity services"
}
]
}
Example Code
curl -X POST "https://api.the-bunch.co.uk/partner-api/Quotes" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"addressUid": "addr_123456789",
"quotingToolVersionId": "v1.0"
}'
const response = await fetch('https://api.the-bunch.co.uk/partner-api/Quotes', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
addressUid: 'addr_123456789',
quotingToolVersionId: 'v1.0'
})
});
const quote = await response.json();
console.log(quote);
import requests
import json
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
data = {
'addressUid': 'addr_123456789',
'quotingToolVersionId': 'v1.0'
}
response = requests.post('https://api.the-bunch.co.uk/partner-api/Quotes',
headers=headers,
data=json.dumps(data))
quote = response.json()
print(quote)
using System.Net.Http;
using System.Text;
using System.Text.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var data = new {
addressUid = "addr_123456789",
quotingToolVersionId = "v1.0"
};
var json = JsonSerializer.Serialize(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.the-bunch.co.uk/partner-api/Quotes", content);
var quote = await response.Content.ReadAsStringAsync();
Console.WriteLine(quote);
Overview
Retrieve a specific quote with all tenants and available products. Use this to check quote status and tenant progress.
💡 Quick Start
Provide a quote ID to retrieve complete quote details including all tenants, packages, and available products.
Prerequisites
- Valid authentication token
- Valid quote ID
Quote Retrieval Flow
- Identify: Use the quote ID from quote creation
- Retrieve: Call this endpoint to get quote details
- Process: Handle the returned quote data
- Display: Show quote information to users
Best Practices
⚠️ Important Notes
- Validate quote ID format before making requests
- Handle quote not found errors gracefully
- Implement proper access controls for quote data
- Cache quote data appropriately to reduce API calls
Request Fields
Request Body
No request body required for this GET endpoint.
Response Fields
Response Body
{
"quoteId": "quote_987654321",
"status": "draft",
"address": {
"addressUid": "addr_123456789",
"addressLine1": "123 Main Street",
"city": "London",
"postCode": "SW1A 1AA"
},
"tenants": [
{
"tenantId": "tenant_001",
"name": "John Doe",
"email": "john@example.com",
"status": "active"
}
],
"packages": [
{
"packageId": "pkg_energy",
"name": "Energy Package",
"status": "available"
}
]
}
Example Code
curl -X GET "https://api.the-bunch.co.uk/partner-api/Quotes/quote_987654321" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json"
const quoteId = 'quote_987654321';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Quotes/${quoteId}`, {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
});
const quote = await response.json();
console.log(quote);
import requests
quote_id = 'quote_987654321'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
response = requests.get(f'https://api.the-bunch.co.uk/partner-api/Quotes/{quote_id}', headers=headers)
quote = response.json()
print(quote)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
client.DefaultRequestHeaders.Add("Content-Type", "application/json");
var quoteId = "quote_987654321";
var response = await client.GetAsync($"https://api.the-bunch.co.uk/partner-api/Quotes/{quoteId}");
var quote = await response.Content.ReadAsStringAsync();
Console.WriteLine(quote);
Overview
Add selected packages to an existing quote. Use package IDs from the quote response to specify which services to include.
Prerequisites
- Valid authentication token
- Valid quote ID
- Quote must be in "Draft" or "PackagesSelected" state
- Quote must not be expired
Package Selection Flow
- Retrieve: Get quote details to see available packages
- Select: Choose packages to add to the quote
- Add: Call this endpoint with selected package IDs
- Verify: Check updated quote with selected packages
Best Practices
⚠️ Important Notes
- Validate package IDs before making requests
- Handle package selection failures gracefully
- Implement proper error handling for invalid packages
- Consider rate limiting for package selection requests
Request Fields
Request Body
{
"packageIds": ["pkg_energy", "pkg_broadband"]
}
Response Fields
Response Body
{
"quoteId": "quote_987654321",
"status": "PackagesSelected",
"selectedPackages": [
{
"packageId": "pkg_energy",
"name": "Energy Package",
"status": "selected"
},
{
"packageId": "pkg_broadband",
"name": "Broadband Package",
"status": "selected"
}
]
}
Example Code
curl -X POST "https://api.the-bunch.co.uk/partner-api/Quotes/quote_987654321/add-packages" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"packageIds": ["pkg_energy", "pkg_broadband"]
}'
const quoteId = 'quote_987654321';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Quotes/${quoteId}/add-packages`, {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
packageIds: ['pkg_energy', 'pkg_broadband']
})
});
const result = await response.json();
console.log(result);
import requests
import json
quote_id = 'quote_987654321'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
data = {
'packageIds': ['pkg_energy', 'pkg_broadband']
}
response = requests.post(f'https://api.the-bunch.co.uk/partner-api/Quotes/{quote_id}/add-packages',
headers=headers,
data=json.dumps(data))
result = response.json()
print(result)
using System.Net.Http;
using System.Text;
using System.Text.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var quoteId = "quote_987654321";
var data = new {
packageIds = new[] { "pkg_energy", "pkg_broadband" }
};
var json = JsonSerializer.Serialize(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync($"https://api.the-bunch.co.uk/partner-api/Quotes/{quoteId}/add-packages", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Add tenant information to an existing quote. This can be done before or after adding packages.
Prerequisites
- Valid authentication token
- Valid quote ID
- Quote must be in "Draft" or "PackagesSelected" state
- Must be completed before payment schedules can be generated for each tenant
- Quote must not be expired
Tenant Addition Flow
- Prepare: Gather tenant information (name, email, contact details)
- Add: Call this endpoint with tenant data
- Verify: Check updated quote with tenant information
- Continue: Proceed with package selection or broadband addition
Best Practices
⚠️ Important Notes
- Validate tenant email addresses before submission
- Ensure all required tenant information is provided
- Handle tenant addition failures gracefully
- Consider data privacy requirements for tenant information
Request Fields
Request Body
{
"tenants": [
{
"name": "John Doe",
"email": "john.doe@example.com"
},
{
"name": "Jane Smith",
"email": "jane.smith@example.com"
}
]
}
Response Fields
Response Body
{
"quoteId": "quote_987654321",
"status": "TenantsAdded",
"tenants": [
{
"tenantId": "tenant_001",
"name": "John Doe",
"email": "john.doe@example.com",
"status": "active"
},
{
"tenantId": "tenant_002",
"name": "Jane Smith",
"email": "jane.smith@example.com",
"status": "active"
}
]
}
Example Code
curl -X POST "https://api.the-bunch.co.uk/partner-api/Quotes/quote_987654321/add-tenants" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tenants": [
{
"name": "John Doe",
"email": "john.doe@example.com"
},
{
"name": "Jane Smith",
"email": "jane.smith@example.com"
}
]
}'
const quoteId = 'quote_987654321';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Quotes/${quoteId}/add-tenants`, {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
tenants: [
{
name: 'John Doe',
email: 'john.doe@example.com'
},
{
name: 'Jane Smith',
email: 'jane.smith@example.com'
}
]
})
});
const result = await response.json();
console.log(result);
import requests
import json
quote_id = 'quote_987654321'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
data = {
'tenants': [
{
'name': 'John Doe',
'email': 'john.doe@example.com'
},
{
'name': 'Jane Smith',
'email': 'jane.smith@example.com'
}
]
}
response = requests.post(f'https://api.the-bunch.co.uk/partner-api/Quotes/{quote_id}/add-tenants',
headers=headers,
data=json.dumps(data))
result = response.json()
print(result)
using System.Net.Http;
using System.Text;
using System.Text.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var quoteId = "quote_987654321";
var data = new {
tenants = new[] {
new { name = "John Doe", email = "john.doe@example.com" },
new { name = "Jane Smith", email = "jane.smith@example.com" }
}
};
var json = JsonSerializer.Serialize(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync($"https://api.the-bunch.co.uk/partner-api/Quotes/{quoteId}/add-tenants", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Update or replace packages on an existing quote. Products can be replaced provided no customer has started payment or been completed yet.
Prerequisites
- Valid authentication token
- Valid quote ID
- Quote must be in "Draft" or "PackagesSelected" state
- No customer payments must have been started
Package Update Flow
- Verify: Check quote status and payment state
- Select: Choose new packages to replace existing ones
- Update: Call this endpoint with new package IDs
- Confirm: Verify the updated quote details
Best Practices
⚠️ Important Notes
- Only update packages before customer payment begins
- Validate new package IDs before making requests
- Handle package update failures gracefully
- Consider impact on existing tenant configurations
Request Fields
Request Body
{
"packageIds": ["pkg_energy_v2", "pkg_broadband_premium"]
}
Response Fields
Response Body
{
"quoteId": "quote_987654321",
"status": "PackagesUpdated",
"updatedPackages": [
{
"packageId": "pkg_energy_v2",
"name": "Energy Package V2",
"status": "selected"
},
{
"packageId": "pkg_broadband_premium",
"name": "Premium Broadband Package",
"status": "selected"
}
]
}
Example Code
curl -X POST "https://api.the-bunch.co.uk/partner-api/Quotes/quote_987654321/update-packages" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"packageIds": ["pkg_energy_v2", "pkg_broadband_premium"]
}'
const quoteId = 'quote_987654321';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Quotes/${quoteId}/update-packages`, {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
packageIds: ['pkg_energy_v2', 'pkg_broadband_premium']
})
});
const result = await response.json();
console.log(result);
import requests
import json
quote_id = 'quote_987654321'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
data = {
'packageIds': ['pkg_energy_v2', 'pkg_broadband_premium']
}
response = requests.post(f'https://api.the-bunch.co.uk/partner-api/Quotes/{quote_id}/update-packages',
headers=headers,
data=json.dumps(data))
result = response.json()
print(result)
using System.Net.Http;
using System.Text;
using System.Text.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var quoteId = "quote_987654321";
var data = new {
packageIds = new[] { "pkg_energy_v2", "pkg_broadband_premium" }
};
var json = JsonSerializer.Serialize(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync($"https://api.the-bunch.co.uk/partner-api/Quotes/{quoteId}/update-packages", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Add broadband products to an existing quote after checking availability.
Prerequisites
- Valid authentication token
- Valid quote ID
- Broadband availability must be checked first
- Products must be available at the address
Broadband Addition Flow
- Check: Verify broadband availability at the address
- Select: Choose available broadband products
- Add: Call this endpoint with selected products
- Schedule: Get installation dates for the products
Best Practices
⚠️ Important Notes
- Always check broadband availability before adding products
- Validate product availability at the specific address
- Handle broadband addition failures gracefully
- Consider installation date availability
Request Fields
Request Body
{
"broadbandProducts": ["bb_fiber_100", "bb_fiber_500"]
}
Response Fields
Response Body
{
"quoteId": "quote_987654321",
"status": "BroadbandAdded",
"broadbandProducts": [
{
"productId": "bb_fiber_100",
"name": "Fiber 100 Mbps",
"status": "added"
},
{
"productId": "bb_fiber_500",
"name": "Fiber 500 Mbps",
"status": "added"
}
]
}
Example Code
curl -X POST "https://api.the-bunch.co.uk/partner-api/Quotes/quote_987654321/add-broadband-products" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"broadbandProducts": ["bb_fiber_100", "bb_fiber_500"]
}'
const quoteId = 'quote_987654321';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Quotes/${quoteId}/add-broadband-products`, {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
broadbandProducts: ['bb_fiber_100', 'bb_fiber_500']
})
});
const result = await response.json();
console.log(result);
import requests
import json
quote_id = 'quote_987654321'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
data = {
'broadbandProducts': ['bb_fiber_100', 'bb_fiber_500']
}
response = requests.post(f'https://api.the-bunch.co.uk/partner-api/Quotes/{quote_id}/add-broadband-products',
headers=headers,
data=json.dumps(data))
result = response.json()
print(result)
using System.Net.Http;
using System.Text;
using System.Text.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var quoteId = "quote_987654321";
var data = new {
broadbandProducts = new[] { "bb_fiber_100", "bb_fiber_500" }
};
var json = JsonSerializer.Serialize(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync($"https://api.the-bunch.co.uk/partner-api/Quotes/{quoteId}/add-broadband-products", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Retrieve available installation dates for broadband products in the quote.
Prerequisites
- Valid authentication token
- Valid quote ID
- Broadband products must be added to the quote
Installation Date Flow
- Add: Ensure broadband products are added to quote
- Request: Call this endpoint to get available dates
- Select: Choose preferred installation date
- Schedule: Confirm installation appointment
Best Practices
⚠️ Important Notes
- Check installation dates before finalizing quote
- Consider customer availability when selecting dates
- Handle date conflicts gracefully
- Provide alternative dates if preferred unavailable
Request Fields
Request Body
No request body required for GET request
Response Fields
Response Body
{
"quoteId": "quote_987654321",
"availableDates": [
"2025-01-15",
"2025-01-16",
"2025-01-17",
"2025-01-20",
"2025-01-21"
],
"earliestDate": "2025-01-15"
}
Example Code
curl -X GET "https://api.the-bunch.co.uk/partner-api/Quotes/quote_987654321/get-bb-install-dates" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const quoteId = 'quote_987654321';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Quotes/${quoteId}/get-bb-install-dates`, {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
});
const result = await response.json();
console.log(result);
import requests
quote_id = 'quote_987654321'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
response = requests.get(f'https://api.the-bunch.co.uk/partner-api/Quotes/{quote_id}/get-bb-install-dates',
headers=headers)
result = response.json()
print(result)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var quoteId = "quote_987654321";
var response = await client.GetAsync($"https://api.the-bunch.co.uk/partner-api/Quotes/{quoteId}/get-bb-install-dates");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Retrieve the total cost breakdown for a quote, showing how costs are split among all tenants.
Prerequisites
- Valid authentication token
- Valid quote ID
- Quote must have packages and tenants added
Cost Calculation Flow
- Add: Ensure packages and tenants are added to quote
- Calculate: System calculates total costs and splits
- Retrieve: Call this endpoint to get cost breakdown
- Display: Show costs to customer for approval
Best Practices
⚠️ Important Notes
- Always show cost breakdown before finalizing quote
- Handle cost calculation errors gracefully
- Validate cost splits are fair and accurate
- Consider tax implications in cost display
Request Fields
Request Body
No request body required for GET request
Response Fields
Response Body
{
"quoteId": "quote_987654321",
"totalCost": 1250.00,
"monthlyCost": 104.17,
"costBreakdown": [
{
"tenantId": "tenant_001",
"tenantName": "John Smith",
"monthlyCost": 52.08,
"setupCost": 125.00,
"products": ["energy_basic", "broadband_standard"]
},
{
"tenantId": "tenant_002",
"tenantName": "Jane Doe",
"monthlyCost": 52.09,
"setupCost": 125.00,
"products": ["energy_basic", "broadband_standard"]
}
]
}
Example Code
curl -X GET "https://api.the-bunch.co.uk/partner-api/Quotes/quote_987654321/total-cost" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const quoteId = 'quote_987654321';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Quotes/${quoteId}/total-cost`, {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
});
const result = await response.json();
console.log(result);
import requests
quote_id = 'quote_987654321'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
response = requests.get(f'https://api.the-bunch.co.uk/partner-api/Quotes/{quote_id}/total-cost',
headers=headers)
result = response.json()
print(result)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var quoteId = "quote_987654321";
var response = await client.GetAsync($"https://api.the-bunch.co.uk/partner-api/Quotes/{quoteId}/total-cost");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Check broadband availability for a specific address using the broadband availability request UID.
Prerequisites
- Valid authentication token
- Valid broadband availability request UID
- Address must be validated
Broadband Check Flow
- Validate: Ensure address is valid and UID exists
- Check: System checks broadband availability
- Retrieve: Call this endpoint to get results
- Display: Show available broadband options
Best Practices
⚠️ Important Notes
- Always validate UID before making requests
- Handle availability check failures gracefully
- Cache results to avoid repeated checks
- Provide fallback options if no broadband available
Request Fields
Request Body
No request body required for GET request
Response Fields
Response Body
{
"uid": "bb_check_123456789",
"available": true,
"maxSpeed": 1000,
"products": [
{
"productId": "bb_fiber_100",
"name": "Fiber 100 Mbps",
"speed": 100,
"price": 25.00
},
{
"productId": "bb_fiber_500",
"name": "Fiber 500 Mbps",
"speed": 500,
"price": 45.00
},
{
"productId": "bb_fiber_1000",
"name": "Fiber 1000 Mbps",
"speed": 1000,
"price": 65.00
}
]
}
Example Code
curl -X GET "https://api.the-bunch.co.uk/partner-api/Quotes/run-broadband-availability-check/bb_check_123456789" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const uid = 'bb_check_123456789';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Quotes/run-broadband-availability-check/${uid}`, {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
});
const result = await response.json();
console.log(result);
import requests
uid = 'bb_check_123456789'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
response = requests.get(f'https://api.the-bunch.co.uk/partner-api/Quotes/run-broadband-availability-check/{uid}',
headers=headers)
result = response.json()
print(result)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var uid = "bb_check_123456789";
var response = await client.GetAsync($"https://api.the-bunch.co.uk/partner-api/Quotes/run-broadband-availability-check/{uid}");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Retrieve customer details and current status information including personal details, payment status, and service subscriptions.
Prerequisites
- Valid authentication token
- Valid customer ID
Customer Retrieval Flow
- Identify: Use the customer ID from tenant creation
- Retrieve: Call this endpoint to get customer details
- Process: Handle the returned customer data
- Display: Show customer information to users
Best Practices
⚠️ Important Notes
- Always validate customer ID before making requests
- Handle customer not found errors gracefully
- Cache customer data to reduce API calls
- Respect customer privacy and data protection
Request Fields
Request Body
No request body required for GET request
Response Fields
Response Body
{
"customerId": "customer_123456789",
"status": "active",
"personalDetails": {
"firstName": "John",
"lastName": "Smith",
"email": "john.smith@example.com",
"phone": "+44 7123 456789"
},
"paymentStatus": "paid",
"services": [
{
"serviceId": "energy_basic",
"name": "Basic Energy Package",
"status": "active",
"startDate": "2025-01-01"
},
{
"serviceId": "broadband_standard",
"name": "Standard Broadband",
"status": "active",
"startDate": "2025-01-01"
}
]
}
Example Code
curl -X GET "https://api.the-bunch.co.uk/partner-api/Customers/customer_123456789" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const customerId = 'customer_123456789';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Customers/${customerId}`, {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
});
const result = await response.json();
console.log(result);
import requests
customer_id = 'customer_123456789'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
response = requests.get(f'https://api.the-bunch.co.uk/partner-api/Customers/{customer_id}',
headers=headers)
result = response.json()
print(result)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var customerId = "customer_123456789";
var response = await client.GetAsync($"https://api.the-bunch.co.uk/partner-api/Customers/{customerId}");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Returns the packages selected and total cost of the quote as split for the specific customer.
Prerequisites
- Valid authentication token
- Valid customer/tenant ID
- Customer must have packages assigned
Cost Retrieval Flow
- Identify: Use the customer/tenant ID
- Calculate: System calculates cost split for this customer
- Retrieve: Call this endpoint to get cost breakdown
- Display: Show customer-specific costs
Best Practices
⚠️ Important Notes
- Always validate customer ID before making requests
- Handle cost calculation errors gracefully
- Ensure cost splits are fair and accurate
- Consider tax implications in cost display
Request Fields
Request Body
No request body required for GET request
Response Fields
Response Body
{
"customerId": "customer_123456789",
"totalCost": 625.00,
"monthlyCost": 52.08,
"packages": [
{
"packageId": "energy_basic",
"name": "Basic Energy Package",
"monthlyCost": 30.00,
"setupCost": 75.00
},
{
"packageId": "broadband_standard",
"name": "Standard Broadband",
"monthlyCost": 22.08,
"setupCost": 50.00
}
]
}
Example Code
curl -X GET "https://api.the-bunch.co.uk/partner-api/Customers/customer_123456789/total-cost" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const customerId = 'customer_123456789';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Customers/${customerId}/total-cost`, {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
});
const result = await response.json();
console.log(result);
import requests
customer_id = 'customer_123456789'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
response = requests.get(f'https://api.the-bunch.co.uk/partner-api/Customers/{customer_id}/total-cost',
headers=headers)
result = response.json()
print(result)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var customerId = "customer_123456789";
var response = await client.GetAsync($"https://api.the-bunch.co.uk/partner-api/Customers/{customerId}/total-cost");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Add complete personal information for a tenant including PSR (Priority Services Register) details and contract dates. This must be submitted for every tenant, even if no PSR information is required.
Prerequisites
- Valid authentication token
- Valid customer ID
- Required before payment intent creation
- Customer must be over 18 years of age
- If PSR (Priority Services Register) information is specified, authorised contact details are required
Personal Information Flow
- Prepare: Gather all required personal information
- Validate: Ensure all required fields are complete
- Submit: Call this endpoint with personal details
- Verify: Confirm information was accepted
Best Practices
⚠️ Important Notes
- Always validate personal information before submission
- Handle PSR (Priority Services Register) information securely and in compliance with regulations
- Implement proper data validation for all fields
- Protect sensitive personal data in transit and at rest
Request Fields
Request Body
{
"firstName": "John",
"lastName": "Smith",
"email": "john.smith@example.com",
"phone": "+44 7123 456789",
"dateOfBirth": "1990-05-15",
"psrDetails": {
"hasPsr": false
}
}
Response Fields
Response Body
{
"customerId": "customer_123456789",
"status": "PersonalInfoComplete",
"personalInfoComplete": true
}
Example Code
curl -X POST "https://api.the-bunch.co.uk/partner-api/Customers/customer_123456789/finalise-personal-information" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"firstName": "John",
"lastName": "Smith",
"email": "john.smith@example.com",
"phone": "+44 7123 456789",
"dateOfBirth": "1990-05-15",
"psrDetails": {
"hasPsr": false
}
}'
const customerId = 'customer_123456789';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Customers/${customerId}/finalise-personal-information`, {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
firstName: 'John',
lastName: 'Smith',
email: 'john.smith@example.com',
phone: '+44 7123 456789',
dateOfBirth: '1990-05-15',
psrDetails: {
hasPsr: false
}
})
});
const result = await response.json();
console.log(result);
import requests
import json
customer_id = 'customer_123456789'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
data = {
'firstName': 'John',
'lastName': 'Smith',
'email': 'john.smith@example.com',
'phone': '+44 7123 456789',
'dateOfBirth': '1990-05-15',
'psrDetails': {
'hasPsr': False
}
}
response = requests.post(f'https://api.the-bunch.co.uk/partner-api/Customers/{customer_id}/finalise-personal-information',
headers=headers,
data=json.dumps(data))
result = response.json()
print(result)
using System.Net.Http;
using System.Text;
using System.Text.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var customerId = "customer_123456789";
var data = new {
firstName = "John",
lastName = "Smith",
email = "john.smith@example.com",
phone = "+44 7123 456789",
dateOfBirth = "1990-05-15",
psrDetails = new {
hasPsr = false
}
};
var json = JsonSerializer.Serialize(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync($"https://api.the-bunch.co.uk/partner-api/Customers/{customerId}/finalise-personal-information", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Retrieve payment schedules amounts for a tenant. Payment amounts may differ between primary and secondary tenants due to pro rata monthly billing.
Prerequisites
- Valid authentication token
- Valid customer ID
- Quote must be in "PackagesSelected" state
- Customer must have personal information completed
Payment Schedule Flow
- Complete: Ensure personal information is finalized
- Calculate: System calculates payment schedules
- Retrieve: Call this endpoint to get payment details
- Display: Show payment schedule to customer
Best Practices
⚠️ Important Notes
- Always validate customer status before retrieving schedules
- Handle pro rata billing calculations correctly
- Display payment amounts clearly to customers
- Consider different billing cycles for tenants
Request Fields
Request Body
No request body required for GET request
Response Fields
Response Body
{
"customerId": "customer_123456789",
"paymentSchedule": {
"monthlyAmount": 52.08,
"setupAmount": 125.00,
"billingCycle": "monthly",
"nextPaymentDate": "2025-02-01"
},
"monthlyAmount": 52.08,
"setupAmount": 125.00
}
Example Code
curl -X GET "https://api.the-bunch.co.uk/partner-api/Customers/customer_123456789/payment-schedules" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const customerId = 'customer_123456789';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Customers/${customerId}/payment-schedules`, {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
});
const result = await response.json();
console.log(result);
import requests
customer_id = 'customer_123456789'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
response = requests.get(f'https://api.the-bunch.co.uk/partner-api/Customers/{customer_id}/payment-schedules',
headers=headers)
result = response.json()
print(result)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var customerId = "customer_123456789";
var response = await client.GetAsync($"https://api.the-bunch.co.uk/partner-api/Customers/{customerId}/payment-schedules");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Create a Stripe setup intent for payment method collection. This creates the customer in Stripe and associates their payment card to the account only. Payments will be collected shortly after.
Prerequisites
- Valid authentication token
- Valid customer ID
- Quote must be in "PackagesSelected" state
- Customer must have personal information completed
- Customer should be shown their payment schedule before this setup intent is generated
Setup Intent Flow
- Prepare: Ensure customer has completed personal information
- Create: Call this endpoint to create Stripe setup intent
- Collect: Use Stripe Elements to collect payment details
- Confirm: Complete setup intent with Stripe
Best Practices
⚠️ Important Notes
- Always use Stripe Elements library for secure payment collection
- Handle setup intent failures gracefully
- Validate customer status before creating setup intent
- Ensure PCI (Payment Card Industry) compliance when handling payment data
Request Fields
Request Body
No request body required for this endpoint
Response Fields
Response Body
{
"customerId": "customer_123456789",
"setupIntentId": "seti_1234567890",
"clientSecret": "seti_1234567890_secret_abcdef",
"stripeCustomerId": "cus_1234567890"
}
Example Code
curl -X POST "https://api.the-bunch.co.uk/partner-api/Customers/customer_123456789/create-setup-intent" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const customerId = 'customer_123456789';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Customers/${customerId}/create-setup-intent`, {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
});
const result = await response.json();
console.log(result);
// Use with Stripe Elements
const stripe = Stripe('pk_test_...');
const elements = stripe.elements();
const cardElement = elements.create('card');
cardElement.mount('#card-element');
import requests
customer_id = 'customer_123456789'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
response = requests.post(f'https://api.the-bunch.co.uk/partner-api/Customers/{customer_id}/create-setup-intent',
headers=headers)
result = response.json()
print(result)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var customerId = "customer_123456789";
var response = await client.PostAsync($"https://api.the-bunch.co.uk/partner-api/Customers/{customerId}/create-setup-intent", null);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Complete the tenant onboarding by accepting terms and conditions. This will finalise the journey for this customer.
Prerequisites
- Valid authentication token
- Valid customer ID
- Payment details must be provided via setup intent
- Setup intent must have had a successful response
Terms Acceptance Flow
- Complete: Ensure payment setup is successful
- Present: Show terms and conditions to customer
- Accept: Call this endpoint when customer accepts
- Finalize: Complete customer onboarding
Best Practices
⚠️ Important Notes
- Always ensure payment setup is complete before accepting terms
- Present terms clearly and ensure customer understands
- Handle terms acceptance failures gracefully
- Maintain audit trail of terms acceptance
Request Fields
Request Body
No request body required for this endpoint
Response Fields
Response Body
{
"customerId": "customer_123456789",
"status": "OnboardingComplete",
"onboardingComplete": true,
"termsAcceptedAt": "2025-01-15T10:30:00Z"
}
Example Code
curl -X POST "https://api.the-bunch.co.uk/partner-api/Customers/customer_123456789/accept-terms" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const customerId = 'customer_123456789';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Customers/${customerId}/accept-terms`, {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
});
const result = await response.json();
console.log(result);
import requests
customer_id = 'customer_123456789'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
response = requests.post(f'https://api.the-bunch.co.uk/partner-api/Customers/{customer_id}/accept-terms',
headers=headers)
result = response.json()
print(result)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var customerId = "customer_123456789";
var response = await client.PostAsync($"https://api.the-bunch.co.uk/partner-api/Customers/{customerId}/accept-terms", null);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Generate HTML contract URL for PCI (Pre-Contract Information) compliance purposes.
Prerequisites
- Valid authentication token
- Valid customer ID
- Customer must have completed onboarding
Contract URL Flow
- Complete: Ensure customer onboarding is finished
- Generate: Call this endpoint to create contract URL
- Access: Use the returned URL to access contract
- Comply: Ensure PCI (Pre-Contract Information) compliance requirements are met
Best Practices
⚠️ Important Notes
- Always validate customer status before generating URLs
- Handle URL generation failures gracefully
- Ensure URLs are accessible for PCI (Pre-Contract Information) compliance
- Maintain security when handling contract URLs
Request Fields
Request Body
No request body required for GET request
Response Fields
Response Body
{
"customerId": "customer_123456789",
"contractUrl": "https://contracts.the-bunch.co.uk/html/customer_123456789?token=abc123",
"expiresAt": "2025-02-15T10:30:00Z"
}
Example Code
curl -X GET "https://api.the-bunch.co.uk/partner-api/Customers/customer_123456789/pci-contract-url-html" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const customerId = 'customer_123456789';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Customers/${customerId}/pci-contract-url-html`, {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
});
const result = await response.json();
console.log(result);
import requests
customer_id = 'customer_123456789'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
response = requests.get(f'https://api.the-bunch.co.uk/partner-api/Customers/{customer_id}/pci-contract-url-html',
headers=headers)
result = response.json()
print(result)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var customerId = "customer_123456789";
var response = await client.GetAsync($"https://api.the-bunch.co.uk/partner-api/Customers/{customerId}/pci-contract-url-html");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Generate PDF contract URL for PCI (Pre-Contract Information) compliance purposes.
Prerequisites
- Valid authentication token
- Valid customer ID
- Customer must have completed onboarding
Contract URL Flow
- Complete: Ensure customer onboarding is finished
- Generate: Call this endpoint to create PDF contract URL
- Access: Use the returned URL to access PDF contract
- Comply: Ensure PCI (Pre-Contract Information) compliance requirements are met
Best Practices
⚠️ Important Notes
- Always validate customer status before generating URLs
- Handle URL generation failures gracefully
- Ensure PDF URLs are accessible for PCI (Pre-Contract Information) compliance
- Maintain security when handling contract URLs
Request Fields
Request Body
No request body required for GET request
Response Fields
Response Body
{
"customerId": "customer_123456789",
"contractUrl": "https://contracts.the-bunch.co.uk/pdf/customer_123456789?token=abc123",
"expiresAt": "2025-02-15T10:30:00Z"
}
Example Code
curl -X GET "https://api.the-bunch.co.uk/partner-api/Customers/customer_123456789/pci-contract-url-pdf" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const customerId = 'customer_123456789';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Customers/${customerId}/pci-contract-url-pdf`, {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
});
const result = await response.json();
console.log(result);
import requests
customer_id = 'customer_123456789'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
response = requests.get(f'https://api.the-bunch.co.uk/partner-api/Customers/{customer_id}/pci-contract-url-pdf',
headers=headers)
result = response.json()
print(result)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var customerId = "customer_123456789";
var response = await client.GetAsync($"https://api.the-bunch.co.uk/partner-api/Customers/{customerId}/pci-contract-url-pdf");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Create a webhook endpoint to receive notifications about quote and customer events such as payment updates, service changes, and status updates.
Prerequisites
- Valid authentication token
- Publicly accessible webhook URL
- HTTPS endpoint (required for security)
Webhook Setup Flow
- Prepare: Set up a webhook endpoint on your server
- Create: Call this endpoint to register your webhook
- Verify: Handle webhook verification requests
- Process: Handle incoming webhook events
Best Practices
⚠️ Important Notes
- Always use HTTPS for webhook endpoints
- Implement webhook signature verification
- Handle webhook failures gracefully with retries
- Implement idempotency for webhook processing
Request Fields
Request Body
{
"url": "https://your-domain.com/webhooks/bunch",
"events": [
"quote.status.changed",
"customer.payment.updated",
"customer.status.changed"
]
}
Response Fields
Response Body
{
"webhookId": "webhook_123456789",
"url": "https://your-domain.com/webhooks/bunch",
"events": [
"quote.status.changed",
"customer.payment.updated",
"customer.status.changed"
],
"status": "active"
}
Example Code
curl -X POST "https://api.the-bunch.co.uk/partner-api/Webhooks" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-domain.com/webhooks/bunch",
"events": [
"quote.status.changed",
"customer.payment.updated",
"customer.status.changed"
]
}'
const response = await fetch('https://api.the-bunch.co.uk/partner-api/Webhooks', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
},
body: JSON.stringify({
url: 'https://your-domain.com/webhooks/bunch',
events: [
'quote.status.changed',
'customer.payment.updated',
'customer.status.changed'
]
})
});
const result = await response.json();
console.log(result);
import requests
import json
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
'Content-Type': 'application/json'
}
data = {
'url': 'https://your-domain.com/webhooks/bunch',
'events': [
'quote.status.changed',
'customer.payment.updated',
'customer.status.changed'
]
}
response = requests.post('https://api.the-bunch.co.uk/partner-api/Webhooks',
headers=headers,
data=json.dumps(data))
result = response.json()
print(result)
using System.Net.Http;
using System.Text;
using System.Text.Json;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var data = new {
url = "https://your-domain.com/webhooks/bunch",
events = new[] {
"quote.status.changed",
"customer.payment.updated",
"customer.status.changed"
}
};
var json = JsonSerializer.Serialize(data);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync("https://api.the-bunch.co.uk/partner-api/Webhooks", content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
Overview
Retrieve details of a specific webhook endpoint.
Prerequisites
- Valid authentication token
- Valid webhook ID
Webhook Retrieval Flow
- Identify: Use the webhook ID from creation
- Retrieve: Call this endpoint to get webhook details
- Process: Handle the returned webhook information
- Display: Show webhook configuration to users
Best Practices
⚠️ Important Notes
- Always validate webhook ID before making requests
- Handle webhook not found errors gracefully
- Cache webhook data to reduce API calls
- Monitor webhook status and health
Request Fields
Request Body
No request body required for GET request
Response Fields
Response Body
{
"webhookId": "webhook_123456789",
"url": "https://your-domain.com/webhooks/bunch",
"events": [
"quote.status.changed",
"customer.payment.updated",
"customer.status.changed"
],
"status": "active",
"createdAt": "2025-01-15T10:30:00Z"
}
Example Code
curl -X GET "https://api.the-bunch.co.uk/partner-api/Webhooks/webhook_123456789" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const webhookId = 'webhook_123456789';
const response = await fetch(`https://api.the-bunch.co.uk/partner-api/Webhooks/${webhookId}`, {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
});
const result = await response.json();
console.log(result);
import requests
webhook_id = 'webhook_123456789'
headers = {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
}
response = requests.get(f'https://api.the-bunch.co.uk/partner-api/Webhooks/{webhook_id}',
headers=headers)
result = response.json()
print(result)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN");
var webhookId = "webhook_123456789";
var response = await client.GetAsync($"https://api.the-bunch.co.uk/partner-api/Webhooks/{webhookId}");
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);