Get started

Integrate Meridian Ads

Add ads to your app in four steps: get a key, request a fill, render the creative, and track impressions and clicks.

Request an ad Request body SDK examples Response formats When ads fill Guides Integration checklist

Point your SDK or HTTP client at serve.meridianads.tech. Each request includes a placement name, a user_key for the viewer, and an optional context object with traits like country or plan. The response is a creative to render, or an empty result when nothing matches.

Manage apps, placements, and keys in this console at meridianads.tech. The control API lives at api.meridianads.tech if you build against REST directly.

serve()

Your app

POST /v1/decision

Serve API

Render + track

Impression and click

Request an ad

HMAC required

Call this endpoint to get a creative for a placement. A 200 response includes the ad to render. A 204 means no ad matched right now. Rate limit is 100 requests per second per app key.

POSThttps://serve.meridianads.tech/v1/decision

Request body

Send placement, user_key, and context in the JSON body. Put your app key prefix in the X-App-Key header, not in the body.

Field	Type	Required	Description
placement	string	Required	The placement name you created in the console for this app.
user_key	string	Required	Your stable ID for this user or session. Do not put it on click or landing URLs.
context	object	Optional	Optional traits for targeting, such as country or plan. Send traits you want campaigns to match on. Max 8KB.

SDK examples

SDK and cURL

SDKs handle signing and headers for you. Use cURL when you need the raw HTTP shape.

POST /v1/decision

import { MeridianAds } from '@yellesoftware/meridian-ads'

const client = new MeridianAds({
  appKey: process.env.MERIDIAN_ADS_APP_KEY,
  secret: process.env.MERIDIAN_ADS_SECRET,
})

const decision = await client.serve('home_banner', 'user-42', {
  country: 'US',
  plan: 'pro'
})

if (!decision) {
  // HTTP 204: no paid or house fill
} else {
  await client.recordImpression(decision)
}

Response formats

native_text and image

A successful response includes creative with either native_text or image fields, plus impression_token and click_url for tracking. Examples below use synthetic IDs.

native_text

JSON

200 fill · synthetic ids

{
  "campaign_id": "3b2e0c6a-4d11-4b0a-9c2e-0f1a2b3c4d5e",
  "house": false,
  "creative": {
    "id": "7aa1b2c3-d4e5-6789-abcd-ef0123456789",
    "format": "native_text",
    "click_url": "https://serve.meridianads.tech/v1/click/{token}",
    "impression_token": "imp_…",
    "native": {
      "headline": "Example native headline",
      "body": "Synthetic copy for the docs.",
      "cta": "Learn more"
    }
  }
}

Example render

Example native headline

Synthetic

Synthetic copy for the docs.

Learn more →

image

300×250

200 fill · synthetic ids

{
  "campaign_id": "3b2e0c6a-4d11-4b0a-9c2e-0f1a2b3c4d5e",
  "house": false,
  "creative": {
    "id": "8bb2c3d4-e5f6-7890-bcde-f01234567890",
    "format": "image",
    "click_url": "https://serve.meridianads.tech/v1/click/{token}",
    "impression_token": "imp_…",
    "image": {
      "cdn_url": "https://cdn.meridianads.tech/…",
      "alt": "Example banner",
      "width": 300,
      "height": 250,
      "mime": "image/webp"
    }
  }
}

Example render

Example banner

cdn.meridianads.tech

Learn more

When ads fill

Only creatives with status approved can fill a live placement. Pending and rejected creatives return no fill until they are approved.

approved

Eligible to fill placements

pending_review

Not eligible yet

rejected

Will not fill

Guides

Integration checklist

1
Create an app, placement, and SDK key in the console.
2
Install an SDK (or call the serve API directly) and sign each request.
3
Call serve with a placement name, user_key, and optional context traits.
4
Render the returned creative, record an impression, and wire clicks to click_url.

Next Users and context