Frequently Asked Questions

Access tokens expire after 24 hours (86400 seconds). You should store the token and reuse it until expiration, then obtain a new one. Don't request a new token for every API call as this is inefficient and may trigger rate limiting.

When you receive a 401 Unauthorized response, it means your token has expired. Simply call the POST /Auth/token endpoint again with your client credentials to get a new token. Implement automatic retry logic to handle this seamlessly.

Store your client ID and secret securely using environment variables or a secure configuration management system. Never expose these credentials in client-side code, public repositories, or logs. Use different credentials for development and production environments.

We support all standard UK postcode formats:

• Standard format: "SW1P 2DX"
• Compact format: "SW1P2DX"
• Lowercase: "sw1p 2dx" (will be converted to uppercase)

The API will automatically normalize the postcode format before processing.

If no addresses are found for a postcode, the API will return an empty array. This could happen if:

• The postcode doesn't exist in our database
• No properties at that postcode are available for household bill quotes
• The postcode format is invalid

Always handle empty responses gracefully and provide appropriate feedback to users.

The AddressUid is a unique identifier for each address that you must use when creating quotes. It's required for:

• Creating new quotes
• Adding broadband products (broadband availability is address-specific)
• Ensuring accurate service delivery

Always use the AddressUid from the address lookup response - don't try to construct address objects manually.

Yes, quotes have an expiration date. When you call the total cost endpoint, check the QuotePricesUpdated property:

• true: Quote had expired, new prices were fetched and expiration extended
• false: Quote is still valid with original pricing

When prices are updated, the quote's expiration date is automatically extended.

The main package types available are:

• electricity: Electric supply packages
• gas: Gas supply packages
• broadband: Internet service packages (requires broadband availability check)

Each package type can have different tariffs and options. Check the API reference for specific package configurations.

Yes, you can add multiple tenants to a quote. The first tenant added is typically the lead tenant and has additional responsibilities:

• Setting contract start and end dates (if not set during quote creation)
• Primary contact for the account
• Responsible for payment setup

Costs are split equally among all tenants in the quote.

PSR (Priority Services Register) categories identify customers who may need additional support. Available categories include:

• Blind, Partially sighted, Hearing impairment
• Mental health, Dementia/Cognitive impairment
• Physical Impairment, Restricted hand movement
• Pensionable age, Families with young children
• And many more...

See the API reference for the complete list of PSR (Priority Services Register) categories.

Costs are calculated based on:

• Selected packages and their options
• Current market rates
• Contract duration

Total costs are split equally among all tenants in the quote. All prices are returned in pence (not pounds) and include weekly, monthly, and yearly breakdowns.

The payment setup process involves several steps:

1. Add personal information (PSR (Priority Services Register) details, contract dates)
2. Get payment schedules to see available options
3. Create a setup intent for payment processing
4. Customer accepts terms and conditions
5. Generate contract URLs for PCI (Pre-Contract Information) compliance

Each step must be completed in order, and the customer's payment status will change accordingly.

Broadband availability checking is a multi-step process:

1. Create a broadband availability request
2. Use the returned UID to run the availability check
3. Check for errors from TAL and Purecomms systems
4. If available, add broadband products to your quote
5. Get installation dates for the selected products

Broadband availability is address-specific and may take time to process.

Broadband availability checks can fail for various reasons:

• TAL Errors: Issues with the TAL (TA1) provider system for home telecom products
• Purecomms Errors: Problems with the Purecomms broadband database
• Address Issues: Invalid or unsupported address

Check the talErrors and purecommsErrors flags, along with their respective error message arrays, to understand what went wrong.

The most common API errors are:

• 401 Unauthorized: Invalid or expired access token
• 400 Bad Request: Invalid input data or missing required fields
• 404 Not Found: Resource doesn't exist (invalid ID)
• 422 Unprocessable Entity: Validation errors (invalid postcode, etc.)

Always check the error response body for detailed information about what went wrong.

Yes, the API implements rate limiting to ensure fair usage. If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement appropriate delays between requests and use exponential backoff for retries.

For integration support, you can:

• Email our developer support team at developers@the-bunch.co.uk
• Check the API Reference for detailed endpoint documentation
• Review the Getting Started guide for common integration patterns
• Check the Changelog for recent updates and changes

When contacting support, please include your client ID (not secret), error messages, and request/response examples.