Create Unique Invite Links

PollPe allows you to create personalized unique links for surveys using hidden parameters. This feature helps track and pre-fill survey responses efficiently.

🚀 Overview

Create unique invite links for each participant by passing hidden parameters like name, phone number, or custom values. These links can be distributed individually for:

CRM integrations
Campaign performance tracking
Auto-filled fields in surveys
Advanced analytics

Each link is a single opaque URL such as https://poll.pe/e08229a2be8fdd3e6e14fe86b8bc970f. Your hidden values are stored against that link on our side rather than encoded into it, so the recipient never sees them in the URL and cannot edit them.

📤 Create Unique Links – API Reference

🔗 Endpoint

POST https://core.pollpe.com/api/create-unique-links

NOTE:
The base URL is region-specific. If your workspace is hosted outside India, use the base URL issued alongside your API token instead of core.pollpe.com — a token only works against the region its workspace lives in.

🔐 Headers

Key	Value
Authorization	Bearer `<YOUR_API_TOKEN>`
Content-Type	application/json

NOTE:
You’ll need an API Token.

Before you start

Two things must be true or the call will fail:

The survey must be published. Draft surveys are rejected.
The survey must already declare its hidden parameters, and each object you send must contain at least one of those declared keys. Set them up in the form builder first — see the note under hidden below.

Request Body

{
  "surveyId": "XYZ000000",
  "properties": {
    "expiry": {
      "days": 2
    },
    "allowMultipleSubmission": false
  },
  "hidden": [
    {
      "hidden_parameter1": "value1",
      "hidden_parameter2": "value2",
      "hidden_parameter3": "value3"
    },
    {
      "hidden_parameter1": "value4",
      "hidden_parameter2": "value5",
      "hidden_parameter3": "value6"
    }
  ]
}

surveyId (string, required) — The unique ID of the target survey for which invite links are to be generated.
properties (object, optional) — Configuration for the invite link behavior. The whole block can be omitted, in which case the defaults below apply.
- expiry.days (number, optional) — How long the link stays valid, as an exact N × 24 hours from the moment the link is created. days: 2 means the link dies exactly 48 hours later, regardless of the time of day you called the API or the time zone your workspace is in. Accepts 1–36524. Defaults to 90 days when omitted.
- allowMultipleSubmission (boolean, optional) — Whether the link can be used for more than one submission. Defaults to false, meaning every link is single-use. Set it to true only if you deliberately want one link to accept unlimited submissions.
hidden (array of objects, or a single object, required) — Each object represents one recipient’s hidden parameters. These values are attached to that recipient’s response without being visible to them, and can also be piped into your question text to personalise the survey. You can include multiple key-value pairs for each respondent, such as IDs, source tags, or campaign info.

Pass an array to mint many links in one call, or a single object to mint one. The response shape differs slightly between the two — see below.
callbackRequired (boolean, optional) — When true, PollPe also POSTs the generated invites to the callback URL configured for your workspace, and reports the outcome in the response. Leave it out if you only want the links returned inline.

NOTE:
Use the same keys for your hidden parameters as you’ve set up in your form. Each object must contain at least one of the keys declared on the form; objects that match none of them are rejected, and the error lists the keys the form expects.

Response Object

When hidden is an array, the response returns invites (plural):

{
  "invites": [
    {
      "hidden_parameter1": "value1",
      "hidden_parameter2": "value2",
      "hidden_parameter3": "value3",
      "surveyLink": "https://poll.pe/e08229a2be8fdd3e6e14fe86b8bc970f"
    },
    {
      "hidden_parameter1": "value4",
      "hidden_parameter2": "value5",
      "hidden_parameter3": "value6",
      "surveyLink": "https://poll.pe/87e99d9339613a1299390eb76cdc83ce"
    }
  ],
  "success": true
}

When hidden is a single object, the response returns invite (singular) instead:

{
  "invite": {
    "hidden_parameter1": "value1",
    "surveyLink": "https://poll.pe/e08229a2be8fdd3e6e14fe86b8bc970f"
  },
  "success": true
}

surveyLink (string) — The unique invite link generated for each recipient, corresponding to their hidden data.
success (boolean) — Whether the links were created. Always check this, see below.

