Recruitment integrations

How to run an Open Lab study with participants recruited elsewhere — a panel, a university pool, or a lab recruitment system. Two things have to happen: the provider's ID has to reach your session, and the provider has to be told, at the end, that the participant finished.

The whole mechanism, once

There is no provider-specific code in Open Lab. Every integration on this page is built from the same two generic features, which is why a provider that is not listed here will usually still work: read the two halves below and translate the names.

Inbound — carrying an ID into the session

Anything you add to the query string of your study link travels with the participant through the whole session. If your study link is https://app.open-lab.online/studies/ABCDE, then the provider sends people to:

https://app.open-lab.online/studies/ABCDE?survey_code=%SURVEY_CODE%

survey_code is a name you invent. %SURVEY_CODE% is a placeholder the provider replaces with this participant's real value. Open Lab stores whatever arrives on the participant's record, where you can:

see it on the study's Participants page — Columns → Custom parameters, which lists the parameters that have actually arrived, so the column appears only after your first test run;
read it in your data export alongside every response;
send it back to the provider at the end, which is the other half.

Parameters must be named

A value on its own — a link ending in ?%SURVEY_CODE% — has nothing to store it under and is dropped. Every parameter needs a name=value pair.

Outbound — telling the provider they finished

There are two ways, and providers accept one or both.

A redirect. Add a Redirect component as the last component of your study, pointing at the completion URL the provider gives you. On a same-tab redirect the completion is recorded before the participant leaves, so nothing is lost by them ending the session elsewhere.
Whether you also need to send anything back in that URL depends entirely on the provider: Sona wants its survey code, Prolific wants nothing at all.
The editor takes a URL either way round. Providers that hand you a finished URL with a placeholder in it — Paste a completion URL — keep everything they gave you, and you point at the placeholder to say which value comes from the session. Providers that give you a bare endpoint — Build the URL — get a query string you assemble yourself.
A completion code. Turn on Generate completion code in the Study Builder (participant settings; it is off by default) and switch on Show completion code on this page for your Ending page. Each participant then sees a unique ten-character code. The codes are stored on the participant records and are included in the Participants export, so you can check them in bulk.

“Completion code” means two different things

Open Lab's feature issues a different code to every participant. That is what MTurk's Survey Link HITs want, and it is what makes a lab session reconcilable afterwards.

Prolific and CloudResearch Connect also offer a “paste this code” method, but theirs is one fixed code for the whole study. Switching our feature on there breaks approval, because every participant reports something the provider has never seen. Put the provider's single code into the text of your Ending page and leave the feature off.

What each provider expects

The two halves combine differently for each one. This is the whole difference between the pages below.

Provider	Carries in	Wants back	Redirect parameters
Sona Systems	A survey code, under a name you choose	The same code, on its completion URL	One
Prolific	PROLIFIC_PID (and optionally study / session ids)	Nothing — arrival at the study-level completion URL is the signal	None
CloudResearch Connect	participantId, spelled exactly	Arrival at its redirect URL; some projects also want the id back	None, or one
MTurk (Survey Link)	Nothing arrives on its own	Open Lab's per-participant completion code, pasted by the worker	No redirect
ORSEE, hroot, eRecruit	Optionally your own pool identifier	Nothing — there is no crediting callback	No redirect

Providers

Sona SystemsAutomatic

University credit pools. Automatic credit granting by redirect.

ProlificAutomatic

Paid participants. A redirect to your study's own completion URL — with no parameters to configure at all.

CloudResearch ConnectAutomatic

Paid participants. A redirect, or Connect's own fixed code — which is not Open Lab's completion code.

Amazon Mechanical TurkCode only

Survey Link HITs, where the worker pastes a completion code. Frame-based HITs are not supported.

Lab recruitment systemsLink only

ORSEE, hroot, eRecruit. No crediting callback exists: you paste the study link into the invitation, and confirm attendance your own way.

Using something else — Testable Minds, Positly, Respondent.io, Clickworker, SoSci Panel? Read the two halves above and map them onto your provider's own instructions: if it gives you a completion URL, use the redirect; if it asks the participant for a code, use the completion code.

Copy the URLs, don't type them

Completion URLs and parameter names change, and a stale one fails quietly — the study runs, the participant finishes, and no credit is granted. Two real examples: Prolific moved its domain from .co to .com, and the Sona help page for Open Lab still describes a version of this platform that no longer exists.

So take the completion URL from your own study's settings inside the provider, every time, and treat any URL written in a guide — this one included — as an illustration of the shape, not as something to paste.

What Open Lab cannot do

Worth knowing before you design the study, rather than after.

It cannot send screened-out or quota-full participants to a different URL. Branching in Open Lab assigns participants at random, by probability; it cannot route on their answers. A study therefore has one terminal redirect for everybody. Market-research marketplaces such as Cint, Lucid and Dynata require three separate terminal redirects — complete, screen-out, quota-full — so they cannot be integrated today. The same limit applies to a provider's own multi-outcome codes, such as Prolific's completion paths.
Redirects are ordinary links, so they cannot submit a form. This is what rules out MTurk's frame-based ExternalQuestion HITs, which expect a POST. The Survey Link HIT works — see the MTurk page.
Nothing is provider-aware. Open Lab will not warn you that a completion URL looks wrong, because it does not know what any provider's URLs look like. Always take a study once yourself through the provider's own preview link before releasing it.

Testing an integration

Start from the provider, not from Open Lab
The ID only exists once the provider generates it, so a plain Open Lab link cannot exercise the round trip. Use the provider's preview or test link.
Check the parameter arrived
On the study's Participants page, enable the parameter's column under Columns → Custom parameters. Filled means the inbound half works.
Check the provider registered the finish
Look for the credit, the approved submission, or the code in the provider's own interface. Empty column means the link is wrong; filled column but no credit means the redirect is.

Invitation management — where the study link lives.
lab.js integration — link parameters are also readable inside a lab.js task at run time.
Participant management — completion codes, custom parameter columns, exports.