Skip to content
Survey Coder Pro Survey Coder Pro

TypeScript SDK

The TypeScript SDK wraps the Survey Coder Pro REST API with full type safety, automatic retries, idempotency keys, and typed errors.

Latest version: surveycoder-sdk@1.0.2 (adds refinement bulkApply + export).

Install

Section titled “Install”
Terminal window
npm install surveycoder-sdk
# or
pnpm add surveycoder-sdk
# or
yarn add surveycoder-sdk

Requires Node 18+ (uses the built-in fetch). Also works in Bun, Deno, Cloudflare Workers, and modern browsers — anywhere fetch exists.

Quickstart

Section titled “Quickstart”
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' },
  ],
  coding_type: 'qualitative',
  language: 'en',
  // Strongly recommended — drives codebook quality:
  question_text: 'Which brand of laundry detergent do you prefer and why?',
  project_name: 'Laundry brand tracker — wave 1',
  country: 'US',
  category: 'CPG / Home Care',
});


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

Constructor options

Section titled “Constructor options”
new SurveyCoderClient({
  apiKey: string;        // required — starts with scp_live_ or scp_test_
  baseUrl?: string;      // default: 'https://api.surveycoder.io'
  timeout?: number;      // default: 300_000 ms (5 min — coding can be slow)
  maxRetries?: number;   // default: 3 (on 5xx and 429, with exponential backoff)
})

The code() call

Section titled “The code() call”

The hero method. Sync if responses.length < 50, async (returns {job_id}) otherwise.

await client.code({
  // Required
  responses: Array<{ id: string; text: string }>;


  // Optional, with defaults
  coding_type?: 'qualitative' | 'entity' | 'qualitative_topics';   // default: 'qualitative'
  language?: string;                                                // default: 'en'


  // Optional context — strongly recommended, all improve quality:
  question_text?: string;     // the actual survey question
  project_name?: string;      // shown in your dashboard
  country?: string;           // ISO code or country name (locale nuance)
  category?: string;          // organizational tag (e.g. 'Food & Beverage')
  coding_guidance?: string;   // free-form prompt instructions for the LLM


  // Advanced: bring your own codebook (skips AI generation)
  codebook?: { categories: Array<{ name: string; codes: Array<{ name: string }> }> };
});

Other methods

Section titled “Other methods”
MethodWhat it does
client.getJob(jobId)Get current state of an async job.
client.waitForJob(jobId, pollIntervalMs?)Poll until the job completes; returns the result or throws.
client.listJobs({ status?, limit? })List recent jobs.
client.getUsage()Current credit balance + rate-limit config.
client.health()Unauthenticated health probe.
client.projects.*CRUD on projects and questions.
client.refinement.*Codebook refinement suggestions — see Refinement workflow. Includes suggestions(), apply(), resolve(), undo(), bulkApply(), export().
client.codebook.*Import, clone, estimate, recommend-type.
client.analytics.*CX dashboard, cross-tabs, segment ranking, anomalies.
client.export.excel(...) / .csv(...)Export coded results.

Waiting for async jobs

Section titled “Waiting for async jobs”
const res = await client.code({ /* >= 50 responses + context */ });


if ('job_id' in res) {
  const final = await client.waitForJob(res.job_id, 5000);  // poll every 5s
  console.log(final.codebook);
}

waitForJob resolves with the job’s result payload, or throws SurveyCoderError if the job ends with status: 'failed'.

Errors

Section titled “Errors”

Every error thrown by the SDK is an instance of SurveyCoderError and carries the structured envelope from the API:

import { SurveyCoderClient, SurveyCoderError, RateLimitError } from 'surveycoder-sdk';


try {
  await client.code({ /* ... */ });
} catch (err) {
  if (err instanceof RateLimitError) {
    console.warn(`Rate limited, retry in ${err.retryAfter}s`);
  } else if (err instanceof SurveyCoderError) {
    console.error(err.code);       // e.g. 'INSUFFICIENT_CREDITS'
    console.error(err.message);
    console.error(err.requestId);  // 'req_01HXJZK4...'
    console.error(err.status);     // HTTP status
  } else {
    throw err;
  }
}

Browse every code in the error reference.

TypeScript types

Section titled “TypeScript types”

The SDK exports request and response shapes:

import type {
  CodeRequest,
  CodeResult,
  Job,
  Usage,
  ApiResponse,
  HealthStatus,
} from 'surveycoder-sdk';
Section titled “Related”