Pulse — submit a response

When a user finishes a survey, the SDK posts the answers to this endpoint. The response is validated against the survey's question schema, scored if applicable (NPS, CSAT, rating), persisted to ClickHouse + Postgres, and emitted as an outbound webhook event.

For the SDK pattern, every official Pulse client wraps this endpoint. Direct HTTP integrations (custom UIs, server-side surveys, email submission flows) should call it directly.

Authentication

Required header: x-api-key: sk_live_… or x-api-key: sk_test_…. See Authentication.

Request body

Example request

curl -X POST https://api.sankofa.dev/api/pulse/responses \
-H "Content-Type: application/json" \
-H "x-api-key: sk_live_..." \
-d '{
  "survey_id": "psv_abc",
  "respondent": {
    "user_id": "user_123",
    "email": "ada@example.com"
  },
  "context": {
    "release_version": "2.4.1",
    "device_model": "iPhone 15",
    "os_version": "17.4"
  },
  "answers": {
    "q_satisfaction": 9,
    "q_feedback": "Love the new checkout — much faster than before.",
    "q_features": ["mobile_app", "dashboard"]
  }
}'

Response (201)

{
"id": "resp_xyz789",
"score": 9,
"env": "live",
"survey": "psv_abc"
}

score is derived from the first NPS or rating answer in question order (or null if no scorable answer was provided). For surveys with multiple scoring questions, the dashboard's analytics view computes per-question scores too — score here is just the headline.

Error responses

Validation error shape

When the request fails per-question validation:

{
"error": "validation",
"message": "Some answers are invalid or missing.",
"invalid": [
  {
    "question_id": "q_satisfaction",
    "prompt": "How satisfied are you?",
    "reason": "value_out_of_range"
  }
],
"missing": [
  {
    "question_id": "q_required_question",
    "prompt": "What's the main reason?"
  }
]
}

The reason codes:

Anonymous submissions

Every field in respondent is independently optional. Posting with no respondent identity creates a fully anonymous submission — useful for kiosks, embedded forms, and public sharable links.

For shareable links, use the survey's slug:

curl -X POST https://api.sankofa.dev/api/pulse/responses \
-H "Content-Type: application/json" \
-H "x-api-key: sk_live_..." \
-d '{
  "survey_id": "post-purchase-nps",
  "answers": { "q_satisfaction": 8 }
}'

Quota and billing

Pulse-response submissions are quota-metered per project per month. The check happens before the database transaction commits — so a 402 response means the row was never written.

If you're at risk of hitting the quota mid-month, the dashboard's usage card warns at 80% / 95%; upgrade tier or contact support before then.

Side effects on success

When the engine accepts a response:

1. Persist

   Inserts pulse_survey_responses (one row) + pulse_survey_response_answers (N rows, one per answered question) in a single transaction.

2. Score derivation

   Picks the first NPS / rating / scale question in order_index order, extracts its value, stores in score field on the response row.

3. Plan integration (if configured)

   Emits a ResponseSubmittedEvent to the in-process bus. If a Plan board has a triage rule (e.g. "auto-create ticket on NPS < 6 with text feedback"), Plan picks it up.

4. Outbound webhook

   pulse.response.submitted event fired to subscribers configured for that pattern. See Webhooks.

5. Distribution attribution

   If context.distribution_id is set, the response is attributed to that distribution for funnel analytics ("of the 1,000 emails sent, 47% opened, 12% submitted").

6. ClickHouse mirror

   Best-effort async write to ClickHouse for analytics queries (joins with cohorts, retention, etc.). Failure here is non-fatal — Postgres is the source of truth.

7. Partial-response cleanup

   If a respondent.external_id was tracked through earlier partial-save calls, the matching pulse_survey_response_partials row is deleted.

Server-side validation against question schema

The engine validates every answer against its question kind:

required: true questions must be present in the answers map. Missing required questions show up under missing in the validation error response.

What's next