Skip to main content
This guide walks you through the full end-to-end flow: authenticate, create a project, define a target segment, generate personas, optionally attach a briefing, run a concept test, and retrieve your results. Every step includes a working curl example. Swap in your own credentials and IDs as you go.
1

Log in and get your access token

Send your credentials to the login endpoint. You’ll receive an access_token that authenticates every subsequent request.
curl -X POST https://api.temujintechnologies.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "password": "your-password"
  }'
The response includes an access_token. Save it — you’ll pass it as a Bearer token in the Authorization header for all authenticated calls.
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5...",
  "token_type": "bearer"
}
2

Create a project

A project is the top-level container for all your persona groups, briefings, and simulations. Give it a name that reflects the research initiative.
curl -X POST https://api.temujintechnologies.com/api/v1/projects \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 Snack Relaunch",
    "description": "Testing new packaging and flavour messaging across Metro Manila and Jakarta"
  }'
Save the id from the response as PROJECT_ID.
{
  "id": "proj_01hw3k9zxe7fmv2bqc4d",
  "name": "Q3 Snack Relaunch",
  "description": "Testing new packaging and flavour messaging across Metro Manila and Jakarta"
}
3

Create a persona group

A persona group defines the demographic profile of the target segment you want to simulate. Set the age range, gender, location, income level, occupation, and how many personas to generate.
curl -X POST https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/persona-groups \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Metro Manila Millennials",
    "age_min": 25,
    "age_max": 35,
    "gender": "All",
    "location": "Manila, Philippines",
    "income_level": "Middle",
    "occupation": "Office worker",
    "persona_count": 5
  }'
Save the id as GROUP_ID.
Not sure how to describe your segment? Use the parse-prompt endpoint to generate these fields from a plain-language description. See the Persona Groups guide for details.
4

Generate personas

This kicks off a background task that generates your personas — complete with names, backstories, psychographic profiles, digital habits, and AI-generated avatar photos.
curl -X POST https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/persona-groups/<GROUP_ID>/generate \
  -H "Authorization: Bearer <access_token>"
The endpoint returns immediately with {"status": "generating"}. Poll the persona group until generation_status is "complete":
curl https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/persona-groups/<GROUP_ID> \
  -H "Authorization: Bearer <access_token>"
Generation typically takes 20–40 seconds for a group of 5 personas. The status progresses: pending → generating → complete.
5

Upload a briefing (optional)

A briefing is the stimulus material your personas will respond to — a product brief, campaign concept, creative deck, or any document that describes what you’re testing. It’s optional for concept tests, but a richer briefing produces richer responses.
curl -X POST https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/briefings \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@./snack-relaunch-brief.pdf"
Save the id from the response as BRIEFING_ID.Supported file types: PDF, JPG, PNG, plain text (.txt), and Word documents (.docx). Text is automatically extracted and injected into the simulation prompt.
See the Briefings guide for tips on what to include in your brief to maximise response quality.
6

Run a concept test

Create a simulation of type concept_test. Attach the persona group, your briefing (if you uploaded one), and a prompt question that frames what you want feedback on.
curl -X POST https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/simulations \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_group_id": "<GROUP_ID>",
    "briefing_ids": ["<BRIEFING_ID>"],
    "simulation_type": "concept_test",
    "prompt_question": "We are relaunching our corn chips with a new chili-lime flavour and eco-friendly packaging priced at PHP 45. How would you respond to this product?"
  }'
The simulation starts immediately as a background task. Save the id as SIM_ID.
7

Poll for completion

Check the simulation status by fetching the simulation object. The status field progresses through: pending → running → generating_report → complete.
curl https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/simulations/<SIM_ID> \
  -H "Authorization: Bearer <access_token>"
Keep polling until you see "status": "complete". The progress field shows live per-persona progress during longer runs.
{
  "id": "sim_01hw4n7zxe2fqv3brc5e",
  "status": "generating_report",
  "progress": {
    "completed": 4,
    "total": 5
  }
}
8

Get your results

Once the simulation is complete, fetch the full results:
curl https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/simulations/<SIM_ID>/results \
  -H "Authorization: Bearer <access_token>"
You’ll receive per-persona reactions, sentiment scores, key themes, and notable quotes — plus an aggregate result with a sentiment distribution and strategic recommendations.

​
What’s next

Now that you’ve run your first simulation, you can go deeper with other simulation types or validate your results.

Persona groups

Learn how to define segments and use the parse-prompt endpoint.

Briefings

Find out what to include in a briefing for the richest responses.

Reading results

Understand per-persona and aggregate result structures.

Convergence & reliability

Validate your results before presenting to stakeholders.