Getting started

This guide takes you from zero to your first coded response in about five minutes. If you already have an API key, skip to the Quickstart.

Prerequisites

• A Survey Coder Pro account. Sign up free — new accounts get 250 credits.
• One of: Node.js 18+, Python 3.9+, or curl. The examples below cover all three.

1. Create your API key

1. Sign in at surveycoder.io.
2. Open Settings → API Keys, or jump to surveycoder.io/settings/api-keys.
3. Click Create key, give it a label (e.g. local-dev), pick scopes — read and write cover the API surface — and copy the key.

Note

API key creation is included on Enterprise and Agency Pack plans. On Starter / Pro / Studio, the page shows an upsell — you can either upgrade your plan or buy the API Access add-on for $100 one-time, which unlocks key creation without changing your plan.

Keys look like scp_live_ followed by 32 characters. Copy it now. We only show the full key once.

Caution

Never commit API keys to source control. Use environment variables or a secrets manager. If a key leaks, revoke it from the same page — revocation is instant.

2. Send your first request

Every request sets the x-api-key header. The hero endpoint POST /v1/code is the fastest way to verify your key works. Strongly recommended: pass the actual question_text — it noticeably improves codebook quality.

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" }
    ],
    "question_text": "Which brand of laundry detergent do you prefer and why?",
    "project_name": "My first API project",
    "country": "US",
    "category": "CPG / Home Care",
    "coding_type": "qualitative",
    "language": "en"
  }'

TypeScript

npm install surveycoder-sdk

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' },
  ],
  question_text: 'Which brand of laundry detergent do you prefer and why?',
  project_name: 'My first API project',
  country: 'US',
  category: 'CPG / Home Care',
  coding_type: 'qualitative',
  language: 'en',
});

console.log(`${result.codebook.length} categories, ${result.results.length} coded responses`);

Python

pip install surveycoder

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"},
    ],
    question_text="Which brand of laundry detergent do you prefer and why?",
    project_name="My first API project",
    country="US",
    category="CPG / Home Care",
    coding_type="qualitative",
    language="en",
)

print(f"{len(result['codebook'])} categories, {len(result['results'])} coded responses")

A successful sync response (less than 50 responses) looks like:

{
  "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 }
        ]
      }
    ],
    "results": [
      { "id": "R001", "codes": [{ "name": "Tide", "sentiment": "Positive", "confidence": "high" }] },
      { "id": "R002", "codes": [{ "name": "Ariel", "sentiment": "Positive", "confidence": "high" }] },
      { "id": "R003", "codes": [{ "name": "Persil", "sentiment": "Positive", "confidence": "high" }] }
    ],
    "credits_used": 3,
    "project_id": "ab91e16b-...",
    "question_id": "d8cfd844-..."
  },
  "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 your coded study with the same UI an analyst gets.

If you get a 401 UNAUTHORIZED, double-check the header is x-api-key (lowercase) and the value starts with scp_live_. See UNAUTHORIZED for more.

3. Understand the response

• codebook — the AI-generated taxonomy. An array of categories; each has a list of codes with name, sentiment, and code_number.
• results — every input verbatim (id) with the codes the model assigned (codes[], with name, sentiment, confidence).
• credits_used — every coded response costs 1 credit. Check your remaining balance with GET /v1/usage.
• project_id / question_id — handles you can use to navigate to the dashboard or call other endpoints (export, refinement, analytics).

Optional context fields (recommended)

The minimal request only needs responses, but passing context dramatically improves codebook quality:

Field	Why it matters
question_text	The single biggest lever — the LLM uses it to guide category discovery.
project_name	Shows up in the dashboard so analysts can find this study later.
country	Affects locale nuance (local brands, regional terms).
category	Organizational tag in the dashboard (e.g. Food & Beverage, Health).
coding_guidance	Free-form prompt instructions — describe the respondent population or how to disambiguate edge cases.

See the Quickstart for the full example with all of these set.

What’s next

Quickstart

Drop in real data with full context. Side-by-side curl / TypeScript / Python on the Quickstart.

Coding pipeline

What actually happens during a call: sync vs async, credits, jobs. Read the pipeline.

Webhooks

Get notified when an async job finishes. Set up webhooks.

Errors

Every error code, with the fix. Browse the error reference.