Get your interviewId & API keys

Every Ear3 integration needs exactly two values. This page is the canonical walkthrough for finding both — and for telling them apart from the values that look similar but won’t work.

Value	Format	Where it lives
`interviewId`	`cm…` (cuid, ~25 chars)	Dashboard → your interview → Deploy
`publishableKey`	`pk_test_…` / `pk_live_…`	Dashboard → Settings → API Keys

Step 1 — create and deploy an interview

Open the dashboard: app.ear3.ai/v2/researcher (redirects into your workspace).
Interviews → Create — author your questions (by hand, with ThirdAI generation, or by importing a template). Details: Creating an interview.
Click Deploy and walk the wizard (choose voice / text / both).
The wizard’s output is the Deployment ID — a cm… string. That is your interviewId.

Deployment id ≠ survey id

If the id you copied looks like a UUID (9453c463-74b6-4ff8-… — five dash-separated groups), you grabbed the survey id from an editor URL. The SDK will answer 404 interview_not_found. Go back to the interview’s Deploy tab and copy the deployment id — it starts with cm.

Also check the deployment is Active — expired or paused deployments answer 409 interview_inactive / 410 interview_expired.

Step 2 — mint API keys

Settings → API Keys → Create key (direct path: /v2/researcher/{workspace}/settings/api-keys). You’ll see three key types — they are not interchangeable:

Prefix	Type	Where it may live	Used for
`pk_test_` / `pk_live_`	Publishable	Browser bundles — safe to expose	`<Ear3Interview>`, `<Ear3VoiceInterview>`
`sk_test_` / `sk_live_`	Secret	Server only — never ship to a browser	`@ear3/server` (`sessions.retrieve`, …)
`whsec_`	Webhook	Server only	Verifying `interview_completed` signatures

Use _test_ keys while integrating; switch to _live_ for real respondents. The key must belong to the same workspace as the deployment — a key from another workspace answers 403 workspace_mismatch.

Step 3 — put both in env

Never hardcode the values in source. Browser-read vars need your framework’s public prefix:

# .env.local (Next.js — use VITE_ for Vite, REACT_APP_ for CRA)
NEXT_PUBLIC_EAR3_INTERVIEW_ID=cm...       # deployment id from Step 1
NEXT_PUBLIC_EAR3_VOICE_INTERVIEWER_KEY=pk_test_...

The publishable key is browser-safe by design — env vars here aren’t about secrecy; they keep ids out of source control and let dev/staging/prod each point at their own interview.

For AI agents doing this integration

Create the env entries above with placeholder values, wire the component to read them, and tell the user to fill in the real values from the dashboard paths on this page. Do not invent values; do not put an sk_ key in browser code; and validate the id format — cm…, not a UUID.

Verify before writing code

One curl tells you whether the pair works:

curl -s -X POST \
  "https://app.ear3.ai/api/v1/interviews/$INTERVIEW_ID/sessions" \
  -H 'Content-Type: application/json' \
  -d "{\"publishableKey\":\"$PUBLISHABLE_KEY\",\"mode\":\"hosted\"}"

A working pair returns { "sessionId": …, "sessionUrl": … }. Errors map directly to the mistakes above:

Response	Meaning
`404 interview_not_found`	Wrong id — likely a survey UUID, not a deployment id
`401 invalid_api_key`	Key typo, or key from a different environment
`403 workspace_mismatch`	Key and deployment belong to different workspaces
`409 / 410`	Deployment inactive / expired — redeploy

Quickstart — wire the values into a working page
@ear3/voice-interviewer — the browser SDK (branded widget or headless)
@ear3/server — where the sk_ / whsec_ keys go

Quickstart Concepts