Partner-Sponsoring API

Die Partner-Sponsoring API richtet sich an Partnerorganisationen, die Sponsoring-Kampagnen, Einlöse-Links und den internen Abrechnungsstatus automatisiert verwalten möchten. Damit der Zugriff verfügbar ist, müssen für die Partnerorganisation sowohl partnerSponsorship als auch partnerSponsorshipApi aktiviert sein.

Diese API umfasst keine öffentlichen validate- oder Endnutzer-redeem-Endpunkte. Die eigentliche Einlösung läuft nur über den Produkt-Flow in der App.

Authentifizierung

Diese API verwendet Organisation-API-Schlüssel. Die Schlüssel werden von Organisationsadministratoren erstellt, verwenden das Präfix sk_meingpt_um_ und werden als Bearer-Token gesendet.

curl -X GET "https://app.meingpt.com/api/sponsorship/v1/campaigns" \
  -H "Authorization: Bearer $MEINGPT_SPONSORSHIP_API_KEY"

Rate Limiting

Alle Organisation-API-Schlüssel haben standardmäßig ein Rate-Limit von 100 Anfragen pro Minute. Die Rate-Limit-Informationen werden in den Response-Headern zurückgegeben:

X-RateLimit-Limit: Maximale Anfragen pro Fenster
X-RateLimit-Remaining: Verbleibende Anfragen
X-RateLimit-Reset: Unix-Zeitstempel, wann das Limit zurückgesetzt wird

API-Schlüssel erstellen

Workspace-Admins erstellen Organisation-API-Schlüssel in den Einstellungen. Details findest Du unter API- & Schlüsselverwaltung.

Der Schlüssel wird nur einmal im Klartext angezeigt. Bewahre ihn sicher auf.

Endpunkte

Kampagnen auflisten

GET /api/sponsorship/v1/campaigns?page=1&pageSize=50&status=active|inactive|all

Listet Sponsoring-Kampagnen der Partnerorganisation mit Pagination auf.

Request-Felder

Feld	Ort	Typ	Erforderlich	Beschreibung
`page`	Query	Integer	Nein	Seitennummer, Standard `1`
`pageSize`	Query	Integer	Nein	Einträge pro Seite, Standard `50`, Maximum `100`
`status`	Query	String	Nein	Filter `active`, `inactive` oder `all`, Standard `all`

Antwort

