Inhaltsverzeichnis

API-Zugriff für personalisierte Teilnahmelinks

Die Funktion Einladungen verschicken → API-Zugriff erlaubt folgende Funktionen:

Eine wesentliche Anwendung der API-Funktion für Serienmails ist die Anbindung eines Shop-Systems. So kann man einem Kunden etwa nach Kauf der Zugangsberechtigung einen gültigen Teilnahme-Link zum Fragebogen übermitteln.

Hintergrund

Für gewöhnlich erstellt SoSci Survey eine personalisierten URL zur Teilnahme an einer Befragung in dem Moment, wenn Sie eine Serienmail versenden. Alternativ kann man mittels Teilnahmecodes manuell personalisierte Links erstellen, allerdings mit Einschränkungen bei der Anonymität und Funktionialität – und Teilnahmecodes benötigen eine andere Zugriffsbeschränkung im Fragebogen als Serienmails.

Mit der Funktion Einladungen verschicken → API-Zugriff können Sie personalisierte Links zum Fragebogen erstellen und ggf. in einer externen Software verwenden, die genauso funktionieren wie die personalisierten Links in Serienmails. Allerdings wird dabei nicht zwangsläufig eine E-Mail verschickt. Wenn keine Serienmail verschickt werden soll, ist nicht einmal eine E-Mail-Adresse notwendig.

Adresseinträge erstellen

Beim Aufruf der API-URL erwartet SoSci Survey, dass mindestens eines der folgenden Identifikationsmerkmale für den (eventuell neuen) Adresseintrag mittels GET oder POST übermittelt wird:

Wenn die API-URL https://www.soscisurvey.de/PROJEKT/?act=83w7vaYqaeakXH7axpH2Yexu lautet, könnte ein gültiger Aufruf etwa wie folgt aussehen. Dabei wird als Identifikationsmerkmal eine Kennung (uid, User ID) verwendet: 

  https://www.soscisurvey.de/PROJEKT/?act=83w7vaYqaeakXH7axpH2Yexu&uid=112233aabbcc

Falls ein passender Eintrag in der Adressliste gefunden wird, wird dieser verwendet. Ansonsten wird unter Einladungen verschicken → Adressliste ein neuer Eintrag erstellt.

SoSci Survey erstellt nun einen gültigen Teilnahmelink und übermittelt diesen als Antwort auf den Aufruf als JSON zurück.

Rückgabewert

Die Antwort auf eine gültige Anfrage könnte etwa wie folgt aussehen: 

{
  "result": "ok",
  "token":  "QS33T6XMVS4KLA9S",
  "url":    "https:\/\/www.soscisurvey.de\/PROJEKT\/?d=QS33T6XMVS4KLA9S",
  "error":  null
}

Im Erfolgsfall enthält das Feld result den Wert ok, ansonsten einen anderen Wert. Außerdem wird im error dann einer Fehlermeldung zurückgegeben. Hier etwa die Antwort auf einen Aufruf ohne Identifikationsmerkmal: 

{
  "result": "error",
  "error":  "Request must specify email, mobile, or uid",
  "url":    null
}

Manueller Aufruf

Der API-Zugriff ist eigentlich für einen automatisierten Aufruf durch eine externe Software ausgelegt (Maschine-zu-Maschine Kommunikation), kann auch dafür „missbraucht“ werden, manuell gültige Teilnahme-Links zu erstellen.

Legen Sie dafür einen API-Link an, wie oben beschrieben. Rufen Sie anschließend die API-URL mit unterschiedlichen Identifikationsmerkmalen auf. Etwa mit den Kennungen respondent01, respondent02, respondent03, …

Die Teilnehmer-ID muss dabei jeweils manuell in die Adresszeile eingetragen werden. 

  https://www.soscisurvey.de/PROJEKT/?act=83w7vaYqaeakXH7axpH2Yexu&uid=respondent01
  https://www.soscisurvey.de/PROJEKT/?act=83w7vaYqaeakXH7axpH2Yexu&uid=respondent02
  https://www.soscisurvey.de/PROJEKT/?act=83w7vaYqaeakXH7axpH2Yexu&uid=respondent03

Ihr Browser zeigt nach jedem Aufruf eine gültige Teilnahme-URL an, die etwa per E-Mail an die Teilnehmer verschickt werden kann.

Eine Funktion zum automatisierten Erstellen einer größeren Anzahl von Teilnahmelinks ohne externe Software ist in Planung, derzeit allerdings nur mit geringer Priorität. Falls die Anonymität nicht kritisch ist (oder wenn sie ganz besonders kritisch ist), kann dafür die Funktion Teilnahmecodes zum Einsatz kommen.

Teilnahmestatus Teilnahmecode

Beim Aufruf der API-URL erwartet SoSci Survey, dass ein Parameter serial mit dem zu prüfenden Teilnahmecode übermittelt wird.

Wenn die API-URL https://www.soscisurvey.de/PROJEKT/?act=exu83w7vaYqaeakXH7axpH2Y lautet, könnte ein gültiger Aufruf zur Überprüfung des Teilnahmecodes „CD246802“ etwa wie folgt aussehen. 

  https://www.soscisurvey.de/PROJEKT/?act=exu83w7vaYqaeakXH7axpH2Y&serial=CD246802

Als Rückgabewert wird ein JSON-String mit folgender Struktur geliefert: 

{
  result:    "ok",
  code:      "CD246802",
  started:   true,
  completed: false,
  notice:    "",
  error:     null
}

Die Attribute haben die folgende Bedeutung:

Im Fehlerfall wird nur der Status-Code und eine Fehlermeldung zurückgegeben, falls vorhanden auch den angefragten Teilnahmecode: 

{
  result:    "error",
  error:     "not found",
  code:      "CD246802"
}

Teilnahmestatus für Adresseintrag

Beim Aufruf der API-URL erwartet SoSci Survey, dass mindestens ein Parameter angegeben wird, um den Adresseintrag zu identifizieren. Falls mehrere Eigenschaften angegeben werden, wird nach einem Adresseintrag gesucht, der alle Eigenschaften hat. Der Adresseintrag kann anhand folgender Eigenschaften gesucht werden:

Wenn die API-URL https://www.soscisurvey.de/PROJEKT/?act=erSoqORu4OPzGeWyetpwmbMu lautet, könnte ein gültiger Aufruf zur Überprüfung des Teilnahmestatus von „person@example.com“ etwa wie folgt aussehen. 

  https://www.soscisurvey.de/PROJEKT/?act=exu83w7vaYqaeakXH7axpH2Y&email=person@example.com

Als Rückgabewert wird ein JSON-String mit folgender Struktur geliefert: 

{
  result:  "ok",
  serial:  null
  email:   "person@example.com"
  mobile:  null
  uid:     null
  mailings: {
    M1: {
      id:         1
      status:     "sent"
      statusMail: "delivered"
      statusSMS:  "none"
      sendTime:   "2023-11-09"
    },
    M2: {
      id:         2
      status:     "skipped",
      statusMail: "none",
      statusSMS:  "none",
      sendTime:   "2023-07-02"
    }
  },
  error:   null
}

Im ersten Teil der Antwort werden die verwendeten Suchparameter zurückgegeben.

Der Teilnahmestatus wird für jede Serienmail angegeben, für welche ein Versand an diesen Adresseintrag versucht wurde. Als Schlüssel für die mailings wird dabei „M“ und die ID der Serienmail verwendet.

Die Attribute haben die folgende Bedeutung:

Im Fehlerfall wird nur der Status-Code und eine Fehlermeldung zurückgegeben, falls vorhanden auch den angefragten Teilnahmecode: 

{
  result:    "error",
  error:     "not found",
  serial:    null
  email:     "nobody@example.com"
  mobile:    null
  uid:       null
}