Code survey responses (one-call hero)

POST

/v2/code

const url = 'https://api.surveycoder.io/v2/code';
const options = {
  method: 'POST',
  headers: {
    'X-Request-Id': '550e8400-e29b-41d4-a716-446655440000',
    'Idempotency-Key': 'my-batch-2026-03-31-001',
    'x-api-key': '<x-api-key>',
    'Content-Type': 'application/json'
  },
  body: '{"responses":[{"id":"R001","text":"I love Nike because of their innovation and comfort"},{"id":"R002","text":"Adidas has the best designs, especially the Originals line"},{"id":"R003","text":"Nike is overpriced, I switched to New Balance last year"},{"id":"R004","text":"I don\'t really care about brands, I just buy whatever is on sale"},{"id":"R005","text":"Puma has great collaborations with designers like Rihanna"}],"coding_type":"qualitative","language":"en"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.surveycoder.io/v2/code \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: my-batch-2026-03-31-001' \
  --header 'X-Request-Id: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'x-api-key: <x-api-key>' \
  --data '{ "responses": [ { "id": "R001", "text": "I love Nike because of their innovation and comfort" }, { "id": "R002", "text": "Adidas has the best designs, especially the Originals line" }, { "id": "R003", "text": "Nike is overpriced, I switched to New Balance last year" }, { "id": "R004", "text": "I don'\''t really care about brands, I just buy whatever is on sale" }, { "id": "R005", "text": "Puma has great collaborations with designers like Rihanna" } ], "coding_type": "qualitative", "language": "en" }'

Send an array of open-ended responses and receive AI-generated codes back in a single call. The pipeline:

Creates a temporary project
Generates (or imports) a codebook
Runs multi-layer AI coding (Preparation -> Classification -> Review)
Returns codebook + per-response codes

Sync vs Async:

< 50 responses: synchronous — result returned inline.
= 50 responses: returns 202 Accepted with a job_id for polling.

Maximum 10,000 responses per request.

Authorizations

ApiKeyAuth

Parameters

Header Parameters

X-Request-Id

string format: uuid

Example

550e8400-e29b-41d4-a716-446655440000

Client-generated request ID for tracing. Returned as-is in the response X-Request-Id header.

Idempotency-Key

string

<= 255 characters

Example

my-batch-2026-03-31-001

Idempotency key for safe retries on write endpoints. If the same key is sent within 24 hours, the server returns the cached response and sets X-Idempotent-Replay: true.

Request Body^required

application/json

object

responses

required

Array of open-ended survey responses to code.

Array<object>

>= 1 items <= 10000 items

object

required

Unique respondent or response identifier (your system’s ID).

string

text

required

The verbatim open-ended response text.

string

coding_type

Type of coding to apply:

qualitative — Theme-based coding with sentiment (default). Best for opinion questions.
entity — Entity/brand extraction and normalization. Best for “which brands do you know?” questions.
qualitative_topics — Topic grouping with forced Neutral sentiment. Best for “what topics were discussed?” questions.

string

default: qualitative

Allowed values: qualitative entity qualitative_topics

language

ISO 639-1 language code for the responses. Affects codebook generation prompts.

string

default: en

codebook

Optional pre-defined codebook. When provided, the AI skips codebook generation and uses these codes directly. When omitted, the AI generates a codebook automatically via MapReduce pipeline.

object

categories

required

Top-level groupings of codes.

Array<object>

object

name

required

Category name (e.g. “Product Quality”, “Customer Service”).

string

codes

required

Individual codes within this category.

Array<object>

object

name

required

Code label.

string

definition

Detailed definition to guide the AI classifier.

string

sentiment

Expected sentiment polarity for this code.

string

default: Neutral

Allowed values: Positive Negative Neutral Mixed

Examples

brand_preference

Brand preference survey (5 responses)

{
  "responses": [
    {
      "id": "R001",
      "text": "I love Nike because of their innovation and comfort"
    },
    {
      "id": "R002",
      "text": "Adidas has the best designs, especially the Originals line"
    },
    {
      "id": "R003",
      "text": "Nike is overpriced, I switched to New Balance last year"
    },
    {
      "id": "R004",
      "text": "I don't really care about brands, I just buy whatever is on sale"
    },
    {
      "id": "R005",
      "text": "Puma has great collaborations with designers like Rihanna"
    }
  ],
  "coding_type": "qualitative",
  "language": "en"
}

Responses

200

Synchronous result (< 50 responses)

application/json

Synchronous coding result (< 50 responses).

object

success

required

boolean

data

required

object

codebook

required

Generated or imported codebook (categories with nested codes).

Array<object>

A category with its nested codes, as returned in codebook results.

object

Database ID of the category.

string format: uuid

name

Category name.

string

codes

Array<object>

object

Database ID of the code.

string format: uuid

name

Code label.

string

sentiment

Sentiment polarity of this code.

string

Allowed values: Positive Negative Neutral Mixed

code_number

Numeric identifier for the code (unique within question).

integer

frequency

Number of responses assigned to this code.

integer

results

required

Per-response coding results, in the same order as the input.

Array<object>

Coding output for a single response.

object

required

The response ID you provided in the request.

string

codes

required

Codes assigned to this response. May be empty if the response could not be classified (garbage, too short, etc.). A response can have multiple codes if it mentions multiple themes.

Array<object>

object

name

required

Code label from the codebook.

string

sentiment

required

Sentiment polarity of this assignment.

string

Allowed values: Positive Negative Neutral Mixed

confidence

required

AI confidence in this code assignment:

high — clear match to code definition.
medium — reasonable match, may benefit from review.
low — uncertain match, flagged for review.

string

Allowed values: high medium low

credits_used

required

Number of credits consumed by this request.

integer

project_id

required

ID of the temporary project created for this request.

string format: uuid

question_id

required

ID of the question within the temporary project.

string format: uuid

meta

required

object

api_version

string

mode

Always sync for inline results.

string

Allowed values: sync

Examples

brand_preference_result

Coded brand preference responses

{
  "success": true,
  "data": {
    "codebook": [
      {
        "id": "cat_001",
        "name": "Brand Perception",
        "codes": [
          {
            "id": "code_001",
            "name": "Innovation / Technology",
            "sentiment": "Positive",
            "code_number": 1,
            "frequency": 1
          },
          {
            "id": "code_002",
            "name": "Design / Aesthetics",
            "sentiment": "Positive",
            "code_number": 2,
            "frequency": 2
          },
          {
            "id": "code_003",
            "name": "Overpriced / Value concern",
            "sentiment": "Negative",
            "code_number": 3,
            "frequency": 1
          },
          {
            "id": "code_004",
            "name": "Price-driven / No brand loyalty",
            "sentiment": "Neutral",
            "code_number": 4,
            "frequency": 1
          },
          {
            "id": "code_005",
            "name": "Celebrity / Designer collaborations",
            "sentiment": "Positive",
            "code_number": 5,
            "frequency": 1
          }
        ]
      }
    ],
    "results": [
      {
        "id": "R001",
        "codes": [
          {
            "name": "Innovation / Technology",
            "sentiment": "Positive",
            "confidence": "high"
          }
        ]
      },
      {
        "id": "R002",
        "codes": [
          {
            "name": "Design / Aesthetics",
            "sentiment": "Positive",
            "confidence": "high"
          }
        ]
      },
      {
        "id": "R003",
        "codes": [
          {
            "name": "Overpriced / Value concern",
            "sentiment": "Negative",
            "confidence": "high"
          }
        ]
      },
      {
        "id": "R004",
        "codes": [
          {
            "name": "Price-driven / No brand loyalty",
            "sentiment": "Neutral",
            "confidence": "medium"
          }
        ]
      },
      {
        "id": "R005",
        "codes": [
          {
            "name": "Celebrity / Designer collaborations",
            "sentiment": "Positive",
            "confidence": "high"
          }
        ]
      }
    ],
    "credits_used": 5,
    "project_id": "proj_abc123",
    "question_id": "q_def456"
  },
  "meta": {
    "api_version": "v1",
    "mode": "sync"
  }
}

Headers

X-Request-Id

string format: uuid

Echo of the client-supplied X-Request-Id, or a server-generated UUID.

X-RateLimit-Limit

integer

Example

Maximum requests allowed per minute for this API key.

X-RateLimit-Remaining

integer

Example

Requests remaining in the current rate-limit window.

X-RateLimit-Reset

integer

Example

1743436800

Unix epoch second when the current rate-limit window resets.

X-Idempotent-Replay

boolean

Example

false

Set to true when the response is a cached replay of a previous request that used the same Idempotency-Key.

202

Async job created (>= 50 responses)

application/json

Async job acceptance (>= 50 responses).

object

success

required

boolean

data

required

object

job_id

required

Unique job identifier for polling.

string

status

required

Initial status is always queued.

string

Allowed values: queued

estimated_seconds

required

Rough estimate of processing time in seconds.

integer

meta

required

object

api_version

string

mode

Always async for job-based processing.

string

Allowed values: async

poll_url

Convenience URL for polling the job.

string

Example

{
  "success": true,
  "data": {
    "job_id": "job_1a2b3c4d5e6f7a8b9c0d1e2f",
    "status": "queued",
    "estimated_seconds": 50
  },
  "meta": {
    "api_version": "v1",
    "mode": "async",
    "poll_url": "/v2/jobs/job_1a2b3c4d5e6f7a8b9c0d1e2f"
  }
}

400

Request body failed validation.

application/json

Standard error envelope.

object

success

required

boolean

error

required

object

code

required

Machine-readable error code. See the error reference for the full list.

string

message

required

Human-readable explanation of what went wrong.

string

request_id

Echo of the X-Request-Id header, when provided.

string format: uuid

doc_url

Link to documentation for this specific error code.

string format: uri

Example

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "responses array is required and must not be empty",
    "doc_url": "https://docs.surveycoder.io/errors/validation-error"
  }
}

