Verivox

Yoli uses the verivox api to provide functionality to switch gas, electricity and dsl contracts.

The functionality is divided into two parts: - gas & electricity - dsl

The reason behind this is that available gas & electricity contracts differ per city district, while available dsl offers may change even more often. Thus an exact address is required.

Note that only a really bare minimum is described here for the sake of conciseness. There are much more fields available to gradually refine searches and give the user detailed information about the offers. You should consider which of these are necessary to provide a good user experience.

Gas & electricity

Before being able to query available offers, we must check whether or not the post code the user resides in has multiple districts in its area. If that's true the user has to choose the district he resides in. That district is sometimes refered to as a paolaLocation.

You can search for potential disctricts with the verivoxDistrictInfo query. It returns all available districts contained in the area of the postCode. Either gas or electricity must also be specified.

{
  verivoxDistrictInfo(productType: "gas", postCode: "34127") {
    fullName
    mainName
    locationID
  }
}
{
  "data": {
    "verivoxDistrictInfo": [
      {
        "fullName": "Am Sandkopf",
        "mainName": "Am Sandkopf",
        "locationID": "597"
      },
      ...
    ]
  }
}

The returned names should be displayed to the user for selection.

The locationID can then be used to query for available offers.

Should the array be empty the district is irrelevant and doesn't have to be supplied in the following queries.

In our example case a district has to be provided however.

{
  verivoxOffers(productType: "gas", postCode: "34127", criteria: {paolaLocationID: "597"}) {
    provider {
      name
    }
  }
}
{
  "data": {
    "verivoxOffers": [
      {
        "provider": [
          {
            "name": [
              "Rainbowenergy"
            ]
          }
        ],
        "subdomain": {
          "url": "https://www.verivox.de/signup/energie/tarif/gas/Jgczzzzz-----xxxxxx=/?ori=xxxxx----------AAD--aaaaaaa----------AAAAAAAAAAAAAAAAAAAA&ranking=1&site_id=123&tariff_id=123&vx_user_id=123&Source_ID=123&SubPartnerId=123&r=True"
        }
      },
      ...
    ]
  }
}

The subdomain.url field should be used to linkout the user to initiate the contract switch.

Errors

Note: If you omit a mandatory parameter or fill it with incorrect values, you will receive a detailed error message.

verivoxOffers(productType: "gas", postCode: "34260", criteria: {maxContractDuration: -5}) {
  rank
  tariff
}
{
  "errors": [
    {
      "message": {
        "id": "#invaidVerivoxParameter",
        "message": "Invalid maxContractDuration -5, allowed 3, 6, 12, 24 or omit"
      },
      "locations": [
        {
          "line": 19,
          "column": 3
        }
      ],
      "path": [
        "verivoxOffers"
      ]
    }
  ],
  "data": {
    "verivoxOffers": null
  }
}

Parameter description

productType: Determines which sort of tariffs you are looking for. (required) - "electricity": Search for electricity tariffs - "gas": Search for gas tariffs Type: String

postCode: Valid zip code of the area, where you are looking for. Type: String

The following parameters are to be specified within criteria and are all optional - just like criteria itself. In this case, default values ​​are used (see next section).

profile: Find tariffs for private or business customers. - h0: private customer (default) - g0: business customer Type: String

bonusIncluded: You can use this filter to specify whether certain one-off payments should be included in the cost details. Possible values are: - none: No bonuses are included in the cost - compliant: Only bonuses are included in the cost of the Verivox consumer protection guidelines - non-compliant All bounuses are included (default) Type: String

prepayment: You can exclude tariffs from the result that require the customer to pay in advance. These prepayments can be requested for up to one year in advance. - true: Consider tariffs with prepayment - false: Exclude tariffs with prepayment (default) Type: Boolean

includePackageTariffs: You can determine whether package rates should be included in the result or filtered out. - true: Consider package rates - false: Exclude package rates (default) Type: Boolean

includeTariffsWithDeposit: You can exclude tariffs from the result that require a deposit, special deduction or cooperative deposit from the customer. - true: Consider tariffs with deposit - false: Exclude tariffs with deposit (default) Type: Boolean