If you sent callbackRequired: true, the response also carries callbackSuccess plus either callbackResponse or callbackError. The callback is reported separately on purpose: a failed callback does not mean the links failed to generate.

⚠️ Checking the response

Check the success field, not just the HTTP status code.

On core.pollpe.com this endpoint sits behind a fallback layer. If the request cannot be completed, that layer answers with HTTP 200 and the following body rather than an error status:

{ "invites": [], "success": false }

So a 200 on its own does not mean links were created. Treat success: false — or an empty invites array — as a failure, and retry or alert on it. Responses produced by the fallback also carry the header X-PollPe-Fallback: true, which you can use to tell them apart.

Common causes of success: false:

Cause	What to check
Survey is unpublished	Publish the form, then retry
`surveyId` is wrong, or belongs to another workspace	Confirm the ID and that your token belongs to that workspace
The form has no hidden parameters configured	Add them in the form builder first
A `hidden` object matches none of the form's declared keys	Every object needs at least one declared key
`expiry.days` present but not a positive number	Send `1`–`36524`, or omit `expiry` for the 90-day default
A bad or deactivated API token	Regenerate the token

Link behaviour after sending

A single-use link (the default) stops working once that recipient submits. Reopening it shows an “Invite link expired” screen rather than a fresh form.
An expired link shows the same screen once its window has elapsed.
A link with allowMultipleSubmission: true keeps accepting submissions until it expires.
Hidden values are recorded against every response collected through the link, so they show up alongside the answers in your results.

Example

Curl
Javascript
Python

curl --location --request POST 'https://core.pollpe.com/api/create-unique-links' \
--header 'Authorization: Bearer <YOUR_API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "surveyId": "XYZ000000",
  "properties": {
    "expiry": {
      "days": 2
    },
    "allowMultipleSubmission": false
  },
  "hidden": [
    {
      "hidden_parameter1": "value1",
      "hidden_parameter2": "value2",
      "hidden_parameter3": "value3"
    },
    {
      "hidden_parameter1": "value4",
      "hidden_parameter2": "value5",
      "hidden_parameter3": "value6"
    }
  ]
}'

var myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer <YOUR_API_TOKEN>");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify({
  "surveyId": "XYZ000000",
  "properties": {
    "expiry": {
      "days": 2
    },
    "allowMultipleSubmission": false
  },
  "hidden": [
    {
      "hidden_parameter1": "value1",
      "hidden_parameter2": "value2",
      "hidden_parameter3": "value3"
    },
    {
      "hidden_parameter1": "value4",
      "hidden_parameter2": "value5",
      "hidden_parameter3": "value6"
    }
  ]
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://core.pollpe.com/api/create-unique-links", requestOptions)
  .then(response => response.json())
  .then(result => {
    if (!result.success) {
      throw new Error('Invite links were not created');
    }
    console.log(result.invites);
  })
  .catch(error => console.log('error', error));

import http.client
import json

conn = http.client.HTTPSConnection("core.pollpe.com")
payload = json.dumps({
  "surveyId": "XYZ000000",
  "properties": {
    "expiry": {
      "days": 2
    },
    "allowMultipleSubmission": False
  },
  "hidden": [
    {
      "hidden_parameter1": "value1",
      "hidden_parameter2": "value2",
      "hidden_parameter3": "value3"
    },
    {
      "hidden_parameter1": "value4",
      "hidden_parameter2": "value5",
      "hidden_parameter3": "value6"
    }
  ]
})
headers = {
  'Authorization': 'Bearer <YOUR_API_TOKEN>',
  'Content-Type': 'application/json'
}
conn.request("POST", "/api/create-unique-links", payload, headers)
res = conn.getresponse()
result = json.loads(res.read().decode("utf-8"))

if not result.get("success"):
    raise RuntimeError("Invite links were not created")

for invite in result["invites"]:
    print(invite["surveyLink"])

🚀 Overview​

📤 Create Unique Links – API Reference​

🔗 Endpoint​

🔐 Headers​

Before you start​

Request Body​

Response Object​

⚠️ Checking the response​

Link behaviour after sending​

Example​

Contents