This is the UTOPIA Public API, outlined on this page are the end points and example JSON to activate each one.
Some end points have an optional network parameter that defaults to UTOPIA, to change the default you can pass the network parameter with the desired network.
Current Network Options: UTOPIA, IDAHOFALLS, BOZEMAN, and BOUNTIFULFIBER
Note: italicized JSON parameters in JSON examples are optional.
https://api.utopiafiber.com
Some endpoints require authentication to access. This documentation will include the endpoints accessible with authentication if authentication is provided.
No API Key Received
Required Parameters:
Example JSON Request:
{
"apikey": "YOUR_API_KEY",
[... additional request inputs ...]
}
Unauthorized - Status Code 401
{
"error": "Authentication Failed"
}
https://api.utopiafiber.com/address/search
This end point expects an address, it will then validate the address and return the Address ID for the address.
You can pass the Network parameter to limit the address search to a desired network only.
Example JSON Request:
{
"network": "UTOPIA",
"search": {
"address": "528 w 800 s",
"postcode": "84058",
"unitnum": ""
}
}
Success return - single record
{
"single": [
{
"address_id": "7529",
"address": "528 WEST 800 SOUTH",
"unitnum": "",
"city": "OREM",
"state": "UTAH",
"postcode": "84058",
"land_use": "RESIDENTIAL",
"history_of_service": "1",
"current_service": "1",
"status": "ORDERABLE",
"contract_type": "none",
"pending_request": "1"
}
]
}
Success return - multi record
{
"multi": [
{
"address_id": "65450",
"address": "673 WEST 1200 SOUTH STREET",
"unitnum": "4",
"city": "OREM",
"state": "UT",
"postcode": "84058",
"land_use": "RESIDENTIAL",
"history_of_service": 1,
"current_service": 0,
"status": "ORDERABLE",
"contract_type": "None",
"pending_request": 0
},
{
"address_id": "65449",
"address": "673 WEST 1200 SOUTH STREET",
"unitnum": "3",
"city": "OREM",
"state": "UT",
"postcode": "84058",
"land_use": "RESIDENTIAL",
"history_of_service": 1,
"current_service": 0,
"status": "ORDERABLE",
"contract_type": "None",
"pending_request": 0
},
{
"address_id": "67707",
"address": "673 WEST 1200 SOUTH STREET",
"unitnum": "7",
"city": "OREM",
"state": "UT",
"postcode": "84058",
"land_use": "RESIDENTIAL",
"history_of_service": 1,
"current_service": 0,
"status": "ORDERABLE",
"contract_type": "None",
"pending_request": 0
}
]
}
{
"none": "No records found"
}
{
"none": "Address field cannot be empty"
}
{
"none": "Postcode field cannot be empty"
}
{
"none": "Incomplete address"
}
https://api.utopiafiber.com/address/chkadid/{siteid}
This end point expects a numeric siteid passed as the last segment in the URI, it will then validate the ID.
Success return example.
{
"address_id": "7529",
"address": "528 WEST 800 SOUTH STREET",
"unitnum": "",
"city": "OREM",
"state": "UT",
"postcode": "84058"
}
{
"error": "ADID not found."
}
https://api.utopiafiber.com/services/providers
This end point provides a list of current Residential providers
You can pass the Network parameter to limit the providers returned to a desired network. By default this end point returns Providers on the UTOPIA network.
Example JSON Request:
{
"network": "UTOPIA"
}
There are no error returns for this end point
https://api.utopiafiber.com/services
This end point provides a list of current Residential services by Provider. This will provide the item ID needed to create an order.
You can pass the Network parameter to limit the services by Provider to a desired network. By default this end point returns services by Provider on the UTOPIA network.
Example JSON Request:
{
"network": "UTOPIA"
}
There are no error returns for this end point
https://api.utopiafiber.com/services/products
This end point provides a list of current Residential products. This will provide the item ID needed to create an order. However only the provider ID is included in the end point.
You can pass the Network parameter to limit the Residential products to a desired network. By default this end point returns Residential products on the UTOPIA network.
Example JSON Request:
{
"network": "UTOPIA"
}
There are no error returns for this end point
https://api.utopiafiber.com/services/infrastructure
This end point returns the list of UTOPIA contracts available for the address ID, ID here must be provided when creating an order, expect when the address doesn't need a contract.
For Bountiful Fiber orders you will need to provide the Data product the user selected to determin the correct contract.
Example JSON Request
{
"siteid": 7529,
"product": "31-174"
}
Success return example.
{
"infrastructure": {
"2": {
"iid": "2",
"name": "Month-to-Month Lease Agreement",
"desc": "This option allows you to lease our fiber on a month-to-month basis for $30\/month for as long as you keep services.",
"mrc": "30",
"nrc": "0",
"multisign": "0",
"billdelivery": [
{
"id": "1",
"desc": "Email me my UTOPIA Fiber bill electronically",
"cost": "0"
},
{
"id": "2",
"desc": "Mail my UTOPIA Fiber bill to my service address ($1.50 per month)",
"cost": "1.5"
},
{
"id": "3",
"desc": "Mail my UTOPIA Fiber bill to my billing address ($1.50 per month)",
"cost": "1.5"
}
]
}
}
}
{
"satisfied": "No contract required for this adid."
}
{
"error": "Invalid adid."
}
https://api.utopiafiber.com/orders/create
This end point will create a new order in the UTOPIA order system. Only residential orders can be processed. To test your API setup please use the test attribute in your JSON it should look like this "test": "true", otherwise you can omit this attribute. This will create a test order that will not be fully processed in our system, a Hello sign contract will still be sent out, but it will not be valid. If no contract is required for the address ID set the infrastructure to 0. If no phone service is being ported than phoneport section of the JSON can also be omitted. You can place any text value in ordersource to help dientify your orgination as the order source.
NOTE: Order's being placed for the Bountiful Fiber Network should have the Customer's Bountiful City Utility account numbers provided for the address they are requesting service for. You can use the accountid1 to pass the Bountiful City Utility Customer ID and accountid2 to pass the Bountiful City Utility Account which is unique to the customer's address
Example JSON snipet with accountid fields
{
"order": {
"firstname": "Bob",
"lastname": "Builder",
"phone": "801-555-3158",
"email": "dtuft@utopiafiber.com",
"accountid1": "xxxxxxxxxxxxxxxxxx",
"accountid2": "xxxxxxxxxxxxxxxxxx",
Example JSON Request
{
"order": {
"firstname": "Bob",
"lastname": "Builder",
"phone": "801-555-3158",
"email": "dtuft@utopiafiber.com",
"adid": "7529",
"billdelivery": "1",
"products": [
{
"itemid": "2-10",
"qty": "1"
},
{
"itemid": "2-4",
"qty": "1"
},
{
"itemid": "2-29",
"qty": "1"
},
{
"itemid": "2-87",
"qty": "3"
}
],
"infrastructure": "3",
"billingaddress": {
"name": "Bob Builder",
"phone": "801-555-1212",
"address": "1118 heat street",
"unitnum": "",
"city": "Mesa",
"postalcode": "81111",
"state": "AZ"
},
"phoneport": [
{
"name": "Bob Builder",
"number": "801-555-3158",
"provider": "Comcast",
"address": "711 south 1420 west, Orem, UT 84058"
},
{
"name": "Bob Builder",
"number": "801-555-9603",
"provider": "Comcast",
"address": "711 south 1420 west, Orem, UT 84058"
}
],
"signers": [
{
"name": "Bob Builder",
"email": "dustintuft@gmail.com",
"phone": "801-555-3158"
},
{
"name": "Bob1 Builder1",
"email": "dtuft@utopiafiber.com",
"phone": "801-555-3158"
}
],
"promo": "random code",
"ordersource": "APIuser",
"test": "true"
}
}
Success return example.
{
"done": "Order saved, reference UIA201900-000000",
"reference": "UIA201900-000000"
}
{
"error": "At least one product quantity must be greater than 0. "
}
{
"error": "No infrastructure found. "
}
{
"error": "ADID not found."
}
{
"error": "No parent product found for add on item 127 "
}
JSON errors are referring to the JSON sent to the end point such as syntax or other issues present in the JSON.
{
"error": "JSON: Syntax error. "
}
Possible messages: JSON: Maximum stack depth exceeded. JSON: Invalid or malformed JSON. JSON: Control character error. JSON: Malformed UTF-8 characters. Unknown error please check JSON sent.
https://api.utopiafiber.com/orders/status/UIA201805-000020
This end point expects a Reference ID passed through the URI, it will than look up the reference number are retrun the current status.
Success return example.
{
"status": "Canceled"
}
{
"error": "Reference ID not found."
}