# External Surveys & Redirect URLs (https://terac.com/docs/researchers/integrations/external-surveys)

Connect a third-party survey or task tool to Terac so completions, screen-outs, and over-quota exits are tracked automatically.

When your task lives on another platform (a Qualtrics or SurveyMonkey survey, your own product, or a hosted usability test), Terac sends qualified participants to that platform and needs to know how each one finished. Redirect URLs are how the two platforms talk to each other.

This is the most common setup question for teams running their own survey or task tool, so it is worth getting right before you launch.

## How It Works [#how-it-works]

Terac sends participant → Participant completes task → Your tool redirects back → Terac records the result

1. A qualified participant clicks through to your survey. Terac appends their **submission ID** to the task URL.
2. The participant completes (or is screened out of) your survey.
3. At the end, your survey **redirects the participant's browser** back to Terac's callback URL with the submission ID and a result.
4. Terac records the outcome and moves the submission to **Work review**, **Approved** or **Rejected**, depending on the result and the task's review type.

> The callback is a browser redirect, not a server-to-server webhook. Your
> survey tool only needs to send the participant's browser to a URL when
> they finish. No API call or authentication is required.

## Step 1: Capture the Submission ID [#step-1-capture-the-submission-id]

When Terac forwards a participant to your task URL, it appends these query parameters:

| Parameter           | Description                                            |
| ------------------- | ------------------------------------------------------ |
| `teracSubmissionId` | The participant's unique submission ID (preferred key) |
| `submissionId`      | The same value, for tools that read this key instead   |
| `taskId`            | The ID of the task within the opportunity              |

Configure your survey tool to **capture `teracSubmissionId`** as a hidden field or embedded data value so you can pass it back at the end. Both `teracSubmissionId` and `submissionId` carry the same value, so either one works.

Enter your task link exactly as your survey tool gives it to you. Terac adds the parameters above on the way out, so there is no need to append `teracSubmissionId` to the link yourself.

### Putting the ID in your own parameter [#putting-the-id-in-your-own-parameter]

Some tools identify participants through a parameter of their own, and hand you a link with that parameter left blank — for example `…&sourceId=terac&sourceParticipantId=`. **Paste it as-is:** a link that ends in an empty parameter gets the submission ID filled into it for each participant.

To place the ID anywhere else — a parameter that is not last, or a segment of the path — write `{TERAC_SUBMISSION_ID}` where the value belongs:

```
https://app.example.com/sample/collect?sourceParticipantId={TERAC_SUBMISSION_ID}&sourceId=terac
```

`{TERAC_TASK_ID}` works the same way for the task ID. Both work on any link, and the parameters from the table above are still appended alongside your own.

> **Warning**
>
> Some survey tools drop unknown query parameters on their hosted pages. If
> yours does, the submission ID will not reach your survey. Tell your Terac
> contact which tool you use and we will configure a pass-through for it.

## Step 2: Redirect Back on Completion [#step-2-redirect-back-on-completion]

At the end of your survey, redirect the participant to:

```
https://terac.com/api/external/callback?teracSubmissionId={{teracSubmissionId}}&result=completed
```

Replace `{{teracSubmissionId}}` with the submission ID you captured in Step 1. The same base URL is used for every study, so you only configure it once per survey tool.

### Result Values [#result-values]

Set `result` to match how the participant finished:

| `result`       | Use when                                                      | Effect on the submission                 |
| -------------- | ------------------------------------------------------------- | ---------------------------------------- |
| `completed`    | The participant finished the survey                           | Depends on the task's review type, below |
| `screened_out` | The participant failed your in-survey screener                | Rejected, with the reason screened out   |
| `quota_full`   | The relevant quota was already full when they arrived         | Rejected, with the reason quota full     |
| `rejected`     | The participant was disqualified for quality or fraud reasons | Rejected                                 |

If `result` is omitted, Terac assumes `completed`.

### `completed` Does Not Mean Approved [#completed-does-not-mean-approved]

A completion redirect tells Terac the work was **done**, not that it was acceptable. What happens next is set by the task's review type, which is a per-task setting:

| Task review type | Shown in the builder as | Where a `completed` redirect leaves the submission       |
| ---------------- | ----------------------- | -------------------------------------------------------- |
| `manual_review`  | not offered, API only   | **Work review**, waiting for you to approve or reject it |
| `auto_approve`   | Needs approval          | **Approved**, and the participant is paid                |
| `self_report`    | Expert approves         | **Approved**, and the participant is paid                |

Once they have opened your survey, participants also see an **I completed the task** button on Terac, unless Terac has turned it off for your organization. On a `self_report` task it approves the submission and pays the participant, with no redirect needed. On the other two it moves the submission to **Work review**, and on an `auto_approve` task a `completed` redirect then approves it.

### Reviewing external work before anyone is paid [#reviewing-external-work-before-anyone-is-paid]

`manual_review` is the review type that holds a completed submission for you, and today it is only settable **through the API**:

