This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
en:survey:mailing-api [03.09.2018 19:59] – [Return Value] admin | en:survey:mailing-api [10.12.2023 21:18] (current) – admin | ||
---|---|---|---|
Line 3: | Line 3: | ||
The feature **Send Invitations** → **API access** allows the following functions: | 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 address list of the survey project.\\ | + | * To enter an e-mail addresses or other participant IDs from external software in the **List of Contacts** |
* Optionally, to trigger the sending of individual serial emails, also automated by an external software.\\ | * 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. \\ | * 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. | 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. | ||
Line 12: | Line 13: | ||
===== Background ===== | ===== Background ===== | ||
- | Usually, SoSci Survey creates a personalized URL to participate in a survey in the moment you [[: | + | Usually, SoSci Survey creates a personalized URL to participate in a survey in the moment you [[: |
- | 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, | + | 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, |
- | ===== Use ===== | + | ===== Create Address Entries |
- | * First, create a new serial mail under **Send invitations** → **Serial mail**. This mail is not sent, but here you can make all settings for the link and check the participation status. | + | * First, create a new serial mail under **Send invitations** → **Serial mail**. This is not necessarily |
| | ||
* Use the Save icon {{: | * Use the Save icon {{: | ||
Line 26: | Line 27: | ||
* //email// e-mail address | * //email// e-mail address | ||
* // | * // | ||
- | * //uid// Unique identifier for the addressee | + | * //uid// Unique identifier for the addressee |
If the API URL is '' | If the API URL is '' | ||
Line 32: | Line 33: | ||
https:// | https:// | ||
| | ||
- | If a matching entry is found in the address list, it is used. Otherwise a new entry will be created in **Send invitations** → **Address list**. | + | 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. | SoSci Survey now creates a valid participation link and returns it in response to the call as JSON. | ||
- | ===== Return Value ===== | + | ==== Return Value ==== |
The answer to a valid request could look something like this: | The answer to a valid request could look something like this: | ||
Line 61: | Line 62: | ||
- | ===== Manual recall | + | ==== Manual recall ==== |
The **API access** is designed for an automated call by an external software (machine-to-machine communication), | The **API access** is designed for an automated call by an external software (machine-to-machine communication), | ||
Line 79: | Line 80: | ||
+ | ===== Participation Status Serial Number ===== | ||
+ | |||
+ | * Under **Send invitations** -> **API access** at // | ||
+ | * With the save icon {{: | ||
+ | |||
+ | 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:// | ||
+ | |||
+ | The return value is a JSON string with the following structure: | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | result: | ||
+ | code: " | ||
+ | started: | ||
+ | completed: false, | ||
+ | notice: | ||
+ | error: | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | The attributes have the following meaning: | ||
+ | |||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * "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: | ||
+ | code: " | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | ===== Participation Status for Address Entries ===== | ||
+ | |||
+ | * Under **Send invitations** -> **API access** at // | ||
+ | * With the save icon {{: | ||
+ | |||
+ | |||
+ | 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: | ||
+ | |||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | |||
+ | If the API-URL is '' | ||
+ | |||
+ | https:// | ||
+ | |||
+ | In return you get a JSON-String with this structure: | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | result: | ||
+ | serial: | ||
+ | email: | ||
+ | mobile: | ||
+ | uid: null | ||
+ | mailings: { | ||
+ | M1: { | ||
+ | id: 1 | ||
+ | status: | ||
+ | statusMail: " | ||
+ | statusSMS: | ||
+ | sendTime: | ||
+ | }, | ||
+ | M2: { | ||
+ | id: 2 | ||
+ | status: | ||
+ | statusMail: " | ||
+ | statusSMS: | ||
+ | sendTime: | ||
+ | } | ||
+ | }, | ||
+ | error: | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | 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 '' | ||
+ | |||
+ | 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: | ||
+ | serial: | ||
+ | email: | ||
+ | mobile: | ||
+ | uid: null | ||
+ | } | ||
+ | </ | ||