{
  "status": "success",
  "campaigns": [
    {
      "id": "camp_123",
      "name": "Fruehjahrsaktion",
      "durationMonths": 4,
      "maxRedemptions": 250,
      "expiresAt": "2026-06-30T23:59:59.000Z",
      "includedSeats": 5,
      "allowedEmailDomains": ["acme.com"],
      "allowedEmails": ["alice@acme.com"],
      "pricing": {
        "model": "FIXED",
        "amountEur": 5,
        "unit": "PER_REDEMPTION"
      },
      "isActive": true,
      "createdAt": "2026-04-01T08:00:00.000Z",
      "updatedAt": "2026-04-10T12:15:00.000Z",
      "completedRedemptionsCount": 18,
      "reservedRedemptionsCount": 20
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 50,
  "totalPages": 1
}

Fehlercodes

400 - Ungültige Query-Parameter
401 - Ungültiger oder fehlender API-Schlüssel
403 - Feature nicht aktiviert oder kein Zugriff auf die API
404 - Ressource nicht gefunden

Kampagne erstellen

POST /api/sponsorship/v1/campaigns

Legt eine neue Sponsoring-Kampagne an.

Request-Felder

Feld	Typ	Erforderlich	Beschreibung
`name`	String	Ja	Kampagnenname, 1 bis 200 Zeichen
`durationMonths`	Integer	Ja	Sponsoring-Dauer in Monaten, ganzzahlig von `1` bis `6`
`maxRedemptions`	Integer	Nein	Optionales Limit für Einlösungen, mindestens `1`
`expiresAt`	String (Date-Time)	Nein	Optionales Enddatum der Kampagne
`includedSeats`	Integer oder `null`	Nein	Optionale Sitzobergrenze pro gesponsorter Organisation, `1` bis `1000`
`allowedEmailDomains`	String-Array	Nein	Optionale Allowlist von Email-Domains
`allowedEmails`	String-Array	Nein	Optionale Allowlist von einzelnen Email-Adressen

Antwort

{
  "status": "success",
  "campaign": {
    "id": "camp_123",
    "name": "Fruehjahrsaktion",
    "durationMonths": 4,
    "maxRedemptions": 250,
    "expiresAt": "2026-06-30T23:59:59.000Z",
    "includedSeats": 5,
    "allowedEmailDomains": ["acme.com"],
    "allowedEmails": ["alice@acme.com"],
    "pricing": null,
    "isActive": true,
    "createdAt": "2026-04-16T09:30:00.000Z",
    "updatedAt": "2026-04-16T09:30:00.000Z",
    "completedRedemptionsCount": 0,
    "reservedRedemptionsCount": 0
  }
}

Fehlercodes

400 - Ungültiger Request-Body
401 - Ungültiger oder fehlender API-Schlüssel
403 - Feature nicht aktiviert oder kein Zugriff auf die API
404 - Ressource nicht gefunden

Kampagne aktualisieren

PATCH /api/sponsorship/v1/campaigns/:campaignId

Aktualisiert einzelne Felder einer bestehenden Kampagne.

Request-Felder

Feld	Typ	Erforderlich	Beschreibung
`name`	String	Nein	Neuer Kampagnenname, 1 bis 200 Zeichen
`durationMonths`	Integer	Nein	Neue Sponsoring-Dauer, ganzzahlig von `1` bis `6`
`maxRedemptions`	Integer oder `null`	Nein	Neues Limit. `null` entfernt ein bestehendes Limit, Weglassen belässt den Wert unverändert
`expiresAt`	String (Date-Time) oder `null`	Nein	Neues Ablaufdatum. `null` entfernt ein bestehendes Datum, Weglassen belässt den Wert unverändert
`isActive`	Boolean	Nein	Aktiviert oder deaktiviert die Kampagne
`includedSeats`	Integer oder `null`	Nein	Neue Sitzobergrenze. `null` entfernt den Wert
`allowedEmailDomains`	String-Array	Nein	Neue Domain-Allowlist
`allowedEmails`	String-Array	Nein	Neue Email-Allowlist

Antwort

{
  "status": "success",
  "campaign": {
    "id": "camp_123",
    "name": "Fruehjahrsaktion DACH",
    "durationMonths": 5,
    "maxRedemptions": null,
    "expiresAt": null,
    "includedSeats": 10,
    "allowedEmailDomains": ["acme.com", "beispiel.de"],
    "allowedEmails": ["alice@acme.com"],
    "pricing": {
      "model": "FIXED",
      "amountEur": 5,
      "unit": "PER_REDEMPTION"
    },
    "isActive": true,
    "createdAt": "2026-04-01T08:00:00.000Z",
    "updatedAt": "2026-04-16T10:00:00.000Z",
    "completedRedemptionsCount": 18,
    "reservedRedemptionsCount": 20
  }
}

Fehlercodes

400 - Ungültiger Request-Body
401 - Ungültiger oder fehlender API-Schlüssel
403 - Feature nicht aktiviert oder kein Zugriff auf die API
404 - Ressource nicht gefunden

Links einer Kampagne auflisten

GET /api/sponsorship/v1/campaigns/:campaignId/links?page=1&pageSize=100

Listet die Sponsoring-Links einer Kampagne auf.

Request-Felder

Feld	Ort	Typ	Erforderlich	Beschreibung
`campaignId`	Pfad	String	Ja	ID der Kampagne
`page`	Query	Integer	Nein	Seitennummer, Standard `1`
`pageSize`	Query	Integer	Nein	Einträge pro Seite, Standard `100`, Maximum `100`

Antwort

{
  "status": "success",
  "links": [
    {
      "id": "link_123",
      "name": "Landingpage April",
      "token": "abcdef1234567890abcdef1234567890",
      "url": "https://app.meingpt.com/auth?sponsored=abcdef1234567890abcdef1234567890",
      "isActive": true,
      "hasPassword": true,
      "createdAt": "2026-04-16T10:15:00.000Z",
      "completedRedemptionsCount": 7
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 100,
  "totalPages": 1
}

Fehlercodes

400 - Ungültige Query-Parameter
401 - Ungültiger oder fehlender API-Schlüssel
403 - Feature nicht aktiviert oder kein Zugriff auf die API
404 - Ressource nicht gefunden

Link unter einer Kampagne erstellen

POST /api/sponsorship/v1/campaigns/:campaignId/links

Erstellt einen neuen Sponsoring-Link unter einer Kampagne.

Request-Felder

Feld	Typ	Erforderlich	Beschreibung
`name`	String	Nein	Optionaler Anzeigename für den Link, 1 bis 200 Zeichen
`password`	String	Nein	Optionales Passwort für den Link, mindestens 4 Zeichen

Antwort

{
  "status": "success",
  "link": {
    "id": "link_123",
    "name": "Landingpage April",
    "token": "abcdef1234567890abcdef1234567890",
    "url": "https://app.meingpt.com/auth?sponsored=abcdef1234567890abcdef1234567890",
    "isActive": true,
    "hasPassword": true,
    "createdAt": "2026-04-16T10:15:00.000Z",
    "completedRedemptionsCount": 0
  }
}

Fehlercodes

400 - Ungültiger Request-Body
401 - Ungültiger oder fehlender API-Schlüssel
403 - Feature nicht aktiviert oder kein Zugriff auf die API
404 - Ressource nicht gefunden

Link aktualisieren

PATCH /api/sponsorship/v1/links/:linkId

Aktualisiert Name und Aktivstatus eines bestehenden Sponsoring-Links.

Request-Felder

Feld	Typ	Erforderlich	Beschreibung
`name`	String	Nein	Neuer Anzeigename, 1 bis 200 Zeichen
`isActive`	Boolean	Nein	Aktiviert oder deaktiviert den Link

Antwort

{
  "status": "success",
  "link": {
    "id": "link_123",
    "name": "Website Header",
    "token": "abcdef1234567890abcdef1234567890",
    "url": "https://app.meingpt.com/auth?sponsored=abcdef1234567890abcdef1234567890",
    "isActive": false,
    "hasPassword": true,
    "createdAt": "2026-04-16T10:15:00.000Z",
    "completedRedemptionsCount": 7
  }
}

Fehlercodes

400 - Ungültiger Request-Body
401 - Ungültiger oder fehlender API-Schlüssel
403 - Feature nicht aktiviert oder kein Zugriff auf die API
404 - Ressource nicht gefunden

Link-Passwort setzen oder entfernen

PATCH /api/sponsorship/v1/links/:linkId/password

Setzt ein Passwort für einen Link oder entfernt es wieder.

Request-Felder

Feld	Typ	Erforderlich	Beschreibung
`password`	String oder `null`	Ja	Neues Passwort mit mindestens 4 Zeichen oder `null`, um das Passwort zu entfernen

Antwort

{
  "status": "success",
  "success": true
}

Fehlercodes

400 - Ungültiger Request-Body
401 - Ungültiger oder fehlender API-Schlüssel
403 - Feature nicht aktiviert oder kein Zugriff auf die API
404 - Ressource nicht gefunden

Einlösungen einer Kampagne auflisten

GET /api/sponsorship/v1/campaigns/:campaignId/redemptions?page=1&pageSize=100&billingStatus=UNBILLED|BILLED|DISPUTED|WAIVED

Listet abgeschlossene Einlösungen einer Kampagne inklusive Abrechnungsmetadaten auf.

Request-Felder

Feld	Ort	Typ	Erforderlich	Beschreibung
`campaignId`	Pfad	String	Ja	ID der Kampagne
`page`	Query	Integer	Nein	Seitennummer, Standard `1`
`pageSize`	Query	Integer	Nein	Einträge pro Seite, Standard `100`, Maximum `100`
`billingStatus`	Query	String	Nein	Optionaler Filter `UNBILLED`, `BILLED`, `DISPUTED` oder `WAIVED`

Antwort

{
  "status": "success",
  "redemptions": [
    {
      "id": "red_123",
      "redeemedAt": "2026-04-12T15:20:00.000Z",
      "sponsoredUntil": "2026-08-12T15:20:00.000Z",
      "extendedUntil": "2026-09-30T23:59:59.000Z",
      "extensionReason": "Partner verlängert Pilotphase",
      "includedSeats": 5,
      "pricing": {
        "model": "FIXED",
        "amountEur": 5,
        "unit": "PER_REDEMPTION"
      },
      "billingStatus": "UNBILLED",
      "billingAmount": 99,
      "billedAt": null,
      "billingBatchId": null,
      "organizationName": "Beispiel GmbH",
      "userEmail": "admin@beispiel.de",
      "linkName": "Landingpage April"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 100,
  "totalPages": 1
}

Fehlercodes

400 - Ungültige Query-Parameter
401 - Ungültiger oder fehlender API-Schlüssel
403 - Feature nicht aktiviert oder kein Zugriff auf die API
404 - Ressource nicht gefunden

Sponsoring verlängern

PATCH /api/sponsorship/v1/redemptions/:redemptionId/extend

Verlängert eine bestehende Einlösung auf ein späteres Enddatum.

Request-Felder

Feld	Typ	Erforderlich	Beschreibung
`newSponsoredUntil`	String (Date-Time)	Ja	Neues Enddatum, muss nach dem aktuellen `sponsoredUntil` liegen
`reason`	String	Nein	Optionaler interner Grund für die Verlängerung

Antwort

{
  "status": "success",
  "redemption": {
    "id": "red_123",
    "redeemedAt": "2026-04-12T15:20:00.000Z",
    "sponsoredUntil": "2026-09-30T23:59:59.000Z",
    "extendedUntil": "2026-09-30T23:59:59.000Z",
    "extensionReason": "Partner verlängert Pilotphase",
    "campaignId": "camp_123",
    "campaignName": "Pilotkampagne Q3",
    "billingStatus": "UNBILLED",
    "billingAmount": 99,
    "billedAt": null,
    "billingBatchId": null,
    "includedSeats": 5,
    "organizationName": "Beispiel GmbH",
    "userEmail": "admin@beispiel.de",
    "linkName": "Landingpage April",
    "linkToken": "lnk_public_token",
    "pricing": {
      "model": "FIXED",
      "amountEur": 5,
      "unit": "PER_REDEMPTION"
    }
  }
}

Fehlercodes

400 - Ungültiger Request-Body oder neues Datum liegt nicht nach dem aktuellen Enddatum
401 - Ungültiger oder fehlender API-Schlüssel
403 - Feature nicht aktiviert oder kein Zugriff auf die API
404 - Ressource nicht gefunden

Abrechnungsstatus einer Einlösung aktualisieren

PATCH /api/sponsorship/v1/redemptions/:redemptionId/billing

Aktualisiert partnerseitige Abrechnungsmetadaten für eine abgeschlossene Einlösung.

Request-Felder

Feld	Typ	Erforderlich	Beschreibung
`billingStatus`	String	Ja	Neuer Status: `UNBILLED`, `BILLED`, `DISPUTED` oder `WAIVED`
`billingAmount`	Number	Nein	Optionaler Betrag, mindestens `0`
`billingBatchId`	String	Nein	Optionaler Batch- oder Rechnungsbezug

Antwort

{
  "status": "success",
  "success": true
}

Fehlercodes

400 - Ungültiger Request-Body
401 - Ungültiger oder fehlender API-Schlüssel
403 - Feature nicht aktiviert oder kein Zugriff auf die API
404 - Ressource nicht gefunden

Redemption-URL-Flow

Ein Partner erzeugt zuerst einen Sponsoring-Link. Die API liefert dafür bereits die vollständige URL im Feld url, also ${ORIGIN}/auth?sponsored=${token}.

Wenn ein Endnutzer diese URL aufruft, landet er im regulären Authentifizierungs-Flow unter /auth?sponsored=<token>. Nach erfolgreicher Registrierung oder Anmeldung wird für diesen Nutzer eine neue gesponserte Organisation mit der in der Kampagne konfigurierten Dauer angelegt.

Preisinformationen sind über die API nur lesbar. Wenn meinGPT Platform Support kommerzielle Konditionen hinterlegt hat, erscheinen sie im Feld pricing; Partner können diese Werte über die API nicht selbst ändern.

Sponsorship API

Partner-Sponsoring API

Authentifizierung

Rate Limiting

API-Schlüssel erstellen

Endpunkte

Kampagnen auflisten

Kampagne erstellen

Kampagne aktualisieren

Links einer Kampagne auflisten

Link unter einer Kampagne erstellen

Link aktualisieren

Link-Passwort setzen oder entfernen

Einlösungen einer Kampagne auflisten

Sponsoring verlängern

Abrechnungsstatus einer Einlösung aktualisieren

Redemption-URL-Flow

Auf dieser Seite