API

Create surveys and named recipients with an API key. The API does not send invite email — send from the dashboard.

Create an API key under Settings → API keys. Send it as Authorization: Bearer <key>.

Environment variable name: WHEREGOING_API_KEY (alias: WHEREGOING_TOKEN).

Base URL: https://wheregoing.com/api/v1

{id} in paths accepts the survey id or slug.

The API does not send email. Every recipient object includes a url. Send invites from the dashboard Recipients tab. The default-locale URL is /s/{slug}/{recipientId}; Chinese pages are at /zh/s/{slug}/{recipientId}.

Create a survey

curl -X POST https://wheregoing.com/api/v1/surveys \
  -H "Authorization: Bearer $WHEREGOING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "targetCompany": "Acme",
    "title": "Wanted to ask Acme about this workflow",
    "description": "A 3-minute research survey. No right answers — actual experience only.",
    "questions": [
      {
        "type": "multiple_choice",
        "label": "Where does customer data live today?",
        "required": true,
        "options": ["Excel / CSV", "ERP", "CRM", "Google Sheets"],
        "allowOther": true
      },
      {
        "type": "linear_scale",
        "label": "How painful is cleaning that data today?",
        "required": true,
        "scaleMin": 1,
        "scaleMax": 10,
        "scaleMinLabel": "Fine",
        "scaleMaxLabel": "Unworkable"
      }
    ],
    "recipients": [
      {
        "targetCompany": "Acme",
        "email": "[email protected]",
        "title": "Wanted to ask Acme about this workflow",
        "accentColor": "#315c4c"
      }
    ]
  }'

The response includes survey.recipients[].url — that is the unique public page.

List and read

curl https://wheregoing.com/api/v1/surveys \
  -H "Authorization: Bearer $WHEREGOING_API_KEY"

curl https://wheregoing.com/api/v1/surveys/{id} \
  -H "Authorization: Bearer $WHEREGOING_API_KEY"

Update a survey

PATCH /api/v1/surveys/{id} with any subset of title, description, welcomeMessage, logoUrl, accentColor, questions, recipients.

Replacing recipients overwrites the list. To add people without dropping existing ones, use the endpoint below.

Optional on create: slug, published, notifyOnResponse, notificationEmail. Invite copy belongs on each recipient (inviteTop, inviteBottom, inviteSignOff). Duplicate slug returns 409.

Add recipients

curl -X POST https://wheregoing.com/api/v1/surveys/{id}/recipients \
  -H "Authorization: Bearer $WHEREGOING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skipExisting": true,
    "recipients": [
      { "targetCompany": "Northwind", "email": "[email protected]" }
    ]
  }'

Matched by id or email. Default is upsert. skipExisting: true leaves existing rows unchanged (keeps inviteSentAt). Response includes added, updated, skipped. Max 200 per survey.

Read responses

curl https://wheregoing.com/api/v1/surveys/{id}/responses \
  -H "Authorization: Bearer $WHEREGOING_API_KEY"

Question types

short_text, long_text, single_choice, multiple_choice, dropdown, linear_scale, rating, multiple_choice_grid, checkbox_grid, date, time.

Choice questions take options. Linear scale: scaleMin 0 or 1, scaleMax 2–10.

Errors

Status	Meaning
401	Missing or invalid API key
400	Payload failed validation (`details` from Zod)
404	Survey not found for this key
409	`slug` already in use
429	API key rate limit exceeded

A prompt you can paste into an agent is on the agent page.

API