sales-skills/sales-questionpro

QuestionPro Platform Help

Help the user with QuestionPro — survey design, distribution, the Audience panel, response analytics, and the v2 REST API / webhook automation surface.

Step 1 — Gather context

If references/learnings.md exists, read it first for accumulated platform knowledge.

Ask the user:

1. What do you need help with?

   • A) Building a survey (question types, logic, languages, AskWhy)
   • B) Distributing it (email lists, links, offline/mobile, reminders)
   • C) Buying responses from QuestionPro Audience
   • D) Analyzing responses (reports, TURF, SPSS export)
   • E) Automation / integrations (v2 REST API, webhooks, CX or Communities APIs, Zapier)
   • F) Account / billing (plan comparison, response limits, API quota)
   • G) Something else — describe it

2. What's your situation?

   • A) Setting up QuestionPro for the first time
   • B) Something isn't working / data looks wrong
   • C) Optimizing an existing survey
   • D) Getting data out into another system
   • E) Evaluating QuestionPro vs alternatives

3. What plan are you on? (Essentials/free, Advanced, Team Edition, Research Suite, trial, not sure)

If the user's request already provides enough context, skip to the relevant step. Lead with your best-effort answer, then ask 1-2 clarifying questions at the end.

Step 2 — Route or answer directly

If the request maps to a specialized skill, route:

• Cross-tool NPS/CSAT/VoC strategy → /sales-customer-feedback {your question}
• Choosing how to validate a startup idea → /sales-idea-validation {your question}
• SurveyMonkey platform questions → /sales-surveymonkey {your question}
• Zoho Survey platform questions → /sales-zoho-survey {your question}
• Enterprise XM → /sales-qualtrics {your question}
• Survey invitation email deliverability → /sales-deliverability {your question}

Otherwise, answer directly using the reference below.

Step 3 — QuestionPro platform reference

Read references/platform-guide.md for the full platform reference — modules, pricing and plan gates, the Audience panel, integrations, and how QuestionPro compares to alternatives.

Answer using only the relevant section. Don't dump the full reference.

For API or webhook questions, also read references/questionpro-api-reference.md — v2 REST endpoints, auth, limits, pagination, response data model, and webhook creation.

Step 4 — Actionable guidance

You no longer need the full platform guide — focus on the user's specific situation.