401

Missing or invalid API key.

application/json

Standard error envelope.

object

success

required

boolean

error

required

object

code

required

Machine-readable error code. See the error reference for the full list.

string

message

required

Human-readable explanation of what went wrong.

string

request_id

Echo of the X-Request-Id header, when provided.

string format: uuid

doc_url

Link to documentation for this specific error code.

string format: uri

Example

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "x-api-key header is required",
    "doc_url": "https://docs.surveycoder.io/errors/unauthorized"
  }
}

402

Organization does not have enough credits.

application/json

Standard error envelope.

object

success

required

boolean

error

required

object

code

required

Machine-readable error code. See the error reference for the full list.

string

message

required

Human-readable explanation of what went wrong.

string

request_id

Echo of the X-Request-Id header, when provided.

string format: uuid

doc_url

Link to documentation for this specific error code.

string format: uri

Example

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Need 500 credits, have 120",
    "doc_url": "https://docs.surveycoder.io/errors/insufficient-credits"
  }
}

403

API key lacks the required scope, is revoked, or has expired.

application/json

Standard error envelope.

object

success

required

boolean

error

required

object

code

required

Machine-readable error code. See the error reference for the full list.

string

message

required

Human-readable explanation of what went wrong.

string

request_id

Echo of the X-Request-Id header, when provided.

