====== API access for personalized participation links ======

The feature **Send Invitations** → **API access** allows the following functions: 

  * To enter an e-mail addresses or other participant IDs from external software in the **List of Contacts** 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. \\ 
  * Retrieve the participation status for a serial mail..\\

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 [[:en:survey:mailing|send a serial mail]]. As an alternative, use [[:en:survey:serials]] to manually create personalized links, but with restrictions on anonymity and functionality - and access codes (serial numbers) require a different [[:en:create:access|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, this does not necessarily send an e-mail. If no serial mail is to be sent, not even an e-mail address is necessary.


===== Create Address Entries =====

  * First, create a new serial mail under **Send invitations** → **Serial mail**. This is not necessarily sent: whether or not can be determined later. But here you can make all settings for the link and check the participation status.
   *Subsequently, then select this // serial email // under **Send invitations**  → **API 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 ([[:en:results:variables|SERIAL]]) and e-mail address should be possible. 
  * Use the Save icon {{:button.save.png?nolink|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 (ASCII characters only)

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 **List of Contacts**, it is used. Otherwise a new entry will be created in the **List of Contacts**. 

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: 

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

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:

<code javascript>
{
  "result": "error", 
  "error":  "Request must specify email, mobile, or uid",  
  "url":    null
}
</code>


==== 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 [[:en:survey:mailing#serial numbers|serial numbers]] feature can be used.



===== Participation Status Serial Number =====

  * Under **Send invitations** -> **API access** at //Function//, select that you want to query the status of a serial number.
  * With the save icon {{:button.save.png?nolink|Save}} you then create an API URL.

When calling the API URL, SoSci Survey expects a parameter //serial// to be submitted with the serial number to be checked.

If the API URL is ''%%https://www.soscisurvey.de/PROJEKT/?act=exu83w7vaYqaeakXH7axpH2Y%%'', a valid call to check the serial number "CD246802" might look something like the following.

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

The return value is a JSON string with the following structure:

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

The attributes have the following meaning:

  * ''result'' -- Return value of the request, can take the value "ok" or "error".
  * ''code'' -- The queried serial number
  * ''started'' -- Was the serial number used to start a questionnaire (boolean)
  * ''completed'' -- If the started questionnaire was filled in to the last page (boolean)
  * ''notice'' -- A note possibly stored for the serial number
  * ''error'' -- Error message if ''result'' has the value "error
    * "not found" -- The serial number searched for is not known in the survey project

In case of an error only the status code and an error message are returned, if available also the requested serial number:

<code javascript>
{
  result:    "error",
  error:     "not found",
  code:      "CD246802"
}
</code>

===== Participation Status for Address Entries =====

  * Under **Send invitations** -> **API access** at //Function//, select that you want to query the status of an address entry.
  * With the save icon {{:button.save.png?nolink|Save}} you then create an API URL.


When calling the API URL, SoSci Survey expects at least one parameter to identify the address entry. If multiple properties are specified, the system searches for an address entry that has all properties. The address entry can be searched for using the following properties:

  * ''serial'' -> Person code of the address entry
  * ''email'' -> Email address
  * ''mobile'' -> Mobile phone number
  * ''uid'' -> Unique ID of the address entry

If the API-URL is ''%%https://www.soscisurvey.de/PROJEKT/?act=erSoqORu4OPzGeWyetpwmbMu%%'', a valid call to check for the participation status may look like this.

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

In return you get a JSON-String with this structure:

<code javascript>
{
  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
}
</code>

The search parameters used are returned in the first part of the response.

The participation status is specified for each serial mail for which sending to this address entry was attempted. The key used for the ''mailings'' is "M" and the ID of the serial mail.

In the event of an error, only the status code and an error message are returned, if available also the requested participation code.

<code javascript>
{
  result:    "error",
  error:     "not found",
  serial:    null
  email:     "nobody@example.com"
  mobile:    null
  uid:       null
}
</code>