Integration API

As an alternative to our prebuilt Javascript Multiwall and SDK integration options that work completely in the browser of the user, we also offer an HTTP based API. Instead of having a time-based token that is valid for a certain amount of time after an ad was watched successfully, we provide a transactional token that can be validated exactly once. This is mostly only useful for integrations where the verification if an ad was watched completely should be done in the backend.

Checking the availability of the Placement

Similar to our prebuilt Javascript integrations this call has to be made from the client as our answer depends on the device type, the given consent within the TCF 2.0, etc.

POST https://www.welect.de/api/v2/preflight/<your-placement-id>

Please note that the parameters shown in the example below are required in the request body. It is important to note that although a valid tcString is required, there is no requirement about the consent that is represented by the tcString. Welect is able to deliver ads even if there is no consent given for any vendor.

If the placement is available the response will include an entry_url. Opening this url in a browser tab will start the placement.

Examples:

Request body:

{
  "gdpr_consent": {
    "gdprApplies": true, //true if GDPR regulations apply to this traffic
    "tcString": "CQB_d48QB_d48LDAAAENCZCAAAAAAAAAAAAAAAAAAAAA" //If gdpr applies a valid tc string has to be present
  },
  "query_parameters": {
    "payload": "https://www.example.com" //The payload is the link the user will be redirected to after watching an ad
  }
}

Response body if the placement is available:

{
  "available": true
  "entry_url": "https://welect.de/passage/pre_offer/38d4d74f-a350-48b7-9bfe-680e7e32595c?payload=https%3A%2F%2Fwww.example.com"
}

Please note that the entry_url will be different for every request.

If the placement is not available the response will be

{ "available": false }

Running the placement

In case an ad was watched successfully we will append a token via the welect-token parameter that you can use to check if the user actually watched the ad.

If our placement is started with this:

https://welect.de/passage/pre_offer/38d4d74f-a350-48b7-9bfe-680e7e32595c?payload=https%3A%2F%2Fwww.example.com

the user will be redirected to:

https://www.example.com?welect-token=<some-token>

Validating the token

Validating the token should be done from your backend as it can only be done once per token. It is required to set an HTTP Header x-api-secret with a secret value that is provided per placement by Welect. Request:

PUT https://www.welect.de/api/v2/ticket/<token>/close

Will result in a json response:

{
    success: true/false
}