onlyEcoTariffs: You can decide that only eco tariffs are returned. - true: Consider eco tariffs - false: Exclude eco tariffs (default) Type: Boolean

signupOnly: You can filter out tariffs from the result that are not negotiable by Verivox. - true: Only tariffs that can be completed by Verivox (default) - false: No filtering Type: Boolean

maxTariffsPerProvider: Maximum number of returned tariffs per provider. Possible values are 0, 1, 2, 3, 4 or 5. If you omit this parameter, a tariff per provider is supplied by default. At 0, however, all tariffs of a provider are delivered. Type: Int

includeNonCompliantTariffs: This parameter filtered out tariffs that do not comply with the Verivox consumer protection guidelines. - true: No filtering - false: Only tariffs that comply with the Verivox consumer protection guidelines. (default) Type: Boolean

onlyProductsWithGoodCustomerRating: You can decide that only tariffs from providers with high customer recommendation rates are returned. - true: Only tariffs from providers with high customer recommendation rates. (default) - false: No filtering Type: Boolean

onlyRegionalTariffs: Search tariffs with local providers. - true: No filtering - false: Only tariffs from local providers. (default) Type: Boolean

paolaLocationID: The parameter is a mandatory parameter only if locations exist for the postal code. Otherwise you have to omit the parameter. Provided by the verivoxDistrictInfo query. Type: String

minDurationInMonths: You can exclude tariffs that offer no or too short a price guarantee by specifying the minimum period (in months). Possible values are: 0, 3, 6, 12, 24. - Omit parameter: Show tariffs without price guarantee - 0: Show tariffs with any price guarantee - 3: Only return prices that offer at least 3 months price guarantee or limited price guarantee Type: Int

annualTotal: Filters tariffs based on declared annual consumption. Must not be negative. Type: Int

offPeakPercentage: Only for electricity. Specifies the percentage of off-peak time in percent. Range: 0 - 100 (included). Type: Int

heatingPowerInKW: Only for gas. Specification of the heating capacity in KW. If the value is not available, then with heatingPowerInKW = annual consumption / 1600, a reasonable replacement can be assumed. Type: Float

maxResultsPerPage: If you want to spread the result over several pages, you can determine how many hits per page should be returned. 0 will show all tariffs. Type: Int

cancellationPeriodAmount & cancellationPeriodUnit: These two parameters filter by the notice period and can only be used in combination of the following values, otherwise an error is thrown. If the notice period does not matter, the parameters must be omitted. * cancellationPeriodAmount: 1 with cancellationPeriodUnit: "month" * cancellationPeriodAmount: 6 with cancellationPeriodUnit: "week" * cancellationPeriodAmount: 2 with cancellationPeriodUnit: "month" * cancellationPeriodAmount: 3 with cancellationPeriodUnit: "month"

maxContractProlongation: Filters out tariffs from the result based on the contract renewal period (in months) after the end of the initial term. Possible values are: 0 (no filtering), 3, 6, 12 or 24. Type: Int

maxContractDuration: Search tariffs with a maximum of the specified runtime. If the runtime does not matter, the parameter must be omitted, otherwise the number of months is passed. Possible values are: 3, 6, 12 or 24. Type: Int

Default filters

const offersDefaultOptions = {
    profile: "h0",
    prepayment: false,
    includePackageTariffs: false,
    includeTariffsWithDeposit: false,
    onlyEcoTariffs: false,
    bonusIncluded: "non-compliant",
    signupOnly: true,
    maxResultsPerPage: 0,
    benchmarkTariffId: 0,
    maxTariffsPerProvider: 1,
    includeNonCompliantTariffs: false,
    onlyProductsWithGoodCustomerRating: true,
    onlyRegionalTariffs: false,
    usage: {
        annualTotal: 4000,
        offPeakPercentage: 0
    }
};

DSL

Offers by phone prefix

In order to search DSL providers only via the phone prefix, the following GraphQL endpoint is used.

query {
  verivoxDSLOffers(phonePrefix: "0561") {
    providerShortName
    productShortName
    ...
  }
}
{
  "data": {
    "verivoxDSLOffers": [{
        "providerShortName": "Telekom",
        "productShortName": "Magenta Zuhause M Young"
        ...
      },
      ...
    ]
  }
}

