Users and context

Your integration sends a placement, a user_key for the viewer, and an optional context object. user_key is required on POST /v1/decision and on POST /v1/decisions. An empty value is rejected. Server SDKs authenticate with X-App-Key and HMAC headers. The browser tag sends X-Web-Key. The key is never in the JSON body.

{
  "placement": "home",
  "user_key": "user-42",
  "context": {
    "plan": "pro",
    "country": "US",
    "locale": "en-US",
    "device": "desktop"
  }
}

POST /v1/decision asks for one placement. HTTP 204 means nothing filled. On that single call, a house ad waits until no paid campaign can fill.

POST /v1/decisions takes 1 to 20 placement names and one user_key. The response is HTTP 200 with one fill per name, in the same order, including when a slot is empty. Repeating a name asks for another slot. An unknown name is an empty fill for that slot and does not fail the others. context is merged once for the whole call.

{
  "placements": ["leaderboard", "infeed", "infeed"],
  "user_key": "user-42",
  "context": {
    "locale": "en-US",
    "device": "desktop"
  }
}

Inside one response, a campaign is used again only when it is the only campaign that can still fill. A house ad can fill a later slot before a paid campaign repeats. If two or more campaigns can still fill and each has already appeared, the extra slot is empty.

Use any stable string you already have: an account ID, session ID, or anonymous device ID. Keep it consistent so frequency caps and profile traits apply to the same viewer. Server SDKs do not set a cookie. You pass user_key on every call.

Do not put user_key on click URLs or advertiser landing pages. If you need to delete a profile, use DELETE /api/v1/apps/{appId}/profiles/{userKey} on the control API.

Static sites load https://meridianads.tech/tag/v1.js with data-token="mw_live_…" and mark slots with data-meridian-placement. Unless data-user-key is set, the tag stores a random id in the first-party cookie meridian_uid for 400 days and sends it as user_key. It also sends locale and device (phone under 768px, tablet under 1024px, otherwise desktop). See the JavaScript guide.

context is a flat JSON object of traits. Send values your campaigns might target, such as country, plan, or device. Traits you send on later requests overwrite earlier values for the same key. Max size is 8KB.

If a campaign requires a trait you do not send, that campaign will not match. See Targeting traits for how rules work.