Skip to content
PristoPristoPristo Help Center

Generate a survey link

POST
/v1/links/generate/{prjId}
curl --request POST \
  --url https://api.pristo.io/v1/links/generate/AbCdEfGhIjKlMnOpQrStUv \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "expiresInMinutes": 10080, "language": "en", "isReusable": false, "title": "Order 1042", "customFields": { "order_id": "1042", "channel": "chat" } }'

Creates a link to a questionnaire on https://go.pristo.io. By default the link is single-use and never expires. A single-use link belongs to one response: opening it again continues that response, and after the respondent submits it opens a thank-you page. A reusable link starts a new response each time it opens. The questionnaire opens in its own default language; language is stored with the link and used for the expired and thank-you pages. Every body field is optional, but the body is required: send {} to use every default.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
prjId
required
string
>= 22 characters <= 22 characters

The questionnaire’s 22-character short ID, shown on the questionnaire’s Share page in the manager app (see https://docs.pristo.io/cx/api/generate-a-survey-link). A full UUID is rejected.

Example
AbCdEfGhIjKlMnOpQrStUv

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
expiresInMinutes

Minutes until the link expires, up to 1,576,800 (3 years). Omit it for a link without an expiry date.

integer
>= 1 <= 1576800
language

Two-letter ISO 639-1 code stored with the link. It sets the language of the expired and thank-you pages and is shown in the response details. The questionnaire itself opens in its own default language.

string
default: he >= 2 characters <= 2 characters
isReusable

Set to true to let the link collect a new response each time it opens.

boolean
title

A label for the link, shown in the response details.

string
<= 50 characters
customFields

Your own values, such as an order number. Values must be strings; keys and values are at most 50 characters each. They appear in the response details in the manager app.

object
key
additional properties
string
<= 50 characters
Example
{
  "expiresInMinutes": 10080,
  "language": "en",
  "isReusable": false,
  "title": "Order 1042",
  "customFields": {
    "order_id": "1042",
    "channel": "chat"
  }
}

Responses

Section titled “Responses”

200

Section titled “200”

The link was created.

Media typeapplication/json
object
linkId
required
string format: uuid
url
required
string format: uri
Example
{
  "linkId": "11111111-2222-3333-4444-555555555555",
  "url": "https://go.pristo.io/l/AbCdEfGhIjKlMnOpQrStUv"
}

400

Section titled “400”

The request is invalid. Plain-text messages:

  • provided surveyId is not valid: prjId is not a 22-character short ID.
  • Payload size exceeds the maximum allowed size of 10000 bytes
  • expiresInMinutes must be between 1 and 1576800
  • language must be exactly 2 characters long (iso 639-1)
  • title must be at most 50 characters long
  • customField values must be strings
  • customField keys and values must be at most 50 characters long
  • Value is invalid: the X-API-Key value is shorter than 24 characters, or language is not an ISO 639-1 code.

A missing body, invalid JSON or a field of the wrong JSON type returns a JSON problem body instead.

string
Example
expiresInMinutes must be between 1 and 1576800

401

Section titled “401”

The X-API-Key header is missing or empty, or the key does not match an active key (wrong, deactivated or deleted).

Media typeapplication/problem+json

An RFC 9457 problem body.

object
type
string
title
string
status
integer
detail
string
traceId
string
Example
{
  "title": "Unauthorized",
  "status": 401
}

404

Section titled “404”

No questionnaire with this ID in the API key’s account, or the questionnaire was deleted. The message contains the questionnaire’s UUID.

Media typetext/plain
string
Example
project with id 11111111-2222-3333-4444-555555555555 not found

415

Section titled “415”

The Content-Type header is not application/json.

Media typeapplication/problem+json

An RFC 9457 problem body.

object
type
string
title
string
status
integer
detail
string
traceId
string
Example
{
  "title": "Unsupported Media Type",
  "status": 415
}

500

Section titled “500”

The server could not create the link. The JSON problem body’s detail is project does not have a form associated or a problem occurred, please try again later. An unexpected failure returns the plain-text body Internal server error.

An RFC 9457 problem body.

object
type
string
title
string
status
integer
detail
string
traceId
string
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "traceId": "example"
}