Offers by address

Before being able to query DSL offers, the address of the user must be determined in a way that verivox can understand.

This can gradually be done using the verivoxDSLLocationInfo query.

First you search for a list of available city names using a postcode.

{
  verivoxDSLLocationInfo(postCode: "34127") {
    cityName
  }
}
{
  "data": {
    "verivoxDSLLocationInfo": [
      {
        "cityName": "Am Sandkopf"
      },
      {
        "cityName": "Kassel"
      }
    ]
  }
}

Then you can provide that cityName to get information on the available streets verivox has offers for.

{
  verivoxDSLLocationInfo(postCode: "34127", cityName: "Kassel") {
    streets {
      streetName
      streetId
    }
  }
}
{
  "data": {
    "verivoxDSLLocationInfo": [
      {
        "streets": [
          {
            "streetName": "Ahnabreite",
            "streetId": "QWhuYWJyZWl0ZQ=="
          },
          ...
        ]
      }
    ]
  }
}

You can use the streets to build a search for the user.

Once you have the cityName and streetName you can actually query for the available offers.

{
  verivoxDSLOffers(phonePrefix: "0561", postCode: "34117", cityName: "Kassel", streetName: "Wolfhager Str.", houseNumber: 2) {
    signUpLinkDesktop
    signUpLinkResponsive
    productShortName
  }
}

Note: only phonePrefix is required. Only if all 4 address fields are submitted and not empty, only offers that are available at this address or otherwise a corresponding error message will be returned.

{
  "data": {
    "verivoxDSLOffers": [
      {
        "signUpLinkDesktop": "https://www.verivox.de/jump/jump.aspx?gc=true&carrier_id=aaaa&source_id=aaaa&site_id=accc&tariff_id=sssss&utm_source=cccc&utm_medium=verivox-partner&utm_campaign=vxcp-dsl",
        "signUpLinkResponsive": "https://www.verivox.de/jump/jump.aspx?gc=true&carrier_id=aaaa&source_id=bbbbb&site_id=8&tariff_id=cccc&utm_source=ddddddd&utm_medium=verivox-partner&utm_campaign=vxcp-dsl",
        "productShortName": "rainbow20"
      },
      ...
    ]
  }
}

The signUpLink* fields should be used to linkout the user to initiate the contract switch.

Errors

Note: If you omit a mandatory parameter or fill it with incorrect values, you will receive a detailed error message.

verivoxDSLOffers(phonePrefix:"05605", minSpeed: -5) {
  rank
}
{
  "errors": [
    {
      "message": {
        "id": "#invaidVerivoxParameter",
        "message": "Invalid minSpeed -5, allowed 6000, 16000, 25000, 50000 or 100000"
      },
      "locations": [
        {
          "line": 30,
          "column": 3
        }
      ],
      "path": [
        "verivoxDSLOffers"
      ]
    }
  ],
  "data": {
    "verivoxDSLOffers": null
  }
}

Filter docs

Right now the filter docs cannot be properly displayed in graphiql.

verivoxDSLOffers(
    phonePrefix: String!, 
    postCode: String, 
    cityName: String, 
    streetName: String, 
    houseNumber: Int, 
    # Minor speed of the connection. Possible values: 6000, 16000, 25000, 50000 or 100000 kbit/s
    minSpeed: Int,
    # If the customer wants to change (existingCustomer) or is new customer (newCustomer)
    customerType: String, 
    # Contract duration (month). Possible values: 1, 12, 24 or -1 = no matter
    contractDuration: Int, 
    # Possible values: noPhone, noFlatrate, flatrate, withComfortFeaturesNoFlatrate or withComfortFeaturesWithFlatrate
    telephonyFlatIncluded: String, 
    # With TV/Entertainment package or not
    onlyProductsWithTvOptions: Boolean,
    # Access via cable or not
    accessModeCable: Boolean,
    # Access via satellite or not
    accessModeSat: Boolean,
    # Access via DSL or not
    accessModeDsl: Boolean,
    # Access via LTE or not
    accessModeLte: Boolean,
    # Tariffs without limitation
    onlyProductsWithoutTrafficLimitation: Boolean,
    # Only offers with free hardware
    onlyProductsWithFreeHardware: Boolean,
    # Only offers with wlan hardware
    onlyProductsWithWlanHardware: Boolean,
    # Check voucher
    includeVoucher: Boolean,
    # Is mobile service contract bookable?
    mobileOptionAvailable: Boolean,
    # Instant mobil surfing?
    surfSofortOption: Boolean,
    # Show only business customer tariffs
    onlyProductsForBusinessCustomers: Boolean,
    # Show only tariffs that are aimed at young people
    onlyProductsForStudents: Boolean,
    # Show only rates that include special actions such as inclusive hardware, vendor benefits, and so on
    onlySpecialOffers: Boolean, 
    pageNumber: Int,
    pageSize: Int,
    # Remaining term (month). Possible values: 0 - 12
    remainingContractDuration: Int
): [VerivoxDSLOffer]

