API Quick Start Guide

Product search lifecycle

A product search takes these steps:

1. Request a Personal Access Token from your account manager.
2. Get your Customer Accounts from the Customer Account Index endpoint.
3. Find a Location by Postcode or UDPRN with the Location Search endpoint.
4. Get the list of Carriers from the Carrier Index endpoint.
5. Create a Search with the New Search endpoint, sending a Customer Account ID, a Location and an array of Carriers. This returns a Search ID.
6. Check the search status with the Search endpoint.
7. Fetch the Product Offers from the Search Offers endpoint.

Get a Personal Access Token

Send the token as a Bearer token in every HTTP request to the Elevate APIs.

Configure your HTTP requests

Every request needs these headers. Here they are as the options object for a JavaScript fetch request:

{
  method: 'GET',
  headers: {
    Accept: 'application/hal+json',
    'Content-Type': 'application/hal+json',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
}

Replace YOUR_ACCESS_TOKEN with your Personal Access Token. Keep the word Bearer and the space after it.

List your customer accounts

Send a GET request to the Customer Account Index endpoint.

GEThttps://api.elevate.uk/user/customer-accounts

The API returns an array of Customer Accounts. You'll need a Customer Account ID when you create a search.

Search for a location

Send a GET request to the Location Search endpoint with either a postcode or a udprn parameter.

GEThttps://api.elevate.uk/locations?postcode=M4%201LN

GEThttps://api.elevate.uk/locations?udprn=24461489

The response is documented in the Location Search endpoint. You'll need a Location ID when you create a search.

Embeds

Add _embed=network to include each location's Elevate network status.

GEThttps://api.elevate.uk/locations?postcode=M4%201LN&_embed=network

Look up available carriers

Send a GET request to the Carrier Index endpoint.

GEThttps://api.elevate.uk/carriers

The response is documented in the Carrier Index endpoint. You'll send an array of Carrier IDs when you create a search.

Create a search

Send a POST request to the New Search endpoint.

POSThttps://api.elevate.uk/searches

The request body must look like this:

{
    "customer_account_id": "00000000000", // required
    "name": "M1 2EH, Internet Access", // optional
    "config": {
        "solution_type": "dia", // required - either "dia" or "ethernet"
        "locations": [
            {
                "type": "b_end",
                "id": "00000000-0000-0000-0000-000000000000"
            }
        ], // required - type should always be "b_end"
        "carriers": [
            "00000000-0000-0000-0000-000000000000",
            "00000000-0000-0000-0000-000000000000",
            "00000000-0000-0000-0000-000000000000",
            "00000000-0000-0000-0000-000000000000",
            "00000000-0000-0000-0000-000000000000",
            "00000000-0000-0000-0000-000000000000"
        ], // required - Array of Carrier IDs to search against.
        "bandwidth": [
            100, 150, 200, 300, 400, 500, 600, 700, 800, 900, 1000,
            2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000
        ], // required -  a subset of the bandwidths in mbps.
        "bearer": [1000, 10000], // required -  a subset of the bearers in mbps.
        "contract": 36, // required -  value in months, one of 1, 12, 36, 60.
        "access": [
            "fibre",
            "wireless",
            "broadband"
        ] // required -  a subset of the examples shown.
    }
}

The response includes a Search ID, which you'll use to check progress and fetch the offers.

Check the search status

Send a GET request to the Search endpoint with the carrier-status embed.

GEThttps://api.elevate.uk/searches/{Search ID}?_embed=carrier-status

The response describes the search and includes an _embedded key like this:

"_embedded": {
    "carrier-status": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Elevate",
            "status": "COMPLETED",
            "updated_at": "2024-06-05T10:51:59.000000Z"
        },
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Luminet",
            "status": "PENDING",
            "updated_at": "2024-06-05T10:51:55.000000Z"
        }
    ]
}

Each carrier in the carrier-status array has a status of "PENDING", "COMPLETED" or "FAILED".

Once no carrier is "PENDING", the search is finished and you can fetch the offers.

Fetch the offers

Send a GET request to the Search Offers endpoint.

GEThttps://api.elevate.uk/searches/{Search ID}/offers

The response includes an array of offers. Results are paginated by default. To get every offer in one response, add noPagination:

GEThttps://api.elevate.uk/searches/{Search ID}/offers?noPagination