api/v1/quotes/externalInitiates a quote request to retrieve available broadband or DIA product offerings based on location and product criteria. This is typically the first step in the service provisioning workflow.
The first step is to create a quote by providing the service location and product details. This API call returns available product offerings with pricing information that you can present to your customer.
What this step does: Submits location and product preferences to receive available broadband service options and pricing.
Why this step: You need to know what services are available at the customer’s location and their associated costs before creating an order.
Important: Save the quote_request_id from the response—you’ll need it to create the order in Step 3. Also save the formal_product_offering_id of the product your customer selects.
| Field | Type | Required | Description |
|---|---|---|---|
location | object | Yes | Location details for the service address |
product | object | Yes | Product configuration details |
account_macnum | string | No | Existing account MAC number. Exactly one of account_macnum or account_to_create must be provided. |
account_to_create | object | No | Account details for new account creation. Exactly one of account_macnum or account_to_create must be provided. |
| Field | Type | Required | Description |
|---|---|---|---|
street_address | string | Yes | Street address of the service location |
city | string | Yes | City name |
state | string | Yes | Two-letter state code (e.g., "CA", "NY") |
zip_code | string | Yes | 5-digit ZIP code |
unit_number | string | No | Unit or suite number, if applicable |
| Field | Type | Required | Description |
|---|---|---|---|
product_type | string | Yes | Product type: "Broadband" or "DIA" |
term | integer | Yes | Contract term in years. Valid values: 1, 2, or 3 |
bandwidth_mbps | integer | No | Desired bandwidth in Mbps. Required for DIA products. |
| Field | Type | Required | Description |
|---|---|---|---|
company_name | string | Yes | Company or organization name |
contact_email | string | Yes | Primary contact email address |
contact_phone | string | Yes | Primary contact phone number (E.164 format) |
Broadband: Quotes return immediately with complete product offerings and pricing. You can proceed directly to the Create Order step using the quote_request_id and selected formal_product_offering_id.
DIA: Quotes require asynchronous processing. The initial response includes a quote_request_id with status “pending”. You must poll the Get Quote Status endpoint until the status is “completed” before proceeding to Create Order.
quote_request_id: Unique identifier for this quote request. Required for subsequent operations including Create Order and Get Quote Status.formal_product_offering_id: Identifier for a specific product offering. Use this value when creating an order to select the desired product.status: Current status of the quote. Values: "pending", "completed", "expired", or "failed".expires_at: ISO 8601 timestamp indicating when the quote expires. Quotes must be used to create an order before this time.After creating the quote, review the available product offerings and let your customer select their preferred option. This is application logic that happens in your system—no API call is needed.
What this step does: Displays the product offerings returned from Step 1 and allows the customer to select their preferred service.
Why this step: Customers need to see pricing and service details before committing to an order.
Important: Save the formal_product_offering_id of the selected offering—you’ll need it in Step 3 to create the order.
Once the customer has selected a product offering, create an order using the quote_request_id from Step 1 and the formal_product_offering_id from Step 2.
What this step does: Converts the quote into an actual service order.
Why this step: The order initiates the service provisioning process.
Data dependencies: Requires quote_request_id from Step 1 and formal_product_offering_id from Step 2.
After creating an order, periodically check its status to monitor the provisioning progress.
What this step does: Retrieves the current status of an order.
Why this step: You need to know when the service has been provisioned and is ready for use.
Data dependencies: Requires order_id from Step 3.
If an address cannot be serviced, the API will return an error response. Check for invalid_addresses in the response.
If no product offerings are available for a location, handle this gracefully.
Quotes expire after 30 days. Always check expires_at before creating an order.
Broadband quotes return immediately with complete data. DIA quotes require polling.
For detailed endpoint documentation, see:
"Broadband" or "DIA" (case-sensitive)1, 2, or 3 (representing years)account_macnum or account_to_create must be provided. If account_macnum is provided, the account must exist and be accessible with the current authentication scope.bandwidth_mbps is required when product_type is "DIA". It is optional for "Broadband" products.expires_at field in the response indicates the exact expiration time.Retry-After header indicating when to retry."completed".| HTTP Status | Error Description | Resolution |
|---|---|---|
400 | Validation Error | Review the error response body for specific field validation errors. Ensure all required fields are present, data types are correct, and values meet constraints (e.g., valid state code, ZIP code format). |
401 | Authentication Failed | Verify your access token is valid and included in the Authorization header with the "Bearer " prefix. Check token expiration and regenerate if necessary. |
403 | Permission Denied | Your access token does not have the required scope (urn:grt:accessexpress). Contact your administrator to request the appropriate permissions. |
404 | Account Not Found | The provided account_macnum does not exist or is not accessible with your current authentication. Verify the MAC number or use account_to_create instead. |
422 | Unserviceable Location | The provided address is not serviceable for the requested product type. Review the error details for alternative locations or product options. |
429 | Rate Limit Exceeded | You have exceeded the rate limit of 60 requests per minute. Check the Retry-After header in the response to determine when to retry. Implement exponential backoff in your integration. |
500 | Internal Server Error | An unexpected error occurred on the server. Retry the request after a brief delay. If the issue persists, contact Granite support with the request ID from the error response. |