Create Project

Creates a new research project. Persona automatically generates an interview guide, recruiting criteria, and branding from the context you provide — no manual setup required.

Once created, use Launch Project to make it live and get a shareable participant link.

Endpoint

http

POST https://external-api.prod.insightscompany.io/external/projects

Request

POST /external/projects

curl -X POST "https://external-api.prod.insightscompany.io/external/projects" \
-H "X-Api-Key: <api_key>" \
-H "Content-Type: application/json" \
-d '{
  "organisation_id": "<organisation_id>",
  "title": "Customer Churn Research",
  "research_objective": "Understand why customers cancelled their subscription in the past 90 days",
  "ai_context": "We are a B2B SaaS company. Churned customers received a 15% win-back offer.",
  "target_audience": "B2B customers who cancelled in the last 90 days"
}'

Request body

Field	Type	Required	Description
`organisation_id`	UUID	Yes	Your organisation ID
`title`	string	Yes	Internal name for the study
`research_objective`	string	Yes	What you want to learn — the AI generates interview questions from this
`ai_context`	string	No	Background for the AI interviewer: product info, customer segment, relevant context
`target_audience`	string	No	Who will be interviewed — informs recruiting criteria

The quality of the generated interview guide is directly tied to the specificity of research_objective. "Understand churn" produces generic questions. "Understand why B2B customers with fewer than 5 seats cancelled within 30 days of onboarding" produces targeted, useful ones.

Response

{
  "project_id": "xyz789-...",
  "title": "Customer Churn Research",
  "status": "DRAFT",
  "interview_guide": {
    "intro_message": "Hi! Thanks for taking a few minutes to chat. I'd love to understand your recent experience...",
    "questions": [
      "What was the main reason you decided to cancel?",
      "Was there a specific moment or event that triggered the decision?",
      "What would have needed to be different for you to stay?"
    ]
  },
  "created_at": "2025-06-20T10:00:00Z"
}

Field	Description
`project_id`	Save this — you'll need it to launch the project and fetch interview records
`status`	`DRAFT` until launched
`interview_guide.questions`	AI-generated questions based on your `research_objective`

Next step

Launch the project to make it live and get a shareable participant link.