Carbon Ads API Documentation

Carbon Ads API Integration Guide

This guide explains how to implement Carbon Classic and Carbon Cover ad formats via the Carbon Ads API. It is intended for developers or publishers who prefer direct integration and full control over rendering.

The Carbon Ads API is built on BuySellAds infrastructure. For core API conventions, see: https://docs.buysellads.com/ad-serving-api

Regardless of the implementation, both formats should support pixels if it exists. Refer to the pixels documentation for more details.

Carbon Classic

Endpoint

https://srv.buysellads.com/ads/{zonekey}.json

Example: https://srv.buysellads.com/ads/CVAIKKQM.json

Response Validation

The API returns an ads array. An ad is valid if statlink is non-empty. Skip rendering if statlink is missing or empty.

Required Fields

smallImage — Original size: 260×200px. Render at 130×100px.
description — Must be fully visible and untruncated.
statlink — Wrap the ad container with this URL.
ad_via_link — Use for attribution: “ads via Carbon”.

Rendering Rules

Ensure correct image dimensions, readable text, clickability via statlink, and visible attribution.

Carbon Cover

Response Differences

When Carbon Cover is active, the API includes additional creative fields. This requires a custom layout and interaction logic.

Required Fields

largeImage — 500×500px. Default size: 180×180px, max: 250×250px.
logo — 250×100px. Render at 125×50px.
companyTagline — Shown by default near the logo.
description — Hidden initially. Show on hover or tap.
callToAction — Use for CTA button. Background: #ffffff.
backgroundColor — Use for dynamic background styling with blur/gradient.
ad_via_link — Use for attribution: “ads via Carbon”.

Design Guidelines

You may reuse inline styles or build your own. Maintain functional parity: smooth transitions, mobile responsiveness, and layout consistency.

We strongly encourage replicating the Carbon Cover layout and interaction. You can check out this CodePen example for the HTML structure and methods to handle mobile responsiveness.

Format Summary

Format	Required Elements	Notes
Classic	smallImage description statlink ad_via_link	Static layout. Attribution required. Full description must be visible.
Cover	largeImage logo companyTagline description callToAction backgroundColor ad_via_link	Dynamic layout. Hover reveals description. Includes branding and interaction.

Implementation Goal

Aim for a minimal, functional, and consistent ad experience. Let the creative speak. Your code should stay out of the way.

This documentation has been updated on June 25, 2025