Quickstart

This page takes you from API key to a coded response in under a minute. Need a key first? See Getting started.

1. Get your API key

Open surveycoder.io/settings/api-keys, create a key, and copy it. Export it as an environment variable so the snippets below work as-is:

export SCP_API_KEY=scp_live_...

Note

API key creation is included on Enterprise and Agency Pack plans. On other plans (Starter / Pro / Studio), buy the standalone API Access add-on for $100 one-time from /settings/api-keys — it doesn’t change your plan, just unlocks key creation.

2. Install the SDK

curl

No install needed. Skip to step 3.

TypeScript

npm install surveycoder-sdk

Python

pip install surveycoder

3. Code 10 responses

We’ll code a typical brand-preference open end. The question:

Which brand of laundry detergent do you prefer and why?

Everything beyond responses is optional but question_text is strongly recommended — the LLM uses it to guide codebook discovery, and coding the same verbatims blind vs with the question produces noticeably different category trees.

curl

curl -X POST https://api.surveycoder.io/v1/code \
  -H "x-api-key: $SCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "responses": [
      { "id": "R001", "text": "Tide because it removes stains better" },
      { "id": "R002", "text": "Ariel - bigger pack, lasts longer" },
      { "id": "R003", "text": "Persil because my mom always used it" },
      { "id": "R004", "text": "Tide pods are convenient" },
      { "id": "R005", "text": "I use whatever is on sale, usually Tide or Ariel" },
      { "id": "R006", "text": "Ariel - works in cold water" },
      { "id": "R007", "text": "Persil sensitive, fewer rashes for my kid" },
      { "id": "R008", "text": "Tide, it just smells the best" },
      { "id": "R009", "text": "Ace, cheapest at my supermarket" },
      { "id": "R010", "text": "OMO because it does not fade colors" }
    ],
    "coding_type": "qualitative",
    "language": "en",
    "question_text": "Which brand of laundry detergent do you prefer and why?",
    "project_name": "Laundry detergent — quickstart demo",
    "country": "US",
    "category": "CPG / Home Care",
    "coding_guidance": "Distinguish brand mentions (Tide, Ariel, Persil, OMO, Ace) from reasons (price, scent, performance). Multi-code when both appear."
  }'

TypeScript

import { SurveyCoderClient } from 'surveycoder-sdk';

const client = new SurveyCoderClient({ apiKey: process.env.SCP_API_KEY! });

const result = await client.code({
  responses: [
    { id: 'R001', text: 'Tide because it removes stains better' },
    { id: 'R002', text: 'Ariel - bigger pack, lasts longer' },
    { id: 'R003', text: 'Persil because my mom always used it' },
    { id: 'R004', text: 'Tide pods are convenient' },
    { id: 'R005', text: 'I use whatever is on sale, usually Tide or Ariel' },
    { id: 'R006', text: 'Ariel - works in cold water' },
    { id: 'R007', text: 'Persil sensitive, fewer rashes for my kid' },
    { id: 'R008', text: 'Tide, it just smells the best' },
    { id: 'R009', text: 'Ace, cheapest at my supermarket' },
    { id: 'R010', text: 'OMO because it does not fade colors' },
  ],
  coding_type: 'qualitative',
  language: 'en',
  question_text: 'Which brand of laundry detergent do you prefer and why?',
  project_name: 'Laundry detergent — quickstart demo',
  country: 'US',
  category: 'CPG / Home Care',
  coding_guidance:
    'Distinguish brand mentions (Tide, Ariel, Persil, OMO, Ace) from reasons (price, scent, performance). Multi-code when both appear.',
});

console.log(`Codebook: ${result.codebook.length} categories`);
for (const row of result.results) {
  const codes = row.codes.map((c) => `${c.name} [${c.sentiment}]`).join(', ');
  console.log(`${row.id} → ${codes || '(uncoded)'}`);
}

Python

import os
from surveycoder import SurveyCoderClient

client = SurveyCoderClient(api_key=os.environ["SCP_API_KEY"])

result = client.code(
    responses=[
        {"id": "R001", "text": "Tide because it removes stains better"},
        {"id": "R002", "text": "Ariel - bigger pack, lasts longer"},
        {"id": "R003", "text": "Persil because my mom always used it"},
        {"id": "R004", "text": "Tide pods are convenient"},
        {"id": "R005", "text": "I use whatever is on sale, usually Tide or Ariel"},
        {"id": "R006", "text": "Ariel - works in cold water"},
        {"id": "R007", "text": "Persil sensitive, fewer rashes for my kid"},
        {"id": "R008", "text": "Tide, it just smells the best"},
        {"id": "R009", "text": "Ace, cheapest at my supermarket"},
        {"id": "R010", "text": "OMO because it does not fade colors"},
    ],
    coding_type="qualitative",
    language="en",
    question_text="Which brand of laundry detergent do you prefer and why?",
    project_name="Laundry detergent — quickstart demo",
    country="US",
    category="CPG / Home Care",
    coding_guidance=(
        "Distinguish brand mentions (Tide, Ariel, Persil, OMO, Ace) from "
        "reasons (price, scent, performance). Multi-code when both appear."
    ),
)

