API Quick Start Guide ⚡

Product Search Lifecycle

Searches can be made by completing the following steps:

1. Create a Personal Access Token via the Elevate Customer Portal.
2. Request a list of your Customer Accounts from the Customer Account Index endpoint.
3. Customer Account Index endpoint returns an array of Customer Accounts.
4. Search a Postcode or UDPRN on the Location Search endpoint.
5. Location Search endpoint returns an array of Locations.
6. Request a list of Carriers from the Carrier Index endpoint.
7. Carrier Index endpoint returns an array of Carriers.
8. Create a Search with the New Search endpoint sending an array of Carriers, a Location and a Customer Account ID.
9. New Search endpoint returns a Search ID.
10. Use the Search endpoint to check the search status.
11. Request a list of Product Offers from Search Offers endpoint.

Create a Personal Access Token

The Access Token is used as the value for Bearer Authentication in your all HTTP requests to the Elevate APIs.

Configure your HTTP requests

All HTTP requests to our APIs require the following headers shown here formatted as the options object for a javascript fetch request.

  {
    method: 'GET',
    headers: {
      Accept: 'application/hal+json',
      'Content-Type': 'application/hal+json',
      Authorization: 'Bearer [PAT value eg: ey1234...]'
    }
  }

Index your Customer Accounts

Send a GET request to the Customer Account Index endpoint.

https://api.telcom.uk/user/customer-accounts

The API will return an array of Customer Accounts, we will use a Customer Account ID to create a search later in the process.

Search the Location API

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

https://api.telcom.uk/locations?postcode=M4 1LN

https://api.telcom.uk/locations?udprn=24461489

The API will return a response as documented in the Location Search endpoint.

We will use a Location ID to create a Search later in the process.

Embeds

Additionally you can request the network status from the Elevate Network via the _embed parameter.

https://api.telcom.uk/locations?postcode=M4 1LN&_embed=network

Look up available Carriers

Send a GET request to the Carrier Index endpoint.

https://api.telcom.uk/carriers

The API will return a response as documented in the Carrier Index endpoint.

Create a Search

Send a POST request to the New Search endpoint.

https://api.telcom.uk/searches

The body of the POST request must include to following body object.

    {
        "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 will include a Search ID that will be used to fetch product offers later in the process.

Check Search status

Send a GET request to the Search endpoint with an embed argument like so.

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

The response will return information about the search passed in the URL. There will be an _embedded key on the response object with contents like the following.

    "_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 object in the carrier-status array will have a status key with the a value of "PENDING" | "COMPLETED" | "FAILED".

Once each status key has a value that does not equal "PENDING" it is safe to fetch the offers for the search as detailed in the next step.

Check for created offers

Send a GET request to the Search Offers endpoint.

https://api.telcom.uk/searches/{Search ID}/offers

The response will include an array of results, by default the results are paginated, alternatively you can request the results with no pagination.

https://api.telcom.uk/searches/{Search ID}/offers?noPagination