Adding custom data to survey responses using External IDs

SurveyLegend has a feature called “External ID” which can be used to add arbitrary data to survey responses. External id can be used for many purposes, for instance identifying an individual respondent (e.g. custom id from your system, email address, name, phone number), grouping respondents together (e.g. consumer, business, government, ngo, control group, age group), tracking where responses came from (e.g. email campaign, social media, store location, country, city, company etc) or any other parameters.

How to add data as external IDs

External ids are part of the survey URL, they are appended at the end of long survey links as query parameters, e.g https://s.surveylegend.com/-ABC123?param1=value1&param2=value2 Parameter names and values of the external id should be url encoded, e.g. param1, value1, param2 and value2 in the query string. It’s easier to read the and understand the external id when used with characters that do not need to be url encoded. This includes uppercase and lowercase letters (A-Z), decimal digits (0-9), hyphen “-” , period “.” , underscore “_”, and tilde “~”.

Generating links with external IDs

There is a link generator in the Share step of SurveyLegends survey editor. Type the external id in the field and an appropriate link will be generated, parameter names and values will be correctly URL encoded.

Note:

External IDs are not passed along when the short link, (e.g. https://s.surveylegend.com/s/1234) is expanded to a long link, the survey will load but the external id will not be saved. Therefore always use the long link together with Exernal IDs.

Generate a link with an External ID

[email protected]

https://s.surveylegend.com/-Jpad3fUCbypMQpg8gcQ?john-legend%40example.com

Tip:

To view then long link of a survey, open the short link in another browser tab. Add the external id to that link.

Note:

It’s possible to use spaces in an external id as long as they are URL encoded e.g, spaces will become %20. Consider using hyphens/dashes (-) or underline (_) to separate words instead of spaces.

Limitations

SurveyLegend does not impose any limits on the length or contents of the external id values. However there are limitations in how browsers (e.g. Chrome, Firefox, Safari, Edge, Internet Explorer) handle URLs. Internet Explorer 11 has a limit just above 2000 characters for a URL, more modern browsers have a much higher limit. To make sure that the survey loads and works for the widest possible audience, keep the entire survey link at 2000 characters, URL encoded of course. When characters are not URL encoded they might not be saved exactly as they looked like in the URL. Some characters are reserved, such as & and ?, and might result in some part of the external id not being included.

Examples of external ids

General structure

Multiple parameters with only values:

https://s.surveylegend.com/-ABC123?value1&value2&value3

Multiple parameters with parameter names and values:

https://s.surveylegend.com/-ABC123?param1=value1&param2=value2

Multiple parameters with mixed with parameter names, values and only values:

https://s.surveylegend.com/-ABC123?param1=value1&param2=value2&value3

Emails

An email directly appended after the survey id ([email protected], %40 is the @ sign url encoded):

https://s.surveylegend.com/-ABC123?my-email%40test.com

Email with a parameter name:

https://s.surveylegend.com/-ABC123?email=my-email%40test.com

Urls

Pass url as query parameter, this is a bit contrived example including https:// in the url, it’s to clearly illustrate that the value should be url encoded.

https://s.surveylegend.com/-ABC123?source=https%3A%2F%2Fwww.surveylegend.com%2Ftour

(/tour%20url%20encoded)

Real world examples

For instance when loading a survey on a tablet in a store for shoppers to participate.

https://s.surveylegend.com/-ABC123?type=in-store&location=new-york
https://s.surveylegend.com/-ABC123?type=kiosk&location=washington
https://s.surveylegend.com/-ABC123?type=booth&location=san-francisco

Tracking source of respondents

A survey can be shared using several different platforms, e.g. social media, email, embedded in a webpage, sms. printed media with QR-code etc. Some researchers might not be interested in tracking each individual respondent, but might prefer to instead analyze the traffic and see from which sources responses are coming from. Use the source as external ID, for instance:

https://s.surveylegend.com/-ABC123?facebook
https://s.surveylegend.com/-ABC123?twitter
https://s.surveylegend.com/-ABC123?linkedin
https://s.surveylegend.com/-ABC123?instagram

https://s.surveylegend.com/-ABC123?sms
https://s.surveylegend.com/-ABC123?qr-code
https://s.surveylegend.com/-ABC123?print
https://s.surveylegend.com/-ABC123?magazine
https://s.surveylegend.com/-ABC123?my-partner
https://s.surveylegend.com/-ABC123?my-site

https://s.surveylegend.com/-ABC123?source=email-campaign1
https://s.surveylegend.com/-ABC123?source=link-from-banner2
https://s.surveylegend.com/-ABC123?source=website2

Groups

https://s.surveylegend.com/-ABC123?age-group=18-25
https://s.surveylegend.com/-ABC123?age-group=50-65

https://s.surveylegend.com/-ABC123?group=control
https://s.surveylegend.com/-ABC123?group=a
https://s.surveylegend.com/-ABC123?group=b

Using only query parameters to load survey and include external id

Using only query parameters is also possible in case it might be needed or convenient.

https://s.surveylegend.com/?survey_id=123&param1=value1
https://s.surveylegend.com/?surveyId=123&param1=value1

Legacy external ids

Previously SurveyLegend surveys used longer links which included some redundant information. The hash (#) and the user id with first tilde (~) are removed in the new format of survey links. Legacy long link

/survey/#/user_id~survey_id

External ID using tilde (~) as separator

/survey/#/user_id~survey_id~external_id1~external_id2

Mixed usage of tilde (~) and query parameters

/survey/#/user_id~survey_id~external_id1~external_id2?param1=value1&param2

All links with the legacy structure will continue to work just as before. When opening a link with the legacy structure it will quickly change into a link with the new structure in the browsers bar.

Note:

Links starting with /survey/{id} are now redirecting to https://s.surveylegend.com/{id} using 301 redirects, which means that if a /#/ is used the id is dropped since the server does not recieve it. Previously the legacy redirects were handled using javascript, that is no longer maintained, since it was deprecated over 3 years ago. https://s.surveylegend.com can not handle links with a hash (/#/) in them. It will redirect to www.surveylegend.com.

How to view External IDs

There are several ways to view external IDs.

Individual responses

The External ID can be viewed after selecting a response in Individual Responses view of SurveyLegend, in the Metrics tab. The illustration above shows an example of what is shown under the Metrics tab in the Individual Responses view. External ID will also be included when an individual response is exported to PDF.

Export of responses to Excel, CSV or ODS

When exporting responses to a dowloadable file, External IDs will all be in one column, they will look just like in the link of the survey.

A	B	C	…	Z
Did you come to our seminar last week?	How satisfied are you with the following aspects of the seminar?	What is your current position?	…	External id
Yes	Satisfied	Supervisor	…	[email protected]
Yes	Satisfied	Marketing	…	[email protected]
No	N/A	Accounting	…	[email protected]
Yes	Very satisfied	IT	…	[email protected]

* The above data is fake. The above table shows an example of a downloaded spreadsheet file. First row shows survey questions, and each of the next rows represent one respondent. It’s possible to split up the External ID column into several other columns in Excel or LibreOffice. Use amperesand (&) or tilde (~) character as delimiter. The cells might need some more processing in case param=value format is used.

Google Sheet integration

External IDs will also be in a separate column in the connected Google Sheet.

API

External IDs can be accessed as externalId property on each survey response retrieved from the SurveyLegend API. API call

GET https://api.surveylegend.com/responses/surveys/{surveyId}

Response:

  
[
	..., 
	{
		..., 
		externalId: "param1=value1&param2=value2&param3",
		...	
	},
	...
]

API documentation