1. State the plan gate first. Before giving steps, tell the user whether their tier supports the feature. If they ask about conjoint or MaxDiff, say immediately that these are Research Suite only — quote-only, ~$5–10k/yr, 10-seat minimum, and not trialable — rather than walking them through a feature they cannot reach. Branding needs Advanced+; collaboration and regional data centers need Team+. When a plan gate is hard, don't stop at "no" — name an alternative. For conjoint/MaxDiff on a self-serve budget, point at OpinionX for free stack-ranking/conjoint-style pricing studies, and/or route the underlying pricing question to /sales-idea-validation for a real behavior test.
2. When a 429 comes up, disambiguate it before troubleshooting. QuestionPro returns 429 for two unrelated reasons: the burst rate limit (300 calls/60s per key, 2,400/60s per org) — where retrying works — or the license's finite lifetime API quota being spent (Trial 500, Advanced 5,000, Team 10,000, Research 20,000), where retrying never works and no amount of backoff helps. Ask which it is before proposing a fix, and tell them to check their remaining calls under Integration » Developer API to settle it. Tell the user plainly that an exhausted quota is not a transient error.
3. Recommend webhook-push over polling for any pipeline. A webhook delivery costs zero API calls; polling burns the finite quota. Say the arithmetic out loud when it decides the design — polling once a minute is ~43,200 calls/month, which exhausts an Advanced license's entire 5,000-call allowance in under three days, permanently.
4. Whenever you set up a webhook, tell the user there is no HMAC signature to verify. They must authenticate it themselves with a shared secret in requestHeader plus an unguessable URL, and verify it server-side. Never imply a signature header exists. Retry behavior is undocumented, so pair every webhook with a nightly reconciliation query. Create it with POST /surveys/{id}/webhooks and always state both the payload template (requestJSON, e.g. the {complete_response} macro) and the trigger point (location, e.g. LOCATION_AFTER_SURVEY) — the body is a template the user defines, so there is no fixed payload schema to code against.
5. Use perPage=1000, not the default 100, on any bulk read — same data, one-tenth the quota burn.
6. Check the data center before debugging auth. US/Canada/EU have different hosts and keys are not portable; Surveys, CX, and Communities each issue a separate key.
7. Step-by-step instructions — numbered steps to accomplish their goal.
8. Verification — how to confirm it works (preview the survey, check the webhook's per-webhook log, send a test response, confirm remaining API quota under Integration » Developer API).

If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there with today's date.

Gotchas

Best-effort from research (2026-07) — review these, especially plan-gated features and pricing, which change.

• 429 means two different things, and only one of them is retryable. QuestionPro meters both a burst rate limit (300 calls/60s per key, 2,400/60s per org) and a finite lifetime quota of API calls per license (Trial 500, Advanced 5,000, Team Edition 10,000, Research/CX/Communities/Workforce 20,000). Once the quota is spent, every subsequent call 429s forever. This is the single most confusing thing about the API: an integration that worked all week dies permanently, and the status code implies "slow down" when the real answer is "buy more calls."

• Conjoint and MaxDiff are Research Suite only — quote-only, and untrialable. Reported ~$5–10k/yr with a 10-user seat minimum, so a two-person research team pays the full freight. They cannot be tested without booking a sales demo. If someone is choosing QuestionPro for conjoint/MaxDiff on a startup budget, that's the wrong tool — say so.

• The free Essentials tier has no listed API quota. It's absent from the limits table entirely — don't promise API access on the free plan. Free is also capped at 200 responses per survey.

• Team Edition is cheaper per seat than Advanced ($83 vs $99/user/mo) but requires 5 seats — so the real floor is ~$415/mo. A solo user pays more per seat than a team does.

• Webhooks have no HMAC signature or signing secret. Authenticate with your own shared secret in requestHeader and an unguessable URL. Retry/backoff on receiver failure is undocumented — never assume at-least-once delivery; reconcile.

• requestJSON is a template, not a schema. {complete_response} is a macro QuestionPro expands. The delivered payload shape is whatever you configured, so there's no single fixed webhook schema.

• Surveys, CX, and Communities each have a separate API and a separate key. A Surveys key 401s against CX. CX keys are generated inside CX, not under Integration » Developer API.

• Keys are data-center-bound. US api.questionpro.com, Canada ca.questionpro.com, EU eu.questionpro.com. A key minted in one region won't authenticate against another — and the v2 docs never expand the {{env}} placeholder, so people guess wrong.

• Audience panel is bid/quote-based with no published rate. Cost-per-complete, incentives included; third-party panel completes typically run $3–15 each. Shorter surveys cost less; tighter targeting costs more. There is no panel API — buying is a UI flow.

• Expect aggressive sales email after signup, plus recurring reviewer complaints about price vs value, 7–10 hour support response times, and a cluttered UI.

• Response-parsing pitfalls live in the API reference. The answerValues[].value object shape, non-ISO timestamps, drifting pagination field names, the custom1..custom5 join keys, the dataQuality/duplicate panel-quality fields, and the deprecated v1 RPC API are all documented in references/questionpro-api-reference.md (Data-model & parsing pitfalls) — read it before writing a parser.

• Self-improving: If you discover something not covered here, append it to references/learnings.md with today's date.

Related skills

• /sales-customer-feedback — NPS/CSAT/VoC strategy across all tools — survey design, response rates, closed-loop feedback, platform comparison. Install: npx skills add sales-skills/sales --skill sales-customer-feedback -a claude-code
• /sales-idea-validation — Validating an idea before building — where a paid survey panel does and doesn't count as evidence. Install: npx skills add sales-skills/sales --skill sales-idea-validation -a claude-code
• /sales-surveymonkey — SurveyMonkey platform help — the closest self-serve peer, with REST API v3 and a per-response Audience panel. Install: npx skills add sales-skills/sales --skill sales-surveymonkey -a claude-code
• /sales-zoho-survey — Zoho Survey platform help — the budget floor of this class, but without a real API. Install: npx skills add sales-skills/sales --skill sales-zoho-survey -a claude-code
• /sales-qualtrics — Qualtrics XM platform help — the enterprise research step up. Install: npx skills add sales-skills/sales --skill sales-qualtrics -a claude-code
• /sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code

Examples

Example 1: The API stopped working (developer/automation)

User: "Our QuestionPro sync ran fine for a week and now every call returns 429. I added exponential backoff and it's still 429. What's wrong?"

Approach: Backoff already failing is the tell — this is the lifetime API quota, not the burst limit. Advanced includes 5,000 total calls (Team 10,000, Trial 500), and a once-a-minute poll is ~43,200/month, so it's spent in under three days, permanently. Have them check remaining calls under Integration » Developer API. The fix is architectural: switch to a webhook (POST /surveys/{id}/webhooks, location: LOCATION_AFTER_SURVEY) which costs zero calls per delivery, and reserve API reads for a nightly reconcile at perPage=1000. Warn there's no HMAC signature (authenticate with a shared secret in requestHeader + an unguessable URL) and retry is undocumented, so keep the reconcile.

Example 2: Chose QuestionPro for conjoint

User: "I'm a solo founder. I signed up for QuestionPro to run a conjoint study on pricing but I can't find conjoint anywhere in the builder. Where is it?"

Approach: It's not hidden — conjoint (and MaxDiff) are Research Suite only: quote-only (~$5–10k/yr), 10-seat minimum, no trial, so a solo founder would buy 10 seats for it. Say plainly they picked the tool for a capability they can't reach on any plan they'd buy. Redirect: OpinionX does free conjoint-style pricing studies, and route the pricing question to /sales-idea-validation since "what should I price this at" usually wants a real behavior test (price-tiered landing page + real checkout). Caveat: conjoint measures stated preference, never that anyone will actually pay.

Example 3: Panel budget for concept testing

User: "I need 800 responses from US homeowners aged 30-55 to test a product concept. What'll QuestionPro Audience cost and how do I set it up?"

Approach: There's no published per-response rate — Audience is cost-per-complete (incentives included), bought by configuring a sample or requesting a bid. Third-party completes typically run $3–15 each, so 800 is plausibly $2,400–12,000 depending on incidence and length; the real number appears once configured. Levers: shorter surveys cost less, and every extra targeting filter raises the rate. Filter delivered data on the built-in dataQuality, dataQualityScore, and duplicate fields before analysis. Category caveat: 800 "I'd buy this" answers are stated preference at scale, not demand — take the go/no-go to a real behavior test (/sales-idea-validation).

Troubleshooting

"API returns 429 / rate limited"

• Determine which 429 it is first. Burst limit (300/60s per key, 2,400/60s per org) → backoff works; lifetime quota exhausted → retrying never works. Backoff not fixing it = quota. Check remaining calls under Integration » Developer API (Trial 500 · Advanced 5,000 · Team 10,000 · Research/CX/Communities/Workforce 20,000).
• Fix by architecture, not retries. Stop polling → webhook (zero calls per delivery); keep API reads for backfill at perPage=1000 (10× fewer calls than the default 100).

"401 Unauthorized / 404 on a valid survey ID"

• Data center: US api.questionpro.com · Canada ca.questionpro.com · EU eu.questionpro.com — keys aren't portable and the v2 docs leave {{env}} unexpanded.
• Right product's key: Surveys, CX, and Communities each issue a separate key (a Surveys key 401s against CX). Header is api-key (not Authorization/X-API-Key). v1 deprecated 2021-07-15 (v2 paths look like /a/api/v2/surveys/{id}/responses). 403 = valid key, tier/role lacks permission.

"Conjoint / MaxDiff / branding / collaboration is missing or greyed out"

• Confirm the tier. Conjoint/MaxDiff are Research Suite only (quote-only, 10-seat min, no trial); branding needs Advanced+; collaboration + regional data centers need Team+. Question types scale by tier (Essentials 30 · Advanced 38 · Team 46 · Research 52). These are hard gates — for conjoint on a budget, use OpinionX or reframe via /sales-idea-validation.

"Webhook data isn't arriving / arrives but my parser produces blank fields"

• Check the per-webhook log (UI) — the source of truth for delivery. Confirm location: LOCATION_AFTER_SURVEY and a real macro like {complete_response} in requestJSON (an empty template delivers nothing). There's no HMAC — authenticate the shared secret in requestHeader, don't reject unsigned. Blank columns = the answerValues[].value object trap (see the API reference's parsing pitfalls). Add a nightly GET /responses reconcile since retry is undocumented.