print(f"Codebook: {len(result['codebook'])} categories")
for row in result["results"]:
    codes = ", ".join(f"{c['name']} [{c['sentiment']}]" for c in row["codes"])
    print(f"{row['id']} -> {codes or '(uncoded)'}")

4. The response

The API returns the auto-generated codebook (taxonomy) and per-response codes. With only 10 verbatims you’ll see the result inline (sync mode — under 50 responses returns immediately):

{
  "success": true,
  "data": {
    "codebook": [
      {
        "name": "Brand",
        "codes": [
          { "name": "Tide", "sentiment": "Positive", "code_number": 1 },
          { "name": "Ariel", "sentiment": "Positive", "code_number": 2 },
          { "name": "Persil", "sentiment": "Positive", "code_number": 3 },
          { "name": "OMO", "sentiment": "Positive", "code_number": 4 },
          { "name": "Ace", "sentiment": "Positive", "code_number": 5 }
        ]
      },
      {
        "name": "Reason for preference",
        "codes": [
          { "name": "Stain removal", "sentiment": "Positive", "code_number": 6 },
          { "name": "Value / pack size", "sentiment": "Positive", "code_number": 7 },
          { "name": "Habit / family", "sentiment": "Positive", "code_number": 8 },
          { "name": "Convenience", "sentiment": "Positive", "code_number": 9 },
          { "name": "Price-driven", "sentiment": "Neutral", "code_number": 10 },
          { "name": "Cold water performance", "sentiment": "Positive", "code_number": 11 },
          { "name": "Skin sensitivity", "sentiment": "Positive", "code_number": 12 },
          { "name": "Scent", "sentiment": "Positive", "code_number": 13 },
          { "name": "Color care", "sentiment": "Positive", "code_number": 14 }
        ]
      }
    ],
    "results": [
      { "id": "R001", "codes": [
        { "name": "Tide", "sentiment": "Positive", "confidence": "high" },
        { "name": "Stain removal", "sentiment": "Positive", "confidence": "high" }
      ]},
      { "id": "R002", "codes": [
        { "name": "Ariel", "sentiment": "Positive", "confidence": "high" },
        { "name": "Value / pack size", "sentiment": "Positive", "confidence": "high" }
      ]}
    ],
    "credits_used": 10,
    "project_id": "ab91e16b-ec89-4c23-ae9a-ad8438944320",
    "question_id": "d8cfd844-80a2-4672-8aed-8e4352c36862"
  },
  "meta": { "api_version": "v1", "mode": "sync" }
}

The project_id is your handle in the dashboard: open https://surveycoder.io/projects/{project_id}/dashboard to see the codebook, refinement suggestions, and the full coded list — everything an analyst sees for a manually-built study.

5. Going bigger (async path)

Requests with 50 or more responses are queued and return 202 Accepted immediately:

{
  "success": true,
  "data": {
    "job_id": "job_dc12934cead7a7d1a31898f0",
    "status": "queued",
    "estimated_seconds": 80
  },
  "meta": { "api_version": "v1", "mode": "async", "poll_url": "/v1/jobs/job_dc12934cead7a7d1a31898f0", "durable": true }
}

Poll GET /v1/jobs/{job_id} until status is completed (then read data.result) or failed (read data.error). Or skip polling and register a webhook — we POST you when the job completes.

TypeScript

const job = await client.code({ /* 80 responses + context */ });
if ('job_id' in job) {
  const result = await client.waitForJob(job.job_id);
  console.log(result.codebook);
}

Python

job = client.code(responses=..., question_text=...)
if "job_id" in job:
    result = client.wait_for_job(job["job_id"])
    print(result["codebook"])

Recommended optional fields

All optional, all improve quality. Pass what you have:

Field	Type	Effect
question_text	string	LLM uses it to guide codebook discovery. Single biggest quality lever.
project_name	string	Display name in your dashboard. Defaults to API Coding {timestamp}.
country	string	ISO code or country name. Influences locale-specific coding (local brands, regional terms).
category	string	Organizational tag in the dashboard (e.g. Food & Beverage, Health, Finance).
coding_guidance	string	Free-form instructions injected into the LLM coding prompt. Describe the respondent population or how to disambiguate edge cases.

What’s next

1. Read the coding pipeline to understand sync vs async, codebook reuse, and how credits are charged.
2. Set up webhooks so you don’t have to poll.
3. Use the TypeScript or Python SDK in your app.
4. Browse the full API reference.