```json
{
  "sequence": 1,
  "task_type": "interview",
  "review_type": "manual_review",
  "task_url": "https://…"
}
```

Send the `completed` redirect as normal. It moves the submission into Work review, and you approve or reject it yourself, in the dashboard or with `POST /submissions/{submissionId}/approve`.

An opportunity launched without a screener has to use `manual_review` on its survey task, unless Terac runs its AI screening interview on it. Everyone who matches its filters reaches your survey, so a redirect alone must never be what pays them. In the dashboard, launching such an opportunity sets its **Needs approval** tasks to `manual_review` for you. See [Launching Without a Screener](https://terac.com/docs/developers/guides/screening-questions#launching-without-a-screener).

> **Warning**
>
> On every other opportunity, the dashboard's task builder does not offer
> `manual_review`. Its picker has two options, and on a task with a URL both
> settle the submission from the redirect without waiting for you: **Needs
> approval** pays out on a `completed` callback, and **Expert approves** lets
> the participant approve their own work. A task that stored `manual_review`
> still shows as **Needs approval** there, with Redirect URLs that say a
> completed redirect waits for your approval, and changing its link or its
> review setting in the builder replaces `manual_review` with one of those two.
>
> So if gating payout matters to you, build the task through the API, and leave
> its link and review setting alone in the builder. Tell us if you need this in
> the dashboard.

The callback itself can never approve a `manual_review` task, whichever way it was created. That part is deliberate: the callback is an unauthenticated browser redirect, and anything a participant's own browser can trigger must not release payment for work you have not seen.

> Set up redirects for every exit path your survey can take, not just
> completion. Without a `screened_out` or `quota_full` redirect, those
> participants look the same as people who simply abandoned the survey.

## Step 3: Test Your Redirect [#step-3-test-your-redirect]

Right after you launch, before participants reach your survey, check the redirect yourself. On the opportunity's **Task** tab, find the task's **Redirect URLs** and click **Run a demo redirect**. We open your task link in a new tab with a demo ID added to it, in place of a real submission ID (`teracSubmissionId=demo_…`). Your redirect sends it back like any other ID, so you don't need to add the demo ID anywhere.

Using the API or MCP? Once the opportunity is live, its response includes `links.dashboard.task`. Open that link and run the demo there.

Go through your survey and exit the way you want to test. When your tool redirects back, you see either **Your redirect works**, or what your tool sent and the redirect URL to use instead. Run it again for each exit path.

> A demo run records nothing in Terac and no participant is affected. It does
> create a real response in your own tool, marked with `demo_run`, so you can
> find and delete it there.

## What Happens Without Redirect URLs [#what-happens-without-redirect-urls]

If a participant reaches your survey but Terac never receives a callback, the submission has no completion signal from your tool. It stays **In Progress** until the participant clicks **I completed the task**, which moves it to **Work review**, or approves it on a `self_report` task.

On an opportunity with **redirect URLs enabled**, a submission sitting in Work review with no callback evidence is **auto-rejected after 6 hours**. Setting up the completion redirect is what prevents qualified participants from being auto-rejected and keeps your recruitment moving.

The same 6-hour sweep never approves a `manual_review` task. One that reached Work review through a `completed` redirect stays there until you decide, however long you take over it.

### Is Redirect URLs Enabled On My Opportunity? [#is-redirect-urls-enabled-on-my-opportunity]

Almost certainly not, unless you asked us to turn it on.

It is a per-opportunity setting that is **off by default**, and it is not currently self-serve: there is no toggle in the dashboard and no field on the API, so it can only be switched on by Terac. Ask us if you want it.

While it is off, nothing is auto-rejected for a missing callback. A participant who clicks **I completed the task** without your survey sending them back waits in Work review for you to resolve, and one who never comes back stays In Progress. That is the behaviour to assume unless you have arranged otherwise.

Configuring the `completed` redirect is worth doing either way. On an `auto_approve` task it is what approves finished work without you, and on a `manual_review` task it puts finished participants in front of you without relying on them to click anything.

## Setup Checklist [#setup-checklist]

* [ ] Your task URL accepts a query parameter and your tool keeps it through to the end of the survey
* [ ] Your survey captures `teracSubmissionId` as hidden / embedded data
* [ ] The end-of-survey redirect points to the Terac callback URL with the captured ID
* [ ] A `completed` redirect is configured
* [ ] `screened_out` and `quota_full` redirects are configured for those exit paths
* [ ] A demo redirect shows **Your redirect works** for each exit path
* [ ] You ran a soft launch (a few participants) to confirm completions show up before scaling to your full sample

> Run a small soft launch first. Send a handful of participants through and
> confirm they appear as Completed in the Submissions tab before opening the
> study to your full target.

## What's Next? [#whats-next]

- [Submissions](https://terac.com/docs/researchers/results/submissions): Track submission states and completion
- [Reviewing Work](https://terac.com/docs/researchers/results/reviewing-work): How approvals and auto-review work
- [API Keys](https://terac.com/docs/researchers/integrations/api-keys): Programmatic access to Terac