# Generate a survey link

Generate a single-use or reusable survey link for a questionnaire with the Pristo API, set when it expires, and attach custom fields to the response.

`POST https://api.pristo.io/v1/links/generate/{prjId}` creates a personal link to one Pristo CX questionnaire and returns its URL. You send the URL to a respondent in your own channel, such as a chat or a receipt, and the answers arrive with the questionnaire's other responses.

## Before you start

- API key: a key for the program, on the Standard or Pro plan. See [Authenticate with an API key](https://docs.pristo.io/cx/api/authentication).
- Questionnaire: published, and set to **Live** on its **Share** tab. See [Share a questionnaire](https://docs.pristo.io/cx/questionnaires/share-a-questionnaire).
- Questionnaire ID: the `prjId` of the questionnaire, a 22-character short ID.

## Steps

1. Select **Management** > **Questionnaires** and open the questionnaire.

2. Select **Share**.

3. In **Developer API**, copy the questionnaire ID. The same ID is in the browser's address bar after `/manage/projects/`.

4. Send a `POST` request to `https://api.pristo.io/v1/links/generate/` followed by the ID, with the headers `X-API-Key` and `Content-Type: application/json` and a JSON body. Send `{}` to use every default.

5. Send the `url` from the response to the respondent.

```bash
curl -X POST "https://api.pristo.io/v1/links/generate/QUESTIONNAIRE_ID" \
  -H "X-API-Key: $PRISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresInMinutes": 10080,
    "language": "en",
    "isReusable": false,
    "title": "Order 1042",
    "customFields": { "order_id": "1042", "channel": "chat" }
  }'
```

## Request body

Every field is optional, but the body itself is required.

| Field | Type | Default | What it does |
|---|---|---|---|
| `expiresInMinutes` | integer | No expiry | Minutes until the link expires, from 1 to 1,576,800 (3 years) |
| `isReusable` | boolean | `false` | `false` makes a single-use link. `true` lets the link collect a new response each time someone opens it |
| `language` | string | `he` | A two-letter ISO 639-1 code. Pristo CX stores it with the link, shows it in the response, and uses it for the page a respondent sees when the link has expired or was already used |
| `title` | string | None | A label for the link, up to 50 characters |
| `customFields` | object | None | Your own values, such as an order number. Keys and values are strings of up to 50 characters |

> **Note**
>
> The questionnaire opens in its own default language, whatever `language` says. To offer respondents other languages, see [Translate a questionnaire](https://docs.pristo.io/cx/form-builder/translate-a-questionnaire).

## Result

The API answers `200 OK`:

```json
{
  "linkId": "11111111-2222-3333-4444-555555555555",
  "url": "https://go.pristo.io/l/AbCdEfGhIjKlMnOpQrStUv"
}
```

`linkId` is a UUID. `url` opens the questionnaire. The link isn't tied to a contact in the population.

- A single-use link belongs to one response. Opening it again continues that response. After the respondent submits, the link opens a thank-you page instead of the questionnaire.
- A reusable link starts a new response every time it opens, until it expires.
- After `expiresInMinutes`, the link opens a page that says the survey has expired.

Account admins and program admins see the `title`, the `language` and every custom field in the response details, under **Link information**. Links made through the API don't appear in the links list on the **Share** tab.

## Limits

- `expiresInMinutes`: 1 to 1,576,800.
- `language`: exactly 2 letters, and a real ISO 639-1 code.
- `title`: up to 50 characters.
- `customFields`: string values only, keys and values up to 50 characters each.
- The request body can be at most 10,000 bytes.

## Troubleshooting

**The API returned 400 with `provided surveyId is not valid`.** The path doesn't end with the 22-character questionnaire ID. A full UUID doesn't work. Copy the ID from **Developer API**.

**The API returned 404 with `project with id … not found`.** No questionnaire with this ID exists in the API key's account, or it was deleted.

**The link opens, but not the questionnaire.** The questionnaire isn't published yet, or its **Share** tab shows **Paused**.

**The API returned another 400.** The plain-text body names the field. See [API errors](https://docs.pristo.io/cx/api/errors).

## Related

- [Share a questionnaire](https://docs.pristo.io/cx/questionnaires/share-a-questionnaire)
- [View responses](https://docs.pristo.io/cx/responses/view-responses)
- [Authenticate with an API key](https://docs.pristo.io/cx/api/authentication)
- [API errors](https://docs.pristo.io/cx/api/errors)
- [API reference: Generate a survey link](https://docs.pristo.io/cx/api/reference/operations/generatesurveylink)