For unmoderated studies and surveys, researchers usually point participants to an external survey, prototype, or task. The completionUrl is how you get an authoritative signal that a participant finished that task — without moving them to ATTENDED and triggering payout.
This separation matters for API partners. Because the API requires autopay to be enabled, Mark as attended immediately starts the incentive payment. Most partners want to inspect the quality of a response (manually or via automated checks) before paying. completionUrl gives you a clean “task is done, participant is ready for review” signal in between those two states, and it’s visible to both you and the researcher on the screener response.
This page covers:
- What
completionUrl is and what the cc parameter means
- All the ways a task can get marked complete (and what each one is for)
- How task completion relates to marking a participant as attended
What is completionUrl?
When you create a project where targetResearchMethodology is unmoderatedStudy or survey, the project response includes a completionUrl field. It looks like this:
https://app.respondent.io/complete?cc=<projectCompletionId>
completionUrl is generated by Respondent. You cannot set it on create or update — it comes back on the project response.- The
cc query parameter is the project completion ID: a unique identifier that lets Respondent associate the incoming participant with the right screener response on the right project. It is not a participant identifier on its own — Respondent also requires the participant to be signed in to their Respondent account in the same browser session.
You should:
- Place the URL of the external survey, study, or task in
unmoderatedStudyOrSurvey.remoteCommunicationDetails when creating the project (see Project deep dive).
- Configure the survey or task tool to redirect to
completionUrl once the participant finishes.
When the participant lands on completionUrl, Respondent:
- Sets
task.status to complete on their screener response
- Sets
task.completedAt to the current timestamp (this appears on the screener response object — see Mark as attended response schema)
- Stops any pending task-completion reminder emails for that participant
How tasks get marked complete
There are three ways task.status becomes complete on a screener response. Only the first one is something you, as an API partner, plug into directly.
| Path | Who triggers it | When to use |
|---|
Participant hits completionUrl | The participant, redirected from your task tool | The standard path for API partners. The participant finishes the external survey or study and your tool redirects them to completionUrl. |
| First-party integrations (SurveyMonkey, Lookback) | Respondent, server-side | Only relevant when a researcher connects a SurveyMonkey or Lookback task on the Researcher Platform. Respondent receives a webhook from the third party and marks the task complete with the response payload. Not available over the public API. |
| Inferred from “Mark as attended” | You, via the API | If you skip task completion entirely and just call Mark as attended, the participant moves to ATTENDED and payout starts. This does not flip task.status to complete — the two flags are independent — but for projects driven entirely from the API it’s a valid shape if you don’t need the intermediate “task done, review pending” state. |
There is no public API endpoint to mark a task complete directly. If you want Respondent’s UI and the screener response object to reflect “task done” before you decide on payment, the only lever is to send the participant through completionUrl at the end of your external task.
Task complete vs. attended
task.status and screenerResponse.status are independent. Hitting completionUrl only touches task.status; calling Mark as attended only touches screenerResponse.status. Neither one implies the other.
For API partners, that gives you a three-stage lifecycle for unmoderated work:
- Invited — you’ve sent the participant to the task.
- Task complete — they finished the task and were redirected through
completionUrl. task.status = complete, task.completedAt is set, reminder emails stop. The participant has not been paid.
- Attended — you’ve reviewed the response and called Mark as attended. Status moves to
ATTENDED and autopay fires.
A typical lifecycle:
- Researcher creates the project —
completionUrl is returned on the response.
- Participant qualifies, you invite them, they complete the external task.
- The external tool redirects the participant to
completionUrl. Respondent marks the task complete and stops reminders.
- Your system (or a reviewer) inspects the response.
- Once you’re happy, your system calls Mark as attended —
ATTENDED + autopay.
- If the response is unacceptable, call Mark as rejected or Mark as no show instead.
Don’t treat completionUrl as a payment trigger. It’s a “ready for review” signal. Payment only starts when you call Mark as attended.
How cc interacts with the other URL parameters
The cc parameter on completionUrl is separate from the URL parameters that Respondent appends to your remoteCommunicationDetails link (respondent_profile_id, respondent_screener_response_id, and so on).
- The outbound link from Respondent to your task tool carries the
respondent_* parameters so your tool knows which participant and screener response it is dealing with.
- The return link back to Respondent (
completionUrl) carries cc so Respondent can identify which project’s task is being marked complete. The participant identity comes from the signed-in Respondent session, not from cc.
You can pass cc through your survey tool as a hidden field and use it as part of the final redirect, or you can hard-code the project’s completionUrl as the redirect target — both work.
When completionUrl is and isn’t returned
| Methodology | completionUrl returned? |
|---|
unmoderatedStudy | Yes |
survey | Yes |
diaryStudy | No |
oneOnOne, focusGroup, inRespondentHome, inRespondentOffice | No |
