AD10€10 Rabatt mit Code AD10 beim Checkout
Dokumentation

Docs durchsuchen

Nach Thema suchen…

API

Partner-API

Basis-URL ist https://adyoutiser.com/api/v1. Jeder Aufruf trägt einen Bearer-Token. Fehler kommen als RFC-7807-Problem-Dokument zurück.

Aktualisiert

Zugang

Die API ist für Partner mit API-Zugang. Die Zugangsdaten vergibt die Administration. Es gibt keine Selbstregistrierung und keinen Key-Generator im Dashboard.

Basis-URL
https://adyoutiser.com/api/v1
Auth-Header
Authorization: Bearer <token>Einen Header X-API-Key gibt es nicht.
Fehlerformat
application/problem+json (RFC 7807)
Rate-Limit
600 Anfragen pro Minute pro Zugang, voreingestellt.

Authentifizierung

Schick den Token im Authorization-Header. Das Präfix entscheidet, wie er gelesen wird: ein Wert, der mit adyo_ beginnt, gilt als API-Key, alles andere als OAuth-Zugriffstoken.

curl -H "Authorization: Bearer adyo_your_api_key" \
  "https://adyoutiser.com/api/v1/screens?city=Wien&limit=50"
API-Key: bei jedem Aufruf unverändert mitschicken.
curl -X POST "https://adyoutiser.com/api/v1/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'
OAuth: Client-Credentials gegen einen Zugriffstoken tauschen.
{
  "access_token": "...",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "screens:read"
}
Der Token ist 3600 Sekunden gültig. Vor Ablauf erneuern.

Der Token-Endpunkt ist eng limitiert

10 Anfragen pro Minute pro IP. Cache den Token die volle Stunde, statt pro Aufruf einen zu holen.

Limits und Fehler

BereichLimit
POST /oauth/token10 pro Minute pro IP.
Alle anderen Endpunkte600 pro Minute pro Zugang, voreingestellt.
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 60
Über dem Limit bekommst du 429 und ein Retry-After von 60 Sekunden.

Jeder Fehler-Body folgt RFC 7807 mit dem Content-Type application/problem+json.

type
Kennung des Fehlertyps.
title
Kurze Bezeichnung des Fehlers.
status
Der HTTP-Statuscode.
detail
Was bei diesem konkreten Aufruf schiefging.
retry_after
Nur bei 429. Wartezeit in Sekunden.

Endpunkte

MethodePfadScope
POST/api/v1/oauth/token—
GET/api/v1/screensscreens:read
GET/api/v1/screens/{screenId}screens:read
GET/api/v1/screens/{screenId}/availabilityscreens:read
POST/api/v1/couponscoupons:write
GET/api/v1/coupons/{code}coupons:read | coupons:write
POST/api/v1/coupons/{code}/revokecoupons:write
GET/api/v1/users/lookupusers:read
POST/api/v1/landing-linkslinks:write
GET/api/v1/campaign-requestscampaign_requests:read
GET/api/v1/campaign-requests/{id}campaign_requests:read

Screens. GET /screens liefert { data, pagination } mit cursor, has_more und total_count. Filter: country (2 Buchstaben), city, orientation, bbox. limit ist voreingestellt auf 50, Maximum 200; geblättert wird über cursor.

{
  "id": "...",
  "name": "...",
  "description": "...",
  "country": "AT",
  "city": "Wien",
  "address": "...",
  "latitude": 0,
  "longitude": 0,
  "orientation": "portrait",
  "resolution_width": 1080,
  "resolution_height": 1920,
  "price_per_day_cents": 0,
  "ad_sov_pct": 0,
  "thumbnail_url": "...",
  "venue_type": "...",
  "is_active": true,
  "created_at": "..."
}
Felder eines Screen-Objekts. Die Werte hier sind Platzhalter, kein Inventar.

Ein 404 heißt nicht weg

GET /screens/{id} antwortet auch dann mit 404, wenn der Screen existiert, aber nicht buchbar ist.

Verfügbarkeit. from und to sind Pflicht, Format YYYY-MM-DD. Die Antwort enthält screen_id, from, to, max_sov_pct, used_sov_pct, available_sov_pct und price_per_day_cents.

curl -H "Authorization: Bearer adyo_your_api_key" \
  "https://adyoutiser.com/api/v1/screens/SCREEN_ID/availability?from=2026-09-01&to=2026-09-07"

Gutscheine. POST /coupons antwortet mit 201. Pflicht: discount_type (percent, amount_cents oder free_days), discount_value größer 0, und lead_email. Optional: code, max_redemptions (1–1000, Voreinstellung 1), valid_until, lead_metadata. Ohne eigenen code wird einer im Muster BVCC-XXXX erzeugt.

curl -X POST "https://adyoutiser.com/api/v1/coupons" \
  -H "Authorization: Bearer adyo_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "discount_type": "percent",
    "discount_value": 10,
    "lead_email": "lead@example.com",
    "max_redemptions": 1
  }'
StatusWann
400percent über 100, oder ein Revoke auf einen Gutschein, der nicht mehr aktiv ist oder schon eingelöst wurde.
409Der Code ist bereits vergeben, oder diese lead_email hat auf deinem Zugang schon einen aktiven Gutschein. Ein aktiver Gutschein pro Lead-E-Mail pro Zugang.

Nutzer. GET /users/lookup nimmt email oder vat_uid. Du bekommst entweder { "data": { "exists": false } } oder einen Datensatz mit user_id, registered_at, has_bookings und optional attribution. Die Attributionsdaten kommen nur zurück, wenn die Vermittlung deinem eigenen Zugang zuzuordnen ist.

Landing-Links. POST /landing-links antwortet mit 201 und liefert eine url samt UTM-Parametern. utm_medium ist immer partner_api.

Kampagnenanfragen. GET /campaign-requests filtert nach status (rejected, abandoned, no_inventory, converted), from, to und industry. Du siehst immer nur deine eigenen Anfragen.

Webhooks

EreignisWird ausgelöst, wenn
user.registeredEin vermittelter Nutzer registriert sich.
campaign.paidEine Kampagne wird bezahlt.
coupon.redeemedEiner deiner Gutscheine wird eingelöst.
campaign_request.createdEine Kampagnenanfrage geht ein.
campaign_request.rejectedEine Kampagnenanfrage wird abgelehnt.
X-Adyoutiser-Signature: t=1754438400,v1=<hex>
Prüf diesen Header, bevor du dem Body vertraust.

Wiederholungen

Bei Fehlern wird bis zu 5-mal erneut zugestellt, im Abstand 1 s, 5 s, 30 s, 2 min, 10 min. Danach gilt die Zustellung als erschöpft — antworte schnell mit 2xx und arbeite danach.

Passt dazu

  • Partner-ÜberblickDir gehört der Screen. Wir verkaufen die Werbezeit und zahlen dich pro Kampagne. Was das konkret heißt.
  • Wie Adyoutiser funktioniertEchte Screens an echten Adressen. Du buchst einen Anteil an der Werbezeit — so wird der Anteil verteilt.