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

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?

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",
      "Tide pods are convenient",
      "I use whatever is on sale, usually Tide or Ariel",
      "Ariel - works in cold water",
      "Persil sensitive, fewer rashes for my kid",
      "Tide, it just smells the best",
      "Ace, cheapest at my supermarket",
      "OMO because it does not fade colors"
    ]
  }'

TypeScript

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',
    'Tide pods are convenient',
    'I use whatever is on sale, usually Tide or Ariel',
    'Ariel - works in cold water',
    'Persil sensitive, fewer rashes for my kid',
    'Tide, it just smells the best',
    'Ace, cheapest at my supermarket',
    'OMO because it does not fade colors',
  ],
});

console.log(result.codebook);
for (const row of result.coded) {
  console.log(row.response, '->', row.codes.join(', '));
}

Python

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",
        "Tide pods are convenient",
        "I use whatever is on sale, usually Tide or Ariel",
        "Ariel - works in cold water",
        "Persil sensitive, fewer rashes for my kid",
        "Tide, it just smells the best",
        "Ace, cheapest at my supermarket",
        "OMO because it does not fade colors",
    ],
)

print(result.codebook)
for row in result.coded:
    print(row.response, "->", ", ".join(row.codes))

4. The response

The API returns a codebook (the taxonomy) and a coded list (every verbatim with its assigned codes).

{
  "success": true,
  "data": {
    "codebook": [
      { "code": "Tide", "category": "Brand", "count": 4 },
      { "code": "Ariel", "category": "Brand", "count": 3 },
      { "code": "Persil", "category": "Brand", "count": 2 },
      { "code": "OMO", "category": "Brand", "count": 1 },
      { "code": "Ace", "category": "Brand", "count": 1 },
      { "code": "Stain removal", "category": "Reason", "count": 1 },
      { "code": "Value / pack size", "category": "Reason", "count": 2 },
      { "code": "Habit / family", "category": "Reason", "count": 1 },
      { "code": "Convenience", "category": "Reason", "count": 1 },
      { "code": "Price / promotion", "category": "Reason", "count": 2 },
      { "code": "Cold water performance", "category": "Reason", "count": 1 },
      { "code": "Skin sensitivity", "category": "Reason", "count": 1 },
      { "code": "Scent", "category": "Reason", "count": 1 },
      { "code": "Color care", "category": "Reason", "count": 1 }
    ],
    "coded": [
      { "response": "Tide because it removes stains better", "codes": ["Tide", "Stain removal"] },
      { "response": "Ariel - bigger pack, lasts longer", "codes": ["Ariel", "Value / pack size"] },
      { "response": "Persil because my mom always used it", "codes": ["Persil", "Habit / family"] }
    ]
  },
  "meta": { "credits_used": 10, "credits_remaining": 240, "request_id": "req_01HXJZK4ABCDEF" }
}

5. Going bigger

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

{
  "success": true,
  "data": { "job_id": "job_01HXJZK4...", "status": "queued" },
  "meta": { "estimated_credits": 1240 }
}

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’ll POST you when the job completes.

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.