Recruitment and embedding

Participation links

Once a study is published, share its participation link:

r = client.recruitment.get(study.id)
print(r.participation_url)
print(r.short_participation_url)

If the study has voice_enabled or video_enabled set, you’ll also get voice_participation_url and video_participation_url, each with a short variant.

Custom short links, quotas and redirects

client.recruitment.update(
    study.id,
    short_url_slug="onboarding-2026",      # lowercase letters, digits, hyphens; unique across all studies
    max_responses=200,                     # response quota
    redirect_url="https://example.com/thanks?pid={{external_participant_id}}",
)

client.recruitment.update(study.id, clear_max_responses=True)  # remove the quota

The response reports completed_interviews and quota_remaining. Subscribe to the study.full webhook to hear when a study fills up.

Check redirect_url_warning on the response. It’s set when the API has a concern about the redirect URL you saved.

Attribute participants to your own IDs

Add query parameters to any participation link:

Parameter	Recorded on the interview as	Use it for
`source=<tag>`	`web_source`	The campaign or channel the participant came from
`participant_id=<your id>`	`external_participant_id`	Joining the interview back to a user in your system

link = f"{r.participation_url}&source=newsletter&participant_id={user.id}"

Then look the person up later:

found = client.interviews.find_by_external_id(study.id, external_participant_id=str(user.id))
for interview in found.interviews:
    print(interview.id, interview.completed, interview.web_source)

You can also filter interviews.list, transcripts.list, transcripts.search and webhooks.list_deliveries by external_participant_id. Any redirect_url can include {{external_participant_id}} to pass the ID on.

participant_id and source come from the link, so a participant can change them. Don’t treat them as proof of identity. For verified values, use signed embed metadata.

Embed the interview

To run the interview inside your own site or app, create a publishable key for the origins it’ll load on, then generate the install snippet.

Create a key

key = client.embed.create_key(
    allowed_origins=["https://app.example.com"],
    study_id=study.id,  # omit to allow any study in your organization
)
publishable_key = key["publishable_key"]
signing_secret = key["signing_secret"]

create_key is the only time publishable_key and signing_secret are returned. Store them before doing anything else.

Origins must be exact (scheme, host and port). The "*" wildcard isn’t allowed.

Get the snippet

snippet = client.embed.get_snippet(study.id, publishable_key=publishable_key, mode="chat")
print(snippet.snippet)

Paste snippet.snippet into your page. mode sets the widget’s presentation (data-mode) and defaults to chat.

Signed metadata

The basic snippet passes metadata through a data-metadata attribute, which a visitor can edit. When the interview needs to rely on a metadata value, use snippet.signed_snippet. Your server mints a JWS (HS256) token with the key’s signing_secret, and the token’s metadata claim is recorded as verified, overriding any page-supplied value of the same name. Each metadata item on an interview carries its provenance:

for item in client.interviews.get(interview_id).embed_metadata:
    print(item.key, item.value, item.provenance)  # "token" = verified, "client" = page-supplied

Managing keys

for k in client.embed.list_keys().keys:   # secrets are never included
    print(k)

client.embed.update_key(key_id, allowed_origins=["https://app.example.com", "https://staging.example.com"])
client.embed.update_key(key_id, status="revoked")

Get started

Guides

Resources

Participation links

Custom short links, quotas and redirects

Attribute participants to your own IDs

Embed the interview

Signed metadata

Managing keys

​Participation links

​Custom short links, quotas and redirects

​Attribute participants to your own IDs

​Embed the interview

​Signed metadata

​Managing keys

Participation links

Custom short links, quotas and redirects

Attribute participants to your own IDs

Embed the interview

Signed metadata

Managing keys