Getting Started with Kevel

🚧

Before you can test Kevel's APIs, you will need to sign-up for an account.

Welcome!

Below are some useful resources as you get started.

Link

Description

Getting Started Guide

Detailed instructions for launching a test ad

Kevel Knowledge Base

Our Knowledge Base containing instructions and descriptions of all of our features

Kevel Glossary

A list of relevant Kevel-specific terms

Ad Tech Glossary

A list of relevant Ad Tech industry terms

Ad Servers: The Definitive Guide

A review of what an ad server is

Kevel APIs

Kevel contains a full suite of APIs to build a customizable ad server. A brief overview of these APIs is below.

API

Description

Decision API

Calls Kevel's Ad Decision Engine to fill an ad request. Returns JSON so you can construct a customized ad unit

Reporting API

Pull reporting data directly into your system

Campaign Management API

Automatically create/update campaigns and ads in bulk

Inventory Management API

Automatically create/update web properties in bulk

UserDB API

A server-side database for storing user-level information. Learn more here.

Content DB API

A server-side database for storing metadata for contextual targeting. Learn more here.

Generating an API Key

📘

Before you can test Kevel's APIs, you will need to sign-up for an account.

The first step to using the Kevel API is to generate an API Key:

  1. Navigate to the Settings section of your Kevel account and choose the API Keys tab or follow this link
  2. Click 'New API Key', and then copy the generated key to use in your code.

Domain

The base domain of the Management API is https://api.kevel.co/. Management API endpoints use /v1/, such as https://api.kevel.co/v1/site.

Authenticating Requests

To authenticate with the Kevel API, the API Key must be passed as a header with the name X-Adzerk-ApiKey.

curl -X GET -H 'X-Adzerk-ApiKey:1234567890ABCDEF1234567890ABCDEF'

All API requests must use SSL to protect your key.

👍

Your API Key is the same as a username/password so be sure to treat it the same way!

📘

Some endpoints, such as the Decision API, do not require API Key authentication. For added security, Kevel has the option to require API Key authentication for the Decision API. Please reach out to your CSM or [email protected] to enable.

You have the option to enable API Key authentication for the following:

Decision Requests: Once enabled, requests to the Decision API will not return a decision without a valid API Key sent in the request header.
EventURL: Once enabled, EventURLs will not count towards reported metrics without a valid API Key sent in with the EventURL request.
UserDB: Once enabled, requests to UserDB will not succeed without a valid API Key sent in with the request.

One enabled, the API Key must be passed as a header with the name X-Adzerk-ApiKey or X-Kevel-ApiKey , the two may be used interchangeably.

Requests lacking the header, or requests with an invalid API Key for the network, will be rejected with a 401 HTTP status.

Payload and Content-Type

The data payload for POST and PUT endpoints is in JSON format. The Content-Type for these endpoints is application/json, which should be passed as a header in your requests:

curl -X POST -H 'X-Adzerk-ApiKey:1234567890ABCDEF1234567890ABCDEF' -H 'Content-Type:application/json'

In curl, the JSON payload should be passed via the --data-binary flag:

curl -X POST -H 'X-Adzerk-ApiKey:1234567890ABCDEF1234567890ABCDEF' -H 'Content-Type:application/json' https://api.kevel.co/v1/site --data-binary '{"Title":"Adzerk","URL":"https://adzerk.com"}'

Note the use of https in the endpoint. Using SSL protects your data and your API key!

🚧

PUT Endpoints and Updating Objects

When updating objects, we recommend that you pass the entire contents of the object as the payload. Otherwise, some values may be set to null.

We also recommend using the GET endpoint to capture the current state of the object before updating.

Legacy Content-Type (Form Encoded)

The POST and PUT endpoints of the Management API can also be used using a legacy form encoded data type (not recommended). You should specify the Content-Type header as application/x-www-form-urlencoded and pass the JSON data object as the value of a key that uses the name of that object (as documented in the "cURL - Legacy" examples):

curl -X POST -H 'X-Adzerk-ApiKey:1234567890ABCDEF1234567890ABCDEF' -H 'Content-Type:application/x-www-form-urlencoded' https://api.kevel.co/v1/site --data-urlencode 'Site={"Title":"Adzerk","URL":"https://adzerk.com"}'