Parameter description

phonePrefix: Phone prefix of the city (required). Type: String

postCode: ZIP of the city. Type: String

cityName: Provide by verivoxDSLLocationInfo query. Type: String

streetName: Provide by verivoxDSLLocationInfo query. Type: String

houseNumber: The house number of the location. Type: String

minSpeed: Minor speed of the connection. Possible values: 6000 (default), 16000, 25000, 50000 or 100000 (in kbit/s). Type: Int

customerType: Search tariffs for new customers or for changers. - "newCustomer": Tariffs for new customers - "existingCustomer ": Tariffs for changers (default) Type: String

contractDuration: Contract duration in months. - -1: Contract period does not matter (default) - 1: Contract period exactly 1 month - 12 Contract period exactly 12 months - 24: Contract period exactly 24 months Type: Int

telephonyFlatIncluded: You can search for tariffs with flatrates and multiple lines (ISDN). Possible values: noPhone, noFlatrate, flatrate, withComfortFeaturesNoFlatrate or withComfortFeaturesWithFlatrate. - "noPhone": Tariffs with no telephone connection - "noFlatrate": Tariffs without fixed network flatrate - "flatrate": Tariffs with fixed network flatrate (default) - "withComfortFeaturesNoFlatrate": Tariffs with multiple telephone lines without landline flatrate - "withComfortFeaturesWithFlatrate": Tariffs with multiple telephone lines with landline flatrate Type: String

onlyProductsWithTvOptions: Filtered out tariffs with TV/Entertainment package or not. - true: With TV/Entertainment package - false: Without TV/Entertainment package (default) Type: Boolean

accessModeCable: Access via cable or not. Default: true. Type: Boolean

accessModeSat: Access via satellite or not. Default: false. Type: Boolean

accessModeDsl: Access via DSL or not. Default: true. Type: Boolean

accessModeLte: Access via LTE or not. Default: false. Type: Boolean

Note: If one or more accessModes are specified, only offers for these access types will be delivered.

onlyProductsWithoutTrafficLimitation: Returns tariffs with traffic limiation. Default: true. Type: Boolean

onlyProductsWithFreeHardware: Only offers with free hardware. Default: true. Type: Boolean

onlyProductsWithWlanHardware: Only offers with Wi-Fi hardware. Default: true. Type: Boolean

includeVoucher: Consider vouchers or not. Default: true. Type: Boolean

mobileOptionAvailable: Offers for which it is possible to book a mobile phone contract. Default: false. Type: Boolean

surfSofortOption: Is Is instant mobile surfing possible? Default: false. Type: Boolean

onlyProductsForBusinessCustomers: Shows only business customer tariffs. Default: false. Type: Boolean

onlyProductsForStudents: Only show rates that are aimed at young people (offers are usually up to 26 years, benefits or special promotions included). Default: false. Type: Boolean

onlySpecialOffers: Only display tariffs that include special actions such as inclusive hardware, perks of the provider or similar. Default: false. Type: Boolean

pageNumber: Return page x of the result set. Default: 1. Type Int

pageSize: If you want to spread the result over several pages, you can determine how many hits per page should be returned. 0 will show all tariffs. Other possible values: 10, 20 or 30. Type: Int,

remainingContractDuration: Filters the tariffs by the remaining time in months. Possible values: 0 - 12. Default: 6. Type: Int