Guides/How to create an NPS survey via API

How to create an NPS survey via API

Collect scores. See the distribution. One template.

Updated March 2026

NPS surveys work because they are dead simple. One question, 0-10 scale, done. You know how customers feel. Sutrena has an NPS template with the score field and an optional follow-up. Create the form, collect scores, build a dashboard to see the distribution. This guide covers the whole thing.

1. Create an NPS form from the template

The NPS template gives you a 0-10 score selector, an optional reason textarea, an optional email field. Pass createDashboard: true to get a dashboard out of the box.

curl -X POST https://sutrena.com/api/forms \
  -H "Authorization: Bearer st_trial_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "nps",
    "createDashboard": true
  }'

# Response:
# {
#   "id": "frm_nps01",
#   "hostedUrl": "https://sutrena.com/f/frm_nps01",
#   "dashboardUrl": "https://sutrena.com/d/dsh_nps01"
# }

2. Collect scores

Put the hosted form URL in an email, on your site, or in your product. Works on mobile, any browser. Or POST scores from your own UI if you want custom design.

# Submit programmatically:
curl -X POST https://sutrena.com/api/forms/frm_nps01/submit \
  -H "Content-Type: application/json" \
  -d '{
    "score": "8",
    "reason": "Great product, would love faster support.",
    "email": "[email protected]"
  }'

# Or embed in email:
# Link to https://sutrena.com/f/frm_nps01

3. Build a custom dashboard

The auto-generated dashboard is fine to start. But you can build a more specific one -- total responses, score distribution bar chart, response trends over time.

curl -X POST https://sutrena.com/api/dashboards \
  -H "Authorization: Bearer st_trial_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "formId": "frm_nps01",
    "name": "NPS Dashboard",
    "isPublic": true,
    "dsl": {
      "version": 1,
      "widgets": [
        {
          "type": "metric_card",
          "title": "Total Responses",
          "value": "count(*)"
        },
        {
          "type": "bar_chart",
          "title": "Score Distribution (0-10)",
          "groupBy": "score"
        },
        {
          "type": "line_chart",
          "title": "Responses Per Week",
          "groupBy": "$submitted_at:week"
        },
        {
          "type": "data_table",
          "title": "Recent Feedback",
          "columns": ["score", "reason", "email"],
          "limit": 30
        }
      ]
    }
  }'

4. Analyze and act on results

Export as CSV to calculate your actual NPS (promoters minus detractors, as percentages). The bar chart shows where scores cluster. Set up a Slack webhook for alerts on new scores.

# Export data as CSV (Builder/Pro/Scale):
curl https://sutrena.com/api/forms/frm_nps01/export \
  -H "Authorization: Bearer st_live_your_key" \
  -o nps-data.csv

# Set up Slack alert for new responses:
curl -X POST https://sutrena.com/api/webhooks \
  -H "Authorization: Bearer st_trial_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "formId": "frm_nps01",
    "url": "https://hooks.slack.com/services/T00/B00/xxx",
    "template": "slack",
    "events": ["form.submission"]
  }'

FAQ

How do I calculate the actual NPS score?

Percentage of promoters (9-10) minus percentage of detractors (0-6). Export as CSV, run this in a spreadsheet or script.

Can I customize the 0-10 scale labels?

The template uses a select field with options 0-10. After creation, PATCH the form to add labels like "Not at all likely" and "Extremely likely" as helper text.

Can I send the NPS survey via email?

Yes. Link to the hosted form URL. Works on mobile and desktop. Nothing to set up.

How many responses can I collect on the free plan?

500 per form. Builder gives you 5,000 per form at $9/month. For ongoing surveys, Pro gives you unlimited at $29/month.

Can I segment NPS by customer type?

Add a custom field like "segment" or "plan" to your form. Then create a dashboard with a bar_chart grouped by that field.

Related

Dashboard DSL guide →Set up webhooks →Export to CSV →Blueprint: Live polling site →

What is Sutrena?

Sutrena is the web runtime for AI agents. Three primitives — pages, forms, and dashboards — accessible through one API. Your agent creates web artifacts, humans interact with them, and your agent gets the data back. Framework-agnostic. Works from any MCP client or HTTP client.

Get started in two API calls

1. Get a trial key (no auth, no signup)

curl -X POST https://sutrena.com/api/trial

2. Create a form + dashboard from a template

curl -X POST https://sutrena.com/api/forms \
  -H "Authorization: Bearer st_trial_xxx" \
  -H "Content-Type: application/json" \
  -d '{"templateId": "waitlist", "createDashboard": true}'
/llms.txt/api/schema/llms-full.txt/.well-known/mcp.json

Ready to build?

Get a trial API key instantly with no signup, or create an account for the full experience.

Start buildingAgent docs
How to create an NPS survey via API — Sutrena | Sutrena