string format: uuid

doc_url

Link to documentation for this specific error code.

string format: uri

Examples

Missing write scope

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Requires 'write' scope",
    "doc_url": "https://docs.surveycoder.io/errors/insufficient-scope"
  }
}

Revoked key

{
  "success": false,
  "error": {
    "code": "KEY_REVOKED",
    "message": "API key has been revoked",
    "doc_url": "https://docs.surveycoder.io/errors/key-revoked"
  }
}

429

Rate limit exceeded. Retry after the reset window.

application/json

Standard error envelope.

object

success

required

boolean

error

required

object

code

required

Machine-readable error code. See the error reference for the full list.

string

message

required

Human-readable explanation of what went wrong.

string

request_id

Echo of the X-Request-Id header, when provided.

string format: uuid

doc_url

Link to documentation for this specific error code.

string format: uri

Example

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "doc_url": "https://docs.surveycoder.io/errors/rate-limited"
  }
}

Headers

X-RateLimit-Limit

integer

Example

Maximum requests allowed per minute for this API key.

X-RateLimit-Remaining

integer

Example

Requests remaining in the current rate-limit window.

X-RateLimit-Reset

integer

Example

1743436800

Unix epoch second when the current rate-limit window resets.

500

Unexpected server error.

application/json

Standard error envelope.

object

success

required

boolean

error

required

object

code

required

Machine-readable error code. See the error reference for the full list.

string

message

required

Human-readable explanation of what went wrong.

string

request_id

Echo of the X-Request-Id header, when provided.

string format: uuid

doc_url

Link to documentation for this specific error code.

string format: uri

Example

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to process coding request",
    "doc_url": "https://docs.surveycoder.io/errors/internal-error"
  }
}

Code survey responses (one-call hero)

Authorizations

Parameters

Header Parameters

Example

Example

Request Body required

Examples

Responses

200

Examples

Headers

Example

Example

Example

Example

202

Example

400

Example

401

Example

402

Example

403

Examples

429

Example

Headers

Example

Example

Example

500

Example

Request Body^required