API Documentation

The SurveyMethods API lets your own systems work with your account: list surveys, read responses as they come in, create surveys and collectors, send invitations, export results and receive webhooks.

An API key only ever sees its own account’s data: your surveys, the surveys shared with you, your contacts and your responses.

For every endpoint, field and example request, see the interactive reference:

US accounts: online.surveymethods.com/api/docs
UK accounts: uk.surveymethods.com/api/docs

This article covers the basics and the things the reference doesn’t spell out.

Getting started

Who can use it

API access is included in the Professional, Team Professional and Enterprise plans. If your plan changes to one without API access, your keys stop working until you upgrade again.

Create an API key

Go to Account > API Keys.
Click Create a new API key and give it a name you’ll recognise, such as “CRM sync”.
Tick Read-only if the key only needs to read data (see Key types).
Copy the key straight away. It’s shown only once, so store it securely, for example in your system’s secrets manager.

You can have up to 25 keys. Delete a key on the same page to stop it working immediately.

Base URL

Use the site your account is on:

https://online.surveymethods.com/api/v1    (US accounts)
https://uk.surveymethods.com/api/v1        (UK accounts)

The examples below use the US address.

Authentication

Send your key in the X-API-Key header with every request:

curl https://online.surveymethods.com/api/v1/surveys \
  -H "X-API-Key: YOUR_API_KEY"

Requests with a body send JSON:

curl -X POST https://online.surveymethods.com/api/v1/surveys \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Customer feedback" }'

Never put an API key in a web page, mobile app or anything else your customers can see. Call the API from your server.

Key types

Type	Can do
Full access	Everything in the API
Read-only	Read data (all `GET` requests) and request exports. Anything that creates, changes, sends or deletes is refused.

Use a read-only key wherever you can, such as for reporting, dashboards or syncing responses into another system.

API keys work only with the public API at /api/v1. They can’t be used to change account settings, billing, team members or other API keys.

What you can do

Area	Endpoints
Surveys	`GET /surveys`, `GET /surveys/{id}`, `GET /surveys/{id}/structure`, `POST /surveys`, `PATCH /surveys/{id}/status`
Responses	`GET /surveys/{id}/responses`, `GET /surveys/{id}/responses/{responseId}`, `DELETE /surveys/{id}/responses/{responseId}`
Collectors	`GET /surveys/{id}/collectors`, `GET /surveys/{id}/collectors/{collectorId}`, `POST /surveys/{id}/collectors`, `PATCH /surveys/{id}/collectors/{collectorId}/status`
Invitations	`POST`, `GET` and `DELETE` on `/surveys/{id}/collectors/{collectorId}/invitations`
Exports	`POST /surveys/{id}/exports`, `GET /surveys/{id}/exports/{exportId}`, `GET /surveys/{id}/exports/{exportId}/file`
Contacts	`GET`, `POST`, `PUT` and `DELETE` on `/contacts`; `POST /contacts/delete` to delete several
Contact groups	`GET`, `POST`, `PUT` and `DELETE` on `/contacts/groups`; `POST` and `DELETE` on `/contacts/groups/{groupId}/contacts`
Webhooks	`GET`, `POST` and `DELETE` on `/webhooks`

All paths are relative to the base URL, for example https://online.surveymethods.com/api/v1/surveys.

Surveys

Create a survey

POST /surveys creates a survey in one of four ways, depending on what you send:

{ "title": "..." }: a blank survey.
{ "copyFromSurveyId": 123 }: a copy of one of your surveys.
{ "templateId": 456 }: a copy of a SurveyMethods template.
{ "title": "...", "definition": { ... } }: a survey built from your own pages and questions.

{
  "title": "Event feedback",
  "definition": {
    "pages": [
      {
        "title": "Your visit",
        "questions": [
          { "type": "netpromoterscore", "text": "How likely are you to recommend us?", "required": true },
          { "type": "multiplechoice", "text": "How did you hear about us?", "choices": ["Search", "A friend", "Social media"] },
          { "type": "commentsbox", "text": "Anything else you'd like to tell us?" }
        ]
      }
    ]
  }
}

Question types: multiplechoice, checkboxes, dropdown, ranking, commentsbox, starrating, netpromoterscore, slider, matrixratingscale, text, name, emailaddress and phone, as far as your plan includes them. Text is plain text. To use themes, logic and other question types, finish the survey in the editor.

Every new survey gets a web link collector. Its content goes through the same anti-phishing checks as surveys made in the app.

Open or close a survey

curl -X PATCH https://online.surveymethods.com/api/v1/surveys/123/status \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "isOpen": true }'

Survey structure

GET /surveys/{id}/structure returns the survey’s pages and questions in order, including each question’s type, choices, matrix rows and columns, and scale. Use it to make sense of answers: an answer’s questionId and choice ids refer to this structure.

Responses

Listing responses

GET /surveys/{id}/responses supports these query parameters:

