Skip to main content
This guide walks you through the complete Boses workflow using the API: authenticate, create a project, define a persona group, generate personas, run a concept test, and retrieve your results. All examples use curl. Replace <TOKEN>, <PROJECT_ID>, <GROUP_ID>, and <SIM_ID> with the values returned at each step.
1

Log in and get your access token

Send your credentials to the login endpoint. The response contains an access_token you will include in 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"
  }'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
Save the access_token value — you will pass it as a bearer token in the Authorization header for all authenticated requests. Access tokens expire after 15 minutes; see Authentication for how to refresh them.
2

Create a project

A project is the top-level container for your research initiative. Give it a name that reflects your campaign or product.
curl -X POST https://api.temujintechnologies.com/api/v1/projects \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 Snack Relaunch",
    "description": "Testing new packaging and messaging for the chili-lime variant"
  }'

{
  "id": "proj_01hw3k9m2n4pqr5st6uv7wx8",
  "name": "Q3 Snack Relaunch",
  "description": "Testing new packaging and messaging for the chili-lime variant",
  "created_at": "2026-04-07T08:00:00Z"
}
Save the id value as PROJECT_ID.
3

Define a persona group

A persona group defines the demographic profile of your target segment. Boses uses these fields to generate realistic individual AI consumers grounded in real market data for the specified location.
curl -X POST https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/persona-groups \
  -H "Authorization: Bearer <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
  }'

{
  "id": "grp_02jx4l0n3o5qrs6tu7vw8xy9",
  "name": "Metro Manila Millennials",
  "generation_status": "pending",
  "persona_count": 5
}
Save the id value as GROUP_ID.
Use the parse-prompt endpoint to fill persona group fields automatically from a plain-English description instead of specifying each field manually:
curl -X POST https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/persona-groups/parse-prompt \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Filipino millennial women aged 25–32, middle-income, living in Metro Manila, working in office jobs"
  }'
The endpoint returns a pre-filled set of demographic fields you can review and pass directly to POST /persona-groups.
4

Generate personas

Trigger persona generation for the group. Boses creates individual AI consumers in the background, drawing on real consumer signals from Reddit, Shopee, and app store reviews for the target market.
curl -X POST https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/persona-groups/<GROUP_ID>/generate \
  -H "Authorization: Bearer <TOKEN>"

{
  "status": "generating"
}
The endpoint returns immediately with 202 Accepted. Poll GET /projects/<PROJECT_ID>/persona-groups/<GROUP_ID> until generation_status is "complete" — this typically takes 20–40 seconds.
curl https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/persona-groups/<GROUP_ID> \
  -H "Authorization: Bearer <TOKEN>"

{
  "id": "grp_02jx4l0n3o5qrs6tu7vw8xy9",
  "generation_status": "complete",
  "persona_count": 5
}
5

Run a concept test

Create a simulation against your persona group. A concept test presents your idea or brief to each persona and collects individual reactions and an aggregate summary.
curl -X POST https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/simulations \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_group_id": "<GROUP_ID>",
    "simulation_type": "concept_test",
    "prompt_question": "We are relaunching our corn chips with a new chili-lime flavour and eco-friendly packaging. How would you respond to this?"
  }'

{
  "id": "sim_03ky5m1o4p6rst7uv8wx9yz0",
  "status": "pending",
  "simulation_type": "concept_test"
}
Save the simulation id as SIM_ID. The simulation runs in the background and moves through the states pending → running → generating_report → complete.
6

Get your results

Poll the simulation endpoint until status is "complete", then fetch the results.
curl https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/simulations/<SIM_ID> \
  -H "Authorization: Bearer <TOKEN>"
Once the status is "complete", retrieve the full results:
curl https://api.temujintechnologies.com/api/v1/projects/<PROJECT_ID>/simulations/<SIM_ID>/results \
  -H "Authorization: Bearer <TOKEN>"
The results include per-persona reactions, sentiment scores, recurring themes, representative quotes, and an aggregate strategic recommendation.

​
Simulation types

Boses supports six simulation types. Choose the one that matches your research objective.
Typesimulation_type valueBest for
Concept testconcept_testTesting a product idea, campaign concept, or creative stimulus against a group of personas
SurveysurveyStructured questionnaires with Likert scales, multiple choice, and open-ended questions
Focus groupfocus_groupMulti-turn group discussion to surface emergent themes and group dynamics
In-depth interview (automated)idi_aiDeep one-on-one exploration of attitudes using an uploaded interview script
In-depth interview (manual)idi_manualInteractive chat session where you interview a single AI persona yourself
Conjoint analysisconjointFeature preference trade-offs and willingness-to-pay across product attribute profiles