Getting Started with Kevel

Overview

Below are some useful resources to help you get started working with Kevel.

LinkDescription
Getting Started GuideDetailed instructions for launching a test ad.
Kevel Knowledge BaseOur Knowledge Base containing instructions and descriptions of all of our features.
Kevel GlossaryA list of relevant Kevel-specific terms.
Ad Tech GlossaryA list of relevant Ad Tech industry terms.
Ad Servers: The Definitive GuideA description of an ad server.
Kevel AudienceTechnical content and documentation for the Kevel Audience product, including detailed information on data collection and segmentation.

Kevel APIs

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

APIDescription
Decision APICalls Kevel's Ad Decision Engine to fill an ad request. Returns JSON so you can construct a customized ad unit
Reporting APIPulls reporting data directly into your system
Campaign Management API
Automatically creates/updates campaigns and ads in bulk
Inventory Management APIAutomatically creates/updates web properties in bulk
UserDB APIA server-side database for storing user-level information. Learn more here.
Content DB APIA server-side database for storing metadata for contextual targeting. Learn more here.

Generating an API Key

📘

Note

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 or X-Kevel-ApiKey, the two may be used interchangeably.

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

All API requests must use SSL to protect your key.

📘

Note:

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 API access.

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.

Once enabled, the API Key must be passed as a header with the name X-Adzerk-ApiKey.

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!

🚧

Caution

When updating objects, we recommend 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"}'