Launch opportunity
Launches a draft opportunity: charges your organization's balance and starts recruiting.
The charge is the participant incentive for every one of num_participants plus the platform
fee, as pricing on the draft shows, and funding says beforehand whether the balance covers
it. The response is the opportunity, already active, so there is nothing to poll for.
Only a draft can be launched; any other status returns 409. A draft that cannot run is
refused with 412 before anything is charged, and the message says what to fix: the balance
does not cover the charge, the screener is missing or nobody can pass it, the participant
budget is under the $5 minimum, or the feasibility request it was priced from is not
answered yet. Unused budget is refunded when the opportunity is stopped or completes.
A screener is recommended. A draft without screening_questions launches only when Terac has
enabled that for your organization and you send without_screener: true. Unless Terac runs its
AI screening interview on it, everyone who matches its filters then goes straight to the task, so
the tasks that deliver the work have to be review_type: manual_review and
customer_screening_review has to be auto_invite: nobody is paid until you approve their
submission with POST /submissions/{submissionId}/approve.
Authorization
apiKey API key as Bearer token: Authorization: Bearer
In: header
Path Parameters
ID of the opportunity, as returned by POST /opportunities or GET /opportunities.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://terac.com/api/external/v2/opportunities/string/launch" \ -H "Content-Type: application/json" \ -d '{}'{
"id": "h7k2p9w4c1v6n3x8b5m0q2rt",
"title": "How finance teams choose spend software",
"internal_title": null,
"description": "Tell us how your team chose and rolled out its spend management software. Eight written questions, about 30 minutes.",
"status": "active",
"num_participants": 12,
"estimated_duration_minutes": 30,
"filters": [
{
"multi_select--country": {
"$in": [
"US",
"CA"
]
}
},
{
"multi_select--seniority": {
"$in": [
"manager",
"senior-manager",
"director"
]
}
}
],
"screening_questions": [
{
"key": "chose_tool",
"text": "Were you involved in choosing your company's current spend management software?",
"pick": "one",
"answers": [
{
"text": "Yes, I led or approved the decision",
"qualify_logic": "must"
},
{
"text": "Yes, I gave input",
"qualify_logic": "must"
},
{
"text": "No",
"qualify_logic": "reject"
}
]
}
],
"quotas": [],
"cross_quotas": [],
"tasks": [
{
"sequence": 1,
"task_type": "interview",
"review_type": "manual_review",
"task_url": "https://research.example.com/studies/spend-software",
"participant_url_template": "https://research.example.com/studies/spend-software?submissionId={submissionId}&teracSubmissionId={submissionId}&taskId={taskId}",
"title": "Written interview",
"description": "Answer the eight questions on the interview page, then submit it.",
"duration_minutes": 30
}
],
"pricing": {
"cost_per_participant_cents": 6250,
"total_cost_cents": 75000,
"currency": "usd"
},
"device_types": [
"desktop",
"mobile_ios",
"mobile_android",
"other"
],
"business_type": "b2b",
"candidate_profile": null,
"required_accounts": [],
"video_required": "none",
"screen_share_required": "none",
"customer_screening_review": "auto_invite",
"pay_frequency": "one_time",
"screening_option_randomization": "disabled",
"forwarding_email_enabled": "disabled",
"max_responses_per_expert": null,
"feasibility_request_id": "tz4a98xxat96iws9zmbrgj3a",
"project_id": "m4q8x2zc7tn1v0bk5r9wh3jd",
"created_at": "2026-09-28T15:10:05.903Z",
"updated_at": "2026-09-29T09:30:12.311Z",
"ending_at": "2026-10-04T09:30:12.311Z",
"launched_at": "2026-09-29T09:30:12.311Z",
"links": {
"self": "/api/external/v2/opportunities/h7k2p9w4c1v6n3x8b5m0q2rt",
"launch": null,
"submissions": "/api/external/v2/opportunities/h7k2p9w4c1v6n3x8b5m0q2rt/submissions",
"dashboard": {
"study": "https://terac.com/acme-research/customer-research-mg4q7x2a/opportunities/h7k2p9w4c1v6n3x8b5m0q2rt",
"draft_editor": null,
"submissions": "https://terac.com/acme-research/customer-research-mg4q7x2a/opportunities/h7k2p9w4c1v6n3x8b5m0q2rt/submissions",
"recruitment": "https://terac.com/acme-research/customer-research-mg4q7x2a/opportunities/h7k2p9w4c1v6n3x8b5m0q2rt/recruitment",
"task": "https://terac.com/acme-research/customer-research-mg4q7x2a/opportunities/h7k2p9w4c1v6n3x8b5m0q2rt/task",
"settings": "https://terac.com/acme-research/customer-research-mg4q7x2a/opportunities/h7k2p9w4c1v6n3x8b5m0q2rt/settings"
}
},
"submission_stats": {
"total": 0,
"in_progress": 0,
"awaiting_review": 0,
"approved": 0,
"rejected": 0
}
}{
"code": "BAD_REQUEST",
"message": "Invalid input data",
"issues": []
}{
"error": {
"code": "UNAUTHORIZED",
"message": "API key required. Include Authorization: Bearer <key> header."
}
}{
"error": {
"code": "FORBIDDEN",
"message": "This account is not permitted to use the API."
}
}{
"code": "NOT_FOUND",
"message": "Not found",
"issues": []
}{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Retry after 61 seconds."
}
}{
"code": "INTERNAL_SERVER_ERROR",
"message": "Internal server error",
"issues": []
}Delete a draft opportunity DELETE
Deletes a draft opportunity, which was never charged, and drops it from `GET /opportunities`. A launched opportunity returns 409; end one with `POST /opportunities/{opportunityId}/stop` instead.
Pause opportunity POST
Pauses an active opportunity, so it stops taking new applicants. Participants already working can still finish and submit, and nothing is charged or refunded. Resume it with `POST /opportunities/{opportunityId}/resume`. Only an `active` opportunity can be paused; any other status returns 409.