External API

The external API enables you to pass data from external
sources into the system.

This can be used if you do not wish to upload email
addresses into our system. You can replace the email address with a
reference number (custom data) and pass this in via a URL that you
construct.

This feature can be used if you are running a forum and
wish to track the forum members names who take the survey. It allows
you to pass them in via the URL.

External Participant Data

The API currently supports collecting participant data from
external sources. The participants that are collected will appear in
the email list you designate.

Parameter

Description Description

Description

pcol

Participant Collection Enable

This parameter must be set to true
to enable data collection

plid

Participant List ID.

This is the email list ID that your
participant will be inserted into

pe

Participant Email

This is can be set to the
participant's email address. This value must be URL encoded.

pfn

Participant First name

This field can be used to store the
participants first name.

pln

Participants Last name

This field can be used to store the
participants last name.

pca

Participants custom data

This field can be used to store
other information like a user ID.

pu

Enforce unique

This option is used to stop
duplicate participants. If the option to allow participants to return
and edit survey is set it also allows the participant to return to the
survey using the link you provide. This can be useful for sending
reminders to participants.
This value can be set to one of the above fields pe, pfn, pln or pca.

Worked example

Create an empty email list. Once you have an email list you
will need to get the email list ID. from the URL shown in the browser.

Navigate to the email list edit screen

The email list is shown above and highlighted in red. Copy
the email list ID part from the browser URL.

In this example we want to the the email address
customer365@mybigredemailserver.com one this has been URL encoded
becomes: customer365%40mybigredemailserver.com

Use the following table to construct the URL:

Number

Fragment

Description

Example

/?pcol=true

Link to the eSurv.org website.
This is required

/?pcol=true

1

?s=

This parameter contains your
survey ID.

?s=HCIJI_5dddfbb2

2

&plid=

This parameter contains your
email list ID.

&plid=OHKJJ_a271577

3

&pu=

We are forcing the participant
data to be unique. This combined with the return to edit survey setting
allows the participant to return and complete their survey and us to
send them reminders.

&pu=pe

4

&pe=

In this example we are using pe
which contains the participants email address.

&pe=customer365%40mybigredemailserver.com

We have now constructed the following URL/?pcol=true&s=HCIJI_5dddfbb2&plid=OHKJJ_a271577&pu=pe&pe=customer365%40mybigredemailserver.com

You can combine multiple participant details in one link
therefore you could add &pfn=andrew to the end of the URL to
collect the participants first name.

We recommend keeping a log of the URL's you have issued in a
spreadsheet in case you need to issue reminder emails to participants.
The in this case you can simply copy the URL from your spreadsheet into
the email or use the mail merge
feature of your office software.