Introduction

Welcome to the Telcom Developer documentation. We expose a public API service for developer use, which has a detailed OpenAPI 3 specification available in the API Reference.

If you would like to try the endpoints for yourself using Postman or a compatible API testing tool, you can download and use this Postman Collection JSON file

Create a Personal Access Token

Visit the Telcom Portal - Access Token management page and create a new Access Token.

Copy the Access Token value. The token value is only available to copy at the point of Access Token creation. The Access Token is used as the value for Bearer Authentication in your all HTTP requests to the Telcom 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.

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": "Telcom",
                "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