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, BOUNTIFULFIBER, IDAHOFALLS, BOZEMAN
Note: italicized JSON parameters in JSON examples are optional.
https://api.utopiafiber.comSome 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/searchThis endpoint is used to search for address matches
Search by Address
Note: requests where the required paramters are enclosed within a search object are also accepted.
Without any optional parameters, search by address will attempt to perform a natural language match on the address. If no matches are found, a legacy wildcard match will be performed. If the optional wildcard parameter is provided, or the optional geocode paramter is set to true, the natural language match logic and the legacy wildcard match logic will be skipped.
Search by Site ID
Search by Parcel ID (multiple siteids can be located on a single parcel)
Search by latitude / longitude (Matches addresses that fall within the same parcel that the given coordinates fall within)
Example JSON Requests:
{
"address": "528 w 800 s",
"postcode": "84058",
"unitnum": ""
}
{
"network": "UTOPIA",
"wildcard": "none",
"address": "528 w 800 s",
"postcode": "84058",
"unitnum": ""
}
{
"geocode": true,
"address": "528 w 800 s",
"postcode": "84058",
"unitnum": ""
}
{
"siteid": 65450
}
{
"parcelid": 41865
}
{
"latitude": 40.282768228301,
"longitude": -111.70823608289935,
"network": "UTOPIA"
}
Success return - single record
{
"single": [
{
"address_id": "7529",
"address": "528 WEST 800 SOUTH STREET",
"unitnum": "",
"city": "Orem",
"state": "Utah",
"postcode": "84058",
"latitude": "40.28289158",
"longitude": "-111.70821967",
"parcel_id": "63732",
"land_use": "RESIDENTIAL",
"history_of_service": 0,
"current_service": 1,
"status": "ORDERABLE",
"contract_type": "Paid",
"pending_request": 0,
"network": "UTOPIA",
"legacy": "0",
"infrasat": "1",
"billorg": "UTOPIA"
}
]
}
Success return - multi record
{
"multi": [
{
"address_id": "65444",
"address": "673 WEST 1200 SOUTH STREET APT# 1",
"unitnum": "",
"city": "Orem",
"state": "Utah",
"postcode": "84058",
"latitude": "40.27514366",
"longitude": "-111.71142677",
"parcel_id": "41865",
"land_use": "RESIDENTIAL",
"history_of_service": 0,
"current_service": 0,
"status": "ORDERABLE",
"contract_type": "None",
"pending_request": 0,
"network": "UTOPIA",
"legacy": "0",
"infrasat": "0",
"billorg": "UIA"
},
{
"address_id": "65446",
"address": "673 WEST 1200 SOUTH STREET APT# 2",
"unitnum": "",
"city": "Orem",
"state": "Utah",
"postcode": "84058",
"latitude": "40.27514366",
"longitude": "-111.71142677",
"parcel_id": "41865",
"land_use": "RESIDENTIAL",
"history_of_service": 0,
"current_service": 0,
"status": "ORDERABLE",
"contract_type": "None",
"pending_request": 0,
"network": "UTOPIA",
"legacy": "0",
"infrasat": "0",
"billorg": "UIA"
},
{
"address_id": "65449",
"address": "673 WEST 1200 SOUTH STREET APT# 3",
"unitnum": "",
"city": "Orem",
"state": "Utah",
"postcode": "84058",
"latitude": "40.27514366",
"longitude": "-111.71142677",
"parcel_id": "41865",
"land_use": "RESIDENTIAL",
"history_of_service": 0,
"current_service": 0,
"status": "ORDERABLE",
"contract_type": "None",
"pending_request": 0,
"network": "UTOPIA",
"legacy": "0",
"infrasat": "0",
"billorg": "UIA"
}
]
}
{
"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": "Utah",
"postcode": "84058",
"latitude": "40.28289158",
"longitude": "-111.70821967",
"footprint": "OR006"
}
{
"error": "ADID not found."
}
https://api.utopiafiber.com/services/providersThis 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/servicesThis 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/productsThis 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/infrastructureThis 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/createThis end point will create a new order in the UTOPIA order system. Only residential orders can be processed. 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 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-0999",
"email": "bobbuilder@example.com",
"accountid1": "xxxxxxxxxxxxxxxxxx",
"accountid2": "xxxxxxxxxxxxxxxxxx",
Example JSON Request
{
"order": {
"firstname": "Bob",
"lastname": "Builder",
"phone": "801-555-0999",
"email": "bobbuilder@example.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-0999",
"address": "1118 heat street",
"unitnum": "",
"city": "Mesa",
"postalcode": "81111",
"state": "AZ"
},
"phoneport": [
{
"name": "Bob Builder",
"number": "801-555-0999",
"provider": "Comcast",
"address": "711 south 1420 west, Orem, UT 84058"
},
{
"name": "Bob Builder",
"number": "801-555-0999",
"provider": "Comcast",
"address": "711 south 1420 west, Orem, UT 84058"
}
],
"signers": [
{
"name": "Bob Builder",
"email": "bobbuilder@example.com",
"phone": "801-555-0999"
},
{
"name": "Bob1 Builder1",
"email": "bob1builder1@example.com",
"phone": "801-555-0999"
}
],
"promo": "random code",
"ordersource": "|unique identifier such as Company or agent name|"
}
}
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-000020This 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."
}