---
title: Getting started
description: >-
  This guide takes a developer from a new Survicate account to a survey that
  collects identified responses from a website or app and delivers them to your
  own systems.
source_url:
  html: 'https://developers.survicate.com/getting-started/'
  md: 'https://developers.survicate.com/getting-started.md'
---
# Getting started with Survicate

This guide takes a developer from a new Survicate account to a survey that collects identified responses from a website or app and delivers them to your own systems. Steps 1 and 2 apply to everyone; in step 3 pick the channel your customers use. Each step links to the reference page with the full details.

## 1. Before you start

- **Create an account** at [panel.survicate.com/signup](https://panel.survicate.com/signup) with a business email address, or accept the invitation a teammate sent you. A new account starts with a 10-day trial of the Growth plan's features and continues on the free plan afterwards; the [pricing page](https://survicate.com/pricing/) lists what each plan includes.
- **Split the work.** Developers install the SDK once and pass attributes and events. From then on, whoever owns feedback creates, targets and launches surveys in the panel, with no further release needed. Agree early on the attribute and event names both sides will use; they are case-sensitive.
- **Know where to get help.** Support answers on the live chat in the panel and at [support@survicate.com](mailto:support@survicate.com). The [Help Center](https://help.survicate.com/en/) covers everything that happens in the panel and this site covers the code; both can be read by your AI assistant, see [Docs for AI agents](/#docs-for-ai-agents).

## 2. Find your keys

| Key | Used by | Where in the panel | Handle as |
| --- | --- | --- | --- |
| Workspace key | Tracking code, npm packages, Mobile SDKs | [Access Keys](https://panel.survicate.com/o/0/w/0/settings/organization/access-keys) | A public identifier; it ships in your pages and apps |
| API key | Data Export API | [Access Keys](https://panel.survicate.com/o/0/w/0/settings/organization/access-keys) (owners and admins) | Secret; server side only |
| Secret key | Signing user IDs for logged-in user targeting (`user_key`) | [Access Keys](https://panel.survicate.com/o/0/w/0/settings/organization/access-keys), Secret Key section | Secret; never in frontend or app code |
| Verification token and signing secret | Verifying webhook deliveries | [Webhooks settings](https://panel.survicate.com/o/0/w/0/integrations/webhooks?tab=settings) | Secret; can be regenerated at any time |
| Survey ID | `showSurvey`, `hiddenSurveys`, Data Export API paths | Address bar while the survey is open | Not secret |

## 3. Install Survicate

### Website or web app

Add the tracking code before the closing `</body>` tag of every page where a survey may appear, or install one of the npm packages. One installation serves every survey in the workspace, and the same snippet can be installed on any number of domains; which pages a survey shows on is decided by its targeting.

```html title="Tracking code"
<!-- Start of Survicate (www.survicate.com) code -->
<script type="text/javascript">
  (function (w) {
    var s = document.createElement('script');
    s.src = 'https://survey.survicate.com/workspaces/{{YOUR WORKSPACE KEY HERE}}/web_surveys.js';
    s.async = true;
    var e = document.getElementsByTagName('script')[0];
    e.parentNode.insertBefore(s, e);
  })(window);
</script>
<!-- End of Survicate code -->
```

```javascript title="Web package"
// npm install @survicate/survicate-web-package --save
import Survicate from '@survicate/survicate-web-package/survicate_widget';

Survicate.init({ workspaceKey: 'YOUR WORKSPACE KEY HERE' });
```

```javascript title="Web surveys wrapper"
// npm install @survicate/survicate-web-surveys-wrapper --save
import { initSurvicate } from '@survicate/survicate-web-surveys-wrapper/widget_wrapper';

await initSurvicate({ workspaceKey: 'YOUR WORKSPACE KEY HERE' });
```

The snippet with your key already filled in is under [Settings → Surveys → Web](https://panel.survicate.com/o/0/w/0/settings/surveys/web) in the panel. The tracking code and the wrapper always load the current SDK version; the web package is a dependency you update yourself. To verify the installation, open your site and run `_svc` in the browser console: it prints the workspace key when the code is installed. Google Tag Manager, WordPress, Segment and Braze installations are covered on the [Installation](/javascript/installation) page.

### Mobile app

Install the SDK for [iOS](/mobile-sdk/ios/installation), [Android](/mobile-sdk/android/installation), [React Native](/mobile-sdk/react-native/installation), [Flutter](/mobile-sdk/flutter/installation) or [Unity](/mobile-sdk/unity/installation), put the workspace key in the app configuration (`Info.plist` on iOS, `AndroidManifest.xml` on Android, or `setWorkspaceKey` in code) and initialize the SDK when the app starts. The key and the per-platform instructions are also under [Settings → Surveys → Mobile](https://panel.survicate.com/o/0/w/0/settings/surveys/mobile) in the panel. Steps 4 and 5 add user attributes, screens and events.

### Email

Nothing to install. To identify the respondents of email and link surveys, add parameters to the survey link. When you pick a supported email tool in the survey's Configure step, Survicate generates the link with that tool's merge tags; with any other tool, or in your own emails, append the parameters yourself. Every parameter becomes a respondent attribute.

```text title="Survey link with respondent attributes"
https://survey.survicate.com/<survey id>/?email={{contact.email}}&first_name={{contact.first_name}}&plan={{contact.plan}}
```

## 4. Identify respondents

Responses are anonymous until your code says who the respondent is. Pass a `user_id` plus the attributes you want to target or filter by, at a point where you know the user, for example after login. Attributes are cached on the device, so once is enough, and changing one may make a survey eligible immediately.

### Website or web app

Set the traits in the `opts.traits` object before the tracking code loads, or call `setVisitorTraits` at any time.

```javascript title="Tracking code"
// Before the tracking code
(function (opts) {
  opts.traits = {
    user_id: 'u_12345',
    email: 'ada@example.com',
    first_name: 'Ada',
    plan: 'pro',
    signed_up: '2026-01-15T09:30:00Z',
  };
})(window._sva = window._sva || {});

// Later, for example after login
window._sva.setVisitorTraits({ user_id: 'u_12345', plan: 'pro' });
```

```javascript title="Web package"
Survicate.setVisitorTraits({
  user_id: 'u_12345',
  email: 'ada@example.com',
  first_name: 'Ada',
  plan: 'pro',
  signed_up: '2026-01-15T09:30:00Z',
});
```

The Installation page covers [user identification](/javascript/installation#users-identification) and [user attributes](/javascript/installation#user-attributes) for each installation method; the method itself is documented under [Set visitor attributes](/javascript/methods#set-visitor-attributes).

### Mobile app

Call `setUserTrait`, or `setUserTraits` for several at once, once the SDK is initialized.

```swift title="iOS (Swift)"
SurvicateSdk.shared.setUserTrait(UserTrait(withName: "user_id", value: "u_12345"))

SurvicateSdk.shared.setUserTraits(traits: [
  UserTrait(withName: "email", value: "ada@example.com"),
  UserTrait(withName: "plan", value: "pro"),
  UserTrait(withName: "subscription_active", value: true),
])
```

```kotlin title="Android (Kotlin)"
Survicate.setUserTrait(UserTrait("user_id", "u_12345"))

Survicate.setUserTraits(listOf(
    UserTrait("email", "ada@example.com"),
    UserTrait("plan", "pro"),
    UserTrait("subscription_active", true)
))
```

The same call exists in every SDK: [iOS](/mobile-sdk/ios/using-sdk#user-identification-and-attributes), [Android](/mobile-sdk/android/using-sdk#user-identification-and-attributes), [React Native](/mobile-sdk/react-native/using-sdk#passing-user-attributes), [Flutter](/mobile-sdk/flutter/using-sdk#passing-user-attributes) and [Unity](/mobile-sdk/unity/using-sdk#passing-user-attributes).

### Email

Every parameter on a survey link becomes a respondent attribute, as shown in step 3: `email`, `first_name`, `last_name` and any custom name such as `plan`. When you send the survey through a supported email tool, Survicate generates the link with that tool's merge tags. For Intercom Messenger and Braze in-app message surveys, respondent identification is set up in the integration; see the Help Center articles on [Intercom Messenger surveys](https://help.survicate.com/en/articles/3935537-intercom-messenger-surveys) and [Braze in-app message surveys](https://help.survicate.com/en/articles/11087508-braze-in-app-message-surveys).

### Attribute rules

- `user_id` can be any string that is unique per user. It marks the respondent as logged in, and it is required for the *All logged-in users*, *Users* and *Manual* audiences.
- `first_name`, `last_name` and `email` make a response identified in the panel; without them it is marked Anonymous.
- Values can be strings, numbers, booleans or dates (ISO 8601). Attribute names are case-sensitive, and names and values are limited to 255 characters. Strings must not contain `{}`, `*`, `[]`, `%`, `~`, `--` or `$`.
- A workspace can hold up to 2,000 distinct attribute names, and an audience filter up to 50 attributes. An attribute becomes available as a filter in the Analyze tab once a response carrying it has arrived.
- Keep sensitive personal data (health, political opinions and similar) out of attributes used for targeting; stick to plan, role, company size and the like.

**Sign user IDs for server-side targeting.** With a *Users* or *Manual* audience, anyone who can run JavaScript on your page could pretend to be another user. To prevent it, create a secret key in the Secret Key section of [Settings → Organization → Access Keys](https://panel.survicate.com/o/0/w/0/settings/organization/access-keys), compute an HMAC-SHA256 of the `user_id` with it on your server, pass the result as `user_key` next to `user_id` (in the web traits, or as a user trait in a mobile app), and turn on **Enforce secret keys for logged-in user targeting**. Once enforced, a `user_id` without a valid `user_key` gets no server-side targeted surveys. Details are in the Help Center article [Securing surveys with secret and user keys](https://help.survicate.com/en/articles/12470514-securing-surveys-with-secret-user-keys).

## 5. Report events

Report the actions you want surveys to react to and, in mobile apps, the screens users move through. Event names, property names and values are case-sensitive and must match the panel exactly; property values are strings, and names are up to 255 characters.

### Website or web app

```javascript title="Event with properties"
_sva.invokeEvent('checkout_completed', { plan: 'pro', currency: 'EUR' });
```

Other methods you will reach for: `showSurvey(surveyId)` to show a specific survey regardless of its targeting (with `{ forceDisplay: true }` even to a visitor who already answered it), `closeSurvey()`, `retarget()` to re-run targeting after an asynchronous change in a single-page app (page loads, survey completions and route changes already do), and `addEventListener` for the `survey_displayed`, `question_answered`, `survey_completed` and `survey_closed` events, so your app can react to answers. Wait for the `SurvicateReady` window event before calling methods on `_sva`. For a fully custom UI, hide a survey with `hiddenSurveys` and record answers with `getSurveyPointsMetadata` and `submitAnswer`. All of them are on the [Methods](/javascript/methods) and [Event Listeners](/javascript/events) pages. Methods other than `setVisitorTraits`, and the event listeners, require a plan with JavaScript targeting.

### Mobile app

Report each screen when it appears and when it disappears, so surveys can be targeted to screens, and report events the same way as on the web. Listeners for `survey_displayed`, `question_answered`, `survey_completed` and `survey_closed` are available as well.

```swift title="iOS (Swift)"
// When the screen appears and disappears
SurvicateSdk.shared.enterScreen(value: "checkout")
SurvicateSdk.shared.leaveScreen(value: "checkout")

// When the user does something a survey should react to
SurvicateSdk.shared.invokeEvent(name: "checkout_completed", with: ["plan": "pro", "currency": "EUR"])
```

```kotlin title="Android (Kotlin)"
// When the screen appears and disappears
Survicate.enterScreen("checkout")
Survicate.leaveScreen("checkout")

// When the user does something a survey should react to
Survicate.invokeEvent("checkout_completed", mapOf("plan" to "pro", "currency" to "EUR"))
```

The same calls, with the same names (PascalCase in Unity), on every platform:

- iOS: [screens](/mobile-sdk/ios/using-sdk#targeting-a-survey-by-the-screen-name), [events](/mobile-sdk/ios/using-sdk#events-based-survey-targeting), [attributes](/mobile-sdk/ios/using-sdk#user-identification-and-attributes), [listeners](/mobile-sdk/ios/using-sdk#listeners)
- Android: [screens](/mobile-sdk/android/using-sdk#targeting-a-survey-by-screen-name), [events](/mobile-sdk/android/using-sdk#events-based-survey-targeting), [attributes](/mobile-sdk/android/using-sdk#user-identification-and-attributes), [listeners](/mobile-sdk/android/using-sdk#event-listeners)
- React Native: [screens](/mobile-sdk/react-native/using-sdk#targeting-a-survey-by-screen-name), [events](/mobile-sdk/react-native/using-sdk#events-based-survey-targeting), [attributes](/mobile-sdk/react-native/using-sdk#passing-user-attributes), [listeners](/mobile-sdk/react-native/using-sdk#event-listeners)
- Flutter: [screens](/mobile-sdk/flutter/using-sdk#targeting-a-survey-by-screen-name), [events](/mobile-sdk/flutter/using-sdk#events-based-survey-targeting), [attributes](/mobile-sdk/flutter/using-sdk#passing-user-attributes), [listeners](/mobile-sdk/flutter/using-sdk#event-listeners)
- Unity: [screens](/mobile-sdk/unity/using-sdk#targeting-a-survey-by-screen-name), [events](/mobile-sdk/unity/using-sdk#events-based-survey-targeting), [attributes](/mobile-sdk/unity/using-sdk#passing-user-attributes), [listeners](/mobile-sdk/unity/using-sdk#event-listeners)

### Triggers and audiences

An event can be used in two ways. As a **trigger** (Target → Triggers) the survey fires the moment the event happens, and occurrence counts are kept on the device. As an **audience filter** on a *Users* audience, Survicate stores the event history per `user_id` on its servers, so the filter follows the user across devices; the eligibility check is cached for about five minutes, so the survey may appear with a delay.

## 6. Launch a survey

In the panel, whoever owns the survey does the rest, without a deployment:

1. **Create new survey**: start from scratch, a template, a description for the AI, or imported questions, then choose the survey type. It cannot be changed afterwards.
2. **Create**: add questions, branch logic, translations and the design theme. Website surveys can switch between a pop-up and the Feedback Button in the Format tab.
3. **Target**: choose pages (URL rules or regular expressions) or screens, a trigger (on load, after a delay, on exit intent, on an event), the audience (All visitors, All logged-in users, or a Visitors, Users or Manual audience), the frequency (once per respondent by default, or recurring), sampling and, for mobile surveys, the device language, operating system or orientation.
4. **Connect**: turn on integrations and Webhooks for this survey.
5. **Launch**: start now or on a date, optionally with an end date or a response cap.

Testing a website survey: use the panel's preview, or test live in a private browsing window, because a website survey is shown to a visitor once by default and the visitor is remembered in Local Storage. Changes to a survey take up to 15 minutes to reach visitors (a couple of minutes for mobile surveys), and server-side audiences add the five-minute cache. `showSurvey(surveyId, { forceDisplay: true })` skips both the targeting and the once-per-visitor rule for a quick check.

## 7. Get the data out

- **Webhooks**: in the survey's Connect tab, add your endpoint URL and choose delivery per answer (`questionAnswered`) or per completed response (`surveyCompleted`). Use **Send sample request** to test. A `questionAnswered` delivery carries one question and its answer; a `surveyCompleted` delivery carries all of them in a `questionsAnswered` array. Both include the survey, `responseUuid`, timestamp, page URL and the respondent's attributes. Verify the signature with your [verification token or signing secret](/webhooks/security), and allow the source IPs 3.248.104.12 and 54.171.69.70. Payloads are documented under [Events](/webhooks/events) and [Answer types](/webhooks/answer-types).
- **Data Export API**: authenticate with the API key and page through results by following `next_url` until `has_more` is `false`. Responses can be filtered by date range and enriched with the attributes you name in `attributes[]`. Limits: 5 concurrent requests and 1,000 requests per minute per workspace. [Setup](/data-export/setup) explains pagination and attributes; [Survey](/data-export/survey), [Response](/data-export/response), [Respondent](/data-export/respondent) and [Personal Data](/data-export/personal-data) list the endpoints.

```shell title="First requests"
curl -H 'Authorization: Basic {{apiKey}}' 'https://data-api.survicate.com/v2/surveys'
curl -H 'Authorization: Basic {{apiKey}}' 'https://data-api.survicate.com/v2/surveys/{survey_id}/responses?items_per_page=100'
```

- **Integrations**: for Slack, Microsoft Teams, Google Sheets, HubSpot, Salesforce, Intercom, Amplitude, Mixpanel, BigQuery and other tools, connect the integration in the panel instead of writing code; the Help Center's [Connect integrations](https://help.survicate.com/en/collections/36481-connect-integrations) collection has the setup for each.
- **Exports**: CSV and XLSX from a survey's Analyze tab, and PDF or PNG charts.
- **Survicate MCP**: connect Claude, ChatGPT, Cursor or Slack to `https://mcp.survicate.com/` to ask questions about the responses, pull scores and draft surveys with your own permissions. See [Connect](/mcp/connect).

Webhooks and the Data Export API are included in the Pro and Enterprise plans; the [pricing page](https://survicate.com/pricing/) lists what each plan includes.

## Next steps

- [JavaScript SDK installation](/javascript/installation)
- [JavaScript SDK methods](/javascript/methods)
- [Mobile SDK](/mobile-sdk)
- [Data Export API setup](/data-export/setup)
- [Webhooks](/webhooks)
- [Connect Survicate MCP](/mcp/connect)