This translation is older than the original page and might be outdated. See what has changed.
Translations of this page:
 

API access for personalized participation links

The feature Send InvitationsAPI access allows the following functions:

  • To enter an e-mail addresses or other participant IDs from external software in the address list of the survey project.
  • Optionally, to trigger the sending of individual serial emails, also automated by an external software.
  • To create personalized links to the questionnaire that work just like the personalized links in serial emails.

An essential application of the API function for serial mails is the connection of a shop system. For example, you can send a valid participation link to the questionnaire to a customer after purchasing the access authorization.

Background

Usually, SoSci Survey creates a personalized URL to participate in a survey in the moment you send a serial mail. Serial numbers can be used to manually create personalized links, but with restrictions on anonymity and functionality - and serial numbers require a different access restriction in the questionnaire than serial emails.

With the Send invitations function → API access you can create personalized links to the questionnaire and, if necessary, use them in external software that works in the same way as the personalized links in serial mail. However, no e-mail is sent and not even an e-mail address is required.

Use

  • First, create a new serial mail under Send invitationsSerial mail. This mail is not sent, but here you can make all settings for the link and check the participation status.
  • Subsequently, then select this serial email under Send invitationsAPI access. Select in Function whether the serial mail should be sent by SoSci Survey or not. If necessary, specify a subgroup for new address entries and, in case of anonymity of new addresses , whether the assignment of person ID (SERIAL) and e-mail address should be possible.
  • Use the Save icon Save to create an API URL.

When calling the API URL, SoSci Survey expects one of the following identification features for the (possibly new) address entry to be transmitted via GET or POST:

  • email e-mail address
  • mobile mobile number for SMS dispatch
  • uid Unique identifier for the addressee

If the API URL is https://www.soscisurvey.de/PROJEKT/?act=83w7vaYqaeakXH7axpH2Yexu , a valid call might look something like this. An identifier (uid, user ID) is used as an identification feature:

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

If a matching entry is found in the address list, it is used. Otherwise a new entry will be created in Send invitationsAddress list.

SoSci Survey now creates a valid participation link and returns it in response to the call as JSON.

Return Value

The answer to a valid request could look something like this:

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

If successful, the field result contains the value ok, otherwise a different value. In addition, an error message is returned in error. Here, for example, is the answer to a call without an identification feature:

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

Manual recall

The API access is designed for an automated call by an external software (machine-to-machine communication), can also be “abused” to create manually valid participation links.

To do this, create an API link as described above. Then call the API URL with different identification features. For example, with the identifiers respondent01, respondent02, respondent03, …

The participant ID must be entered manually in the address line.

  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

Your browser displays a valid participation URL after each call, which can be sent to the participants by e-mail, for example.

A feature to automatically create a larger number of participation links without external software is planned, but currently only with low priority. If anonymity is not critical (or if it is particularly critical), the serial numbers feature can be used.

en/survey/mailing-api.txt · Last modified: 03.09.2018 19:59 by admin
 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
Driven by DokuWiki