Launch Project

Launches a project and returns a shareable link ready to send to participants. The link can be embedded in emails, your product, or a QR code.

The project must have a completed interview guide before it can be launched. If you used Create Project, the guide is generated automatically.

Endpoint

Launches a draft project using your organisation's existing credit balance and/or trial credits. Trial credits are consumed first. If your balance is insufficient, top up via the dashboard or contact support — no payment can be taken through the API. `target_participants` overrides the value set at project creation.

Authentication

x-api-key header

Path Parameters

Name	Type	Description
`project_id`*	string	—

Headers

Name	Type	Description
`x-api-key`	string	—

Request Bodyrequired

Field	Type	Description
`target_participants`required	integer	Number of participants to recruit. Overrides the value set at project creation.

Responses

Field	Type	Description
`project_id`required	string	Project Id
`status`required	DRAFTIN_PROGRESSCOMPLETESTARTEDPAUSED	—
`target_participants`required	integer	Target Participants
`trial_credits_used`required	integer	Trial Credits Used
`balance_charged`required	string	Balance Charged
`balance_remaining`required	string	Balance Remaining
`call_url`required	string	Call Url
`recruiting_type`required	string	Recruiting Type

Example request

POST /v1/projects/{project_id}/launch

curl -X POST "https://external-api.prod.insightscompany.io/v1/projects/<project_id>/launch" \
-H "x-api-key: <api_key>" \
-H "Content-Type: application/json" \
-d '{"target_participants": 10}'

Request body

Field	Type	Required	Description
`target_participants`	integer	Yes	Number of participants to recruit. Overrides the value set at project creation.

Example response

Response 200

{
  "balance_charged": "$400.00",
  "balance_remaining": "$600.00",
  "call_url": "https://call.insightscompany.io/en/{interview_id}/{project_id}",
  "project_id": "b2c3d4e5-0000-0000-0000-000000000001",
  "recruiting_type": "INTERNAL",
  "status": "IN_PROGRESS",
  "target_participants": 10,
  "trial_credits_used": 2
}

{
  "project_id": "b2c3d4e5-0000-0000-0000-000000000001",
  "status": "IN_PROGRESS",
  "target_participants": 10,
  "trial_credits_used": 2,
  "balance_charged": "$400.00",
  "balance_remaining": "$600.00",
  "call_url": "https://call.insightscompany.io/en/{interview_id}/{project_id}",
  "recruiting_type": "INTERNAL"
}

Response fields

Field	Type	Description
`project_id`	string	UUID of the launched project
`status`	string	Project status — `IN_PROGRESS` after launch
`target_participants`	integer	Total participant target
`trial_credits_used`	integer	Free trial credits consumed from your balance
`balance_charged`	string	Amount charged from your balance, e.g. `$272.00`
`balance_remaining`	string	Remaining balance after this charge, e.g. `$9,628.00`
`call_url`	string	Shareable participant link — live immediately
`recruiting_type`	string	`INTERNAL` or `USER_INTERVIEWS`

Credits and billing

Launches are charged against your organisation's balance. Trial credits are consumed first, then your balance. The cost per participant is deducted up front based on target_participants.

If your balance is insufficient a 402 Payment Required error is returned:

{
  "error": {
    "code": "insufficient_balance",
    "balance_available": 20000,
    "balance_required": 40000,
    "shortfall": 20000,
    "message": "Top up via the dashboard or contact support."
  }
}

Top up via the dashboard or contact support.

Completed interviews

As participants finish, their records appear in Interviews. If you've set up a Webhook, you'll be notified in real time.

Notes

Each project can only be launched once. Attempting to launch again returns 409 Conflict.
To run a follow-up study, create a new project.
call_url is live immediately after launch.

Launch Project

On this page