Parameter	Meaning
`status`	`all` (default), `completed` or `partial`
`startDate`, `endDate`	Only responses completed in this range (ISO 8601, e.g. `2026-10-01T00:00:00Z`)
`includeAnswers`	`true` to include each response’s answers
`page`, `pageSize`	Page through newest first. Pages start at 0; `pageSize` is 25 by default, at most 100.
`afterId`	Sync responses in order (see below)

Each answer includes the question text, answerText (readable, e.g. “Very satisfied”) and answer (the stored value, e.g. a choice id, or JSON for checkboxes, rankings and matrices). It also includes any “Other” text or comment.

Keeping another system in sync

To copy every response into another system without missing or repeating any, use afterId rather than pages:

Request GET /surveys/{id}/responses?afterId=0&status=completed&includeAnswers=true&pageSize=100.
Store the responses, then repeat the request with afterId set to the nextAfterId from the reply.
When nextAfterId is null, you’re up to date. Save the last response id and start from it next time.

With afterId, responses come back oldest first. For new responses the moment they arrive, use a webhook instead of polling.

Collectors and invitations

Create a collector

curl -X POST https://online.surveymethods.com/api/v1/surveys/123/collectors \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "type": "web", "name": "Website footer" }'

Web collectors ("type": "web") open straight away. The reply includes the survey link in url.
Email collectors ("type": "email") send invitations.

To open or close a collector, send { "status": "open" } or { "status": "closed" } to PATCH /surveys/{id}/collectors/{collectorId}/status.

Send an invitation

curl -X POST https://online.surveymethods.com/api/v1/surveys/123/collectors/456/invitations \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-98765-feedback" \
  -d '{
    "subject": "How did we do?",
    "message": "Hi {name},\n\nThanks for your order. Could you spare two minutes to tell us how it went?",
    "buttonText": "Take the survey",
    "recipients": { "emails": ["jane@example.com"], "contactGroupIds": ["12"] }
  }'

The message is plain text. Use {name} for the recipient’s name. The email uses the design of the last invitation you sent from this collector in the app, with a button that opens each recipient’s own survey link.
Recipients can be up to 1,000 email addresses, or contact groups of any size.
To send later, add "sendAt" (up to 90 days ahead).
Retries are safe with an Idempotency-Key header (any unique string). Sending the same request with the same key within 24 hours returns the original invitation instead of sending it again.

Invitations sent through the API get the same checks as those sent from the app:

The sender address must be verified.
The content must pass our anti-phishing checks.
Your plan’s monthly email allowance applies to the app and the API together.
If your account is new to sending, a large send may be checked by our team first. Its status is then review, usually for less than a working day.

If an invitation is refused, the error says why.

GET .../invitations lists a collector’s invitations and their status: scheduled, review, sent, cancelled, blocked or overlimit. To cancel an invitation that hasn’t been sent yet, use DELETE .../invitations/{invitationId}.

Exports

Exports produce the same files as Export All Responses and Export Summary under Analyse in the app:

curl -X POST https://online.surveymethods.com/api/v1/surveys/123/exports \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{ "type": "responses", "format": "xlsx" }'

type: "responses": every response, as csv or xlsx.
type: "summary": the results summary, as csv, xlsx, pdf or pptx.

Exports are built in the background, usually within a minute or two:

Check on the export with GET /surveys/{id}/exports/{exportId} until status is ready.
Download it from downloadUrl, sending your API key as usual. CSV and Excel exports download as a .zip.

You can have up to 3 exports building at once. Exports need a plan that includes data export, and read-only keys can request them.

Webhooks

Webhooks tell your system the moment something happens, so you don’t have to keep polling. Set them up under Account > Webhooks, or with POST /webhooks. See Webhooks for the events, payloads and how to verify signatures.

Paging, limits and errors

Paging

List endpoints take page (starting at 0) and pageSize (default 25, at most 100). Replies include page, pageSize and totalCount.

Rate limit

Each API key can make 60 requests a minute, and short bursts are fine. Past that, you get 429 Too Many Requests with a Retry-After header saying how many seconds to wait.

Errors

Errors return a status code and a JSON body with a readable message:

{ "error": "Survey not found" }

Status	Meaning
`400`	The request isn’t valid, or a send was refused. The message says why.
`401`	The API key is missing, wrong or deleted.
`403`	The key can’t do this. It may be read-only, your plan may not include API access or the feature, or the account may be suspended.
`404`	Not found, or not something this key can see.
`409`	Conflicts with the current state, e.g. an export that isn’t ready yet.
`422`	The survey can’t be opened because its content was flagged by our anti-phishing checks.
`429`	Rate limit reached. Wait for the `Retry-After` seconds.

Good practice

Keep keys secret: store them in a secrets manager or environment variables, never in code repositories or web pages.
Use the least access: use read-only keys where you can, and one key per system, so you can revoke one without affecting the others.
Retry carefully: after a 429, wait for the Retry-After seconds. For other errors, back off before retrying. Use an Idempotency-Key when sending invitations.
Prefer webhooks to polling for new responses.

Need help?

Contact support@surveymethods.net with the request you sent (without your API key) and the response you got.

Related articles: