Quote Management (Ethernet)

This guide walks you through the steps to generate a synchronous quote for Wholesale Ethernet products using the REST POST method.

Before structuring the specific product payloads for your E-LAN, E-Line, or Ethernet Internet quotes, you must understand the common prerequisites, header requirements, and how to interpret the standardized pricing response.

  While the tutorials use a NAD Key (NadKeySite) for simplicity, the API supports various identifiers including Postcodes and UPRNs. Before building your integration, please review the Key concepts guide. This resource provides a full Site compatibility matrix, along with essential details on pricing, Sandbox testing, and request batching best practices to avoid rate limits.

 Generating a quote is optional. The generated Quote ID cannot be used for product ordering. The prices obtained through the Quote Management API are indicative, not firm prices.

 

---

Step 1: Complete prerequisites

Before generating any quote, ensure you have the following:

1. A valid Access Token. See the Authentication docs.
    
2. Your valid location data:
   • A UK postcode is enough for an indicative quote.
   • You can also use yourOpenreach Address ID (NAD Key): Follow the Identifying and validating installation addresses tutorial to retrieve the Address ID.

 

---

Step 2: Construct the request headers

Every POST request to the quoting endpoint requires standard mandatory HTTP headers:

 

---

Step 3: Construct the payload

Your payload must always start with the root attributes (like externalId and expectedFulfillmentStartDate), followed by a quoteItem array that acts as the top-level "envelope" for your quote

Inside the envelope, products are assembled using up to three core components:

 

Connectivity logic

How you arrange the quoteItem envelopes depends on your product's connectivity model

Flat structure (E-LAN / Ethernet Internet)

• Logic: Sites connect to a shared "cloud" or the public internet. Because all sites are effectively the same, there are no A-Ends or B-Ends, and no reference to an existing A-End.
• Structure: These products use a single, flat quoteItem per site containing the physical access and virtual path as siblings.

 

Nested structure (E-Line Point-to-Point / Hub-and-Spoke)

• Logic: Based on the notion of an A-End (hub) and a B-End (spoke) connected via a cloud. The A-End physical access acts as the root access product, and the B-Ends are quoted as children. The A-End can be new or pre-existing.
• Structure: E-Line requires a nested structure. You use a root quoteItem for the A-End's physical access. Underneath that, there is a nested quoteItem array for each B-End, which contains the B-End's physical access and the virtual path connecting it back to the A-End.

(For detailed visual breakdowns of these structures, please refer to the specific product tutorials for E-Line, E-LAN, and Ethernet Internet).

While Gold NAD Keys (starting with 'A') are preferred for accuracy, the API  supports another site subtypes.  See the list of site subtypes in the Site compatibility matrix.

 

---

Step 4: Send the request

Once your product-specific JSON payload is built, send it in the body of a POST request to the unified endpoint: /tmf-api/quoteManagement/v4/quote.

 

Important quoting rules

• Item limits: A single quote request can contain up to 100 quote items.
• No product mixing: You must quote products individually; you cannot mix different parent products within the same quote request.

 

---

Step 5: Interpret the response

The API operates synchronously and will return a 201 Created status upon success.

Note on indicative pricing: All API-generated pricing and service availability information is indicative and non-binding; firm pricing is only provided at the order stage. Quoted prices may not include additional service-related fees, such as excess construction charges (ECCs).

When parsing the response, capture the following key elements:

1. The Quote ID

Locate the id field in the response; this unique UUID is your Quote ID. Quotes are retained and can be retrieved via a GET request for exactly 1 month from the date of creation.

 

View an example ID snippet

{
   "id": "15582451-1d1e-4049-89dd-797aca356e52",
    ...
}

 

2. Excess Construction Charges (ECCs)

Check the productInformation block for construction insights.

• Exchange details: Identifies the serving BT exchange.
• Indicative ECCs: If the tariff states "Unable to calculate ECC", the price is subject to a site survey for civil works (digging).

 

View technical warning snippet

"productInformation": {
   ...
  "indicativeECCs": {
     "circuitDeliveryCategory": "3",
    "tariff": "Unable to calculate ECC",
    "indicativeExtraECCs": "Unable to calculate ECC",
    "fibrePresent": "No",
    "tNodeCapacity": "No"
    },
  ...
}

 

3. Standard pricing array

The API automatically returns pricing for all available contract term options simultaneously in the productPrice array. Typically, you will see pricing for 1-year, 3-year, and 5-year terms.

• priceType: nonRecurring: Represents the one-off connection fee.
• priceType: recurring: Represents the ongoing annual rental fee.

 

View pricing response snippet (3-Year Example)

"productPrice": [
   ...
  {
    "name": "3 Year rental",
    "priceType": "recurring",
    "recurringChargePeriod": "year",
    "price": {
      "dutyFreeAmount": { "unit": "GBP", "value": 5431 }
      }
    }
  ...
]

 

4. Option B pricing

Certain products may return secondary pricing structures labelled as Option B. Option B allows customers to select a higher upfront connection charge in exchange for a correspondingly lower monthly rental fee across a specific term period.

 

View an example Option B response snippet

"productPrice": [
...
  {
    "name": "3 Year Option B connection",
    "priceType": "nonRecurring",
    "price": {
      "taxRate": 20,
      "dutyFreeAmount": {
        "unit": "GBP",
       "value": 0
      },
    "taxIncludedAmount": {
       "unit": "GBP",
      "value": 0
      }
    }
  },
   ...
]

 

---

Common API-specific errors & Troubleshooting

If the request is unsuccessful, the API will return a synchronous error response. For issues specific to this API, the service will return a 4xx status with a specific errorCode, which you can find in the table below.

For details on common HTTP, OAuth, and OpenID Connect error codes and their solutions, see the Troubleshooting guide.

API Gateway (APIGW) Exceptions

If an error occurs at the API Gateway level (before the request even reaches the underlying quoting system), the API will return specific headers detailing the gateway exception. You should log these headers for troubleshooting:

• APIGW-Exception: Carries the message of the exception.
• APIGW-Exception-Code: Carries the specific code of the exception.
• APIGW-Exception-System: Identifies the system from which the exception originated.

Note: These specific headers will only be sent for APIGW Errors. For details on common HTTP, OAuth, and OpenID Connect error codes and their broader solutions, please consult the core API integration documentation.

 

---

Next steps

You are ready to build your product-specific JSON payloads.

Choose the tutorial that matches your connectivity requirements:

• Quoting for dedicated Ethernet (E-Line): Learn how to construct the nested payloads required to connect physical sites together via virtual circuits in point-to-point or hub-and-spoke configurations.
• Quoting for Ethernet LAN (E-LAN): Discover how to generate a quote for any-to-any connectivity, allowing multiple sites to communicate within a private network mesh.
• Quoting for Ethernet Internet: Follow the steps to build a quote for this bundled service, which delivers a layer 3 connection directly to the internet.
• Managing and interpreting quotes: Learn how to retrieve quotes by Id, how list and search quotes, and how to interpret the response headers and quote states.