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.
• 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/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.

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.

curl

curl -X POST https://api.surveycoder.io/v1/code \
  -H "x-api-key: $SCP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Which brand of laundry detergent do you prefer and why?",
    "responses": [
      "Tide because it removes stains better",
      "Ariel - bigger pack, lasts longer",
      "Persil because my mom always used it"
    ]
  }'

TypeScript

npm install surveycoder-sdk

import { SurveyCoder } from 'surveycoder-sdk';

const sc = new SurveyCoder({ apiKey: process.env.SCP_API_KEY });

const result = await sc.code({
  question: 'Which brand of laundry detergent do you prefer and why?',
  responses: [
    'Tide because it removes stains better',
    'Ariel - bigger pack, lasts longer',
    'Persil because my mom always used it',
  ],
});

console.log(result.codebook);

Python

pip install surveycoder

from surveycoder import SurveyCoder
import os

sc = SurveyCoder(api_key=os.environ["SCP_API_KEY"])

result = sc.code(
    question="Which brand of laundry detergent do you prefer and why?",
    responses=[
        "Tide because it removes stains better",
        "Ariel - bigger pack, lasts longer",
        "Persil because my mom always used it",
    ],
)

print(result.codebook)

A successful response looks like:

{
  "success": true,
  "data": {
    "codebook": [
      { "code": "Tide", "category": "Brand", "count": 1 },
      { "code": "Ariel", "category": "Brand", "count": 1 },
      { "code": "Persil", "category": "Brand", "count": 1 }
    ],
    "coded": [
      { "response": "Tide because it removes stains better", "codes": ["Tide"] },
      { "response": "Ariel - bigger pack, lasts longer", "codes": ["Ariel"] },
      { "response": "Persil because my mom always used it", "codes": ["Persil"] }
    ]
  },
  "meta": { "credits_used": 3, "credits_remaining": 247 }
}

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. Each entry has a code, a category, and a count.
• coded — every input verbatim with the codes the model assigned.
• meta.credits_used — every coded response costs 1 credit; check your remaining balance with GET /v1/usage.

What’s next

Quickstart

Drop your real data in. Side-by-side curl / TypeScript / Python examples 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.