# Introduction
## Welcome to Pristo Docs!
Pristo is the solution for all your data collection projects.
Why? Because you can easily deploy forms and surveys, make changes to all aspects of a project in the blink of an eye, and get projects done on time and within budget. No coding required.
***
## New to Pristo?
After completing the sign-up process, you can proceed to create your first survey:
✅ [Create your first survey](/manager/creating-a-new-questionnaire)
# Creating a new project
When you first log in to Pristo, you'll be taken to the dashboard. From here, there are two ways to create a new project.
To create a new project from the **Recent projects** section:
1. From the Dashboard, click on the **+ New project** button.
2. Enter a **Project name.** This will open the form setup popup.
3. In the form setup popup:
1. Enter a **Form title**.
2. Select a pre-made template of create a blank form.
3. Click on the **Create** button.
To create a new project from the **Navigation menu** on the left:
1. From the Navigation menu, click on the **dropdown menu**.
2. Click on the **+ Add new project** button at the bottom.
3. Enter a **Project name.** This will open the form setup popup.
4. In the form setup popup:
1. Enter a **Form title**.
2. Select a pre-made template of create a blank form.
3. Click on the **Create** button.
# Creating a new questionnaire
There are two ways to create a new survey:
To create a new questionnaire from the **Surveys menu**:
1. From the Navigation menu on the left, click on the **Survey dropdown menu**.
2. In the menu, click on **+Add new survey** at the bottom of the list.
3. In the survey setup popup:
1. Give a name to your survey in **Survey title**.
2. You can choose a color for your survey.
3. Click on the **Create** button. You'll be redirected to a page where you can choose a blank questionnaire or select on of our free templates.
To create a new questionnaire from the **Recent surveys** section:
1. From the Dashboard, click on the **+ New survey** button. This will open the form setup popup.
2. In the survey setup popup:
1. Give a name to your survey in **Survey title**.
2. You can choose a color for your survey.
3. Click on the **Create** button. You'll be redirected to a page where you can choose a blank questionnaire or select on of our free templates.
From the Dashboard, click on the + New survey button
# Edit a questionnaire
To edit an existing questionnaire:
1. Select the survey that contains the questionnaire you want to edit.
2. From the navigation menu on the left, click on **Questionnaire**.
3. You'll be redirected to the Form builder to edit your questionnaire.
# Share a survey
After publishing your survey, you'd want to share it with your audience and start getting responses to your survey.
To share your published survey:
1. From the navigation menu, click on **Share**.
2. Select how you'd like to share your survey. There are 3 available methods:
1. Share a link
2. Embed the code on a website
3. Share a QR code
3. Click on your preferred method.
# Viewing collected responses
You've created and shared a survey, now it's time to view all the collected data.
To view collected responses:
1. From the navigation menu, click on **Responses**.
2. Using the filters, you can choose a specific dates and statuses you wish to see.
All your responses will be listed in the table below.
{% hint style="info" %}
You'll get an email when your first response comes in
{% endhint %}
***
**KPI's bar**
At the top of the page you'll see a quick preview of the responses collected for this survey:
Total responses, responses received in the last 7 days and responses received today.
**Sorting columns:**
To sort entries in a specific column:
1. Click on the column title for ascending sorting.
2. Click again to sort change to descending sorting.
**Filter columns:**
To filter entries in ascending or descending order:
1. Hover over the column and click the filter button next to the specific column.
2. Select the filter you'd like to assign to the column.
3. To remove the filter and restore to the default state: click on the filter button, select **Contains** and make sure the Filter textbox is empty.
**Show/hide columns:**
To show or hide any columns from the table view:
1. Click the **Columns** filter at the top of the table.
2. Select/unselect the required columns.
# Export survey data
After collecting responses to your survey, you can generate a comprehensive report to gain a deeper understanding of the collected data.
To export your form data:
1. From the navigation menu go to **Export**.
2. Click on **+ New export** button.
3. Select your preferred format, dates and select the form you'd like to export.
4. Click on the **Export** button.
5. After the file is ready, click on **Download** to view the data.
{% hint style="info" %}
Some of the export options are only available to **Pro** and **Enterprise** plans
{% endhint %}
When ready for download the export file will appear in the list
# Change language
To change Pristo's default language:
1. In the manager, click on your profile picture in the top-right corner.
2. Click on **User settings.**
3. Select your preferred language from the list.
4. The language will change automatically. You can close the window.
Click on User settings
Choose your preferred language
# Adding fields
There are two ways to add a new field to your survey:
**Inside a section**
1. Hover over or under an existing field
2. Click on the **+** button
3. Select the field type you wish to add
**From an existing field**
1. Hover over an existing field
2. Click on the **+** button on the right
3. Inside the added field area, click on the **+** button
4. Select the field type you wish to add
# Adding a new page
To add more pages to your survey:
1. Click on **+ Add page button** that is located above your first section.
2. Change the page name.
3. Add fields and sections as needed.
# End page
It's important to address your audience after they've submitted a survey in order to maintain engagement and enhance the user experience.
You can choose whether to show a Thank you page to your respondents, or redirect them to another website.
To display a **Thank You page** to your respondents acknowledging their submission once they submit a survey entry:
1. Click on **End page** at the top of the survey.
2. In the settings panel on the right, fill in a title and a subtitle. You'll see a live preview of how it will appear to your users.
3. Changes are saved automatically. You can go back to editing your survey.
To redirect your respondents to a different **URL**:
1. Click on **End page** at the top of the survey.
2. In the settings panel on the right, select **Redirect to URL**.
3. Enter the website URL you wish to redirect users to.
4. Changes are saved automatically. You can go back to editing your survey.
# Previewing your survey
You've finished working on your survey and want to preview it before sharing it with your audience.
The survey preview feature provides you with an accurate representation of how the survey will appear to your users.
To see a preview of your survey:
1. At the top right, click on the **Preview** button.
2. A popup window with your form will open. Here you can see how your form will look on different devices - Web, tablet and mobile.
3. After you've made sure that the form looks and works as you wish, close the popup to go back to the form builder.
# Publishing your survey
Now that you've made sure your survey is ready, it's time to publish it with your users.
To publish your survey:
1. At the top right, click the **Publish** button.
2. In the window that will open up you can add your version release notes (not required).
3. Click on **Publish**.
4. A success message will appear when the survey is published. You will be automatically redirected to the [Share page](/manager/share-a-survey).
# Translating a survey (Localization)
By default, your survey language will be the one used to build your survey. [Learn more ](/manager/change-language)about changing Pristo's language.
To add a language translation to your survey:
1. After building your survey, navigate to the **Localizations** from the left menu.
2. At the top left, click on to add a new localization.
3. Inside the translation window, choose a language to translate to from the dropdown menu.
4. Add the appropriate translation for each part of your survey. Changes are automatically saved.
{% hint style="info" %}
You can add more than one translation to each survey
{% endhint %}
Adding a language to localization
Once you add a translation to the survey, your user will be able to change the survey to that language. You can also see the new translation in the [**Preview** ](/form-builder/previewing-your-survey)window.
Preview your survey in different languages
# Managing populations
A Population is the database of contacts (respondents) linked to your project. Before you can send any surveys via SMS or Email, you must have a population set up. This list acts as the source for all your distribution campaigns.
#### Overview
To view your current contact lists, click on Population in the left-hand menu.
The main dashboard provides a quick summary of your available lists, including:
* Name: The label given to the contact list (e.g., "Tests" or "Customer List Q1").
* Number of Contacts: The total number of valid recipients currently in the list.
* Number of Unsubscribed: A count of contacts who have opted out of receiving messages. The system automatically excludes these users from future distributions to ensure compliance.
* Creation Date: The date the list was originally created or linked to the project.
#### Inside a Population
When you click on a specific population, you enter its management screen. If the list is new, you will see options to start building your database:
* Import contacts: For uploading bulk lists via Excel or CSV.
* Add contact: For manually adding single individuals.
* Contact attributes: For defining custom fields (like Department, City, or Purchase Date) before you upload data.
Once your list is populated, clicking on its name (e.g., "Customer List Q1") opens the detailed management view. Here you will see a table listing your individual contacts.
# Adding a new population
To send surveys, you must populate your project with contacts. A population is typically added by importing a data file (CSV or Excel) containing your respondent details.
#### Creating a new population from a file
To send surveys, you must populate your project with contacts. There are two primary methods to do this: importing a bulk data file or adding contacts manually.
#### Importing Contacts from a File
For most distributions, you will upload a data file (CSV or Excel) containing your respondent details. This allows you to add thousands of contacts at once.
**Preparing Your Data**
Before adding a new list, ensure your file is formatted correctly to work with the Distribution and Personalization features:
* Essential Contact Info:
* Phone Number: Required if you plan to use SMS or WhatsApp distributions.
* Email Address: Required if you plan to use Email distributions.
* Personalization Fields: Include columns for details like First Name or Last Name. These will allow you to use dynamic variables (e.g., `{{Name}}`) in your message wording later.
* Segmentation Data: If you plan to filter your audience (e.g., "Send only to customers in New York"), ensure your file includes these specific attributes (like `City`, `Age`, or `Purchase Date`) as separate columns.
To import contacts from a file:
1. Navigate to the **Population** tab in the left-hand menu.
2. Name your list: Enter a unique name for this group (e.g., "Q1 Customers" or "Employee List 2026") and save.
3. Click on the **Import contacts** button.
4. Upload File your CSV or Excel file into the upload window.
5. Map Columns: The system will ask you to match the columns in your file to the fields in the database.
* *Example:* Map your "Cell Phone" column to the system's "Phone Number" field.
5. Click **Next**. The system will now scan your file to check if the columns are mapped correctly and if the required data is present.
6. Only after receiving a confirmation that the data is valid can you click the **Import** button to finalize the process.
#### Manual Entry
You can also add contacts one by one directly through the interface. This is often used for:
* Testing: Adding yourself or a colleague to verify that SMS/Email links work correctly before sending to real customers.
* Quick Updates: Adding a specific VIP client or a new employee without needing to re-upload an entire spreadsheet.
To add a single contact:
1. Navigate to the specific Population list you wish to update.
2. Click on **+Add Contact**.
3. Add personalization details like First Name or Last Name to enable dynamic variables in your messages.
4. Fill in the essential details required for your distribution channel (Phone Number or Email Address).
# Introduction to distributions
To start collecting responses via SMS or email, you need to set up a Distribution. This is where you decide your delivery strategy—like sending a one-time blast or setting up an automatic trigger after a purchase—and choose how much respondent information you want to track.
### Distribution Types
The distribution type determines the logic behind how and when your SMS or email invitations are sent out.
* **One-time Delivery:** Best for standard research projects where you have a fixed list of contacts and want to send the survey to everyone at once or in a single scheduled batch.
* **Ongoing/Periodic Survey:** Ideal for "always-on" feedback loops, such as employee pulse checks or long-term customer satisfaction tracking. This allows you to automatically sample a portion of your audience (e.g., 10%) over a set period (e.g., every quarter).
* **Event-Based Survey:** Designed for high-relevance feedback. The survey is triggered by a specific action—like a customer completing a purchase—and sent after a predefined delay to capture their thoughts while the experience is still fresh.
### Anonymity Levels
The anonymity level defines the relationship between the respondent's identity and their data. This is a critical choice for building trust with your audience.
* **Fully Anonymous Survey:** Use this when total privacy is the priority. You will not be able to see who opened the link or which individual provided which answer. This is often used for sensitive internal feedback where respondents need to feel safe being completely honest.
* **Anonymous Survey with Response Status Tracking:** This is the "middle ground." It allows you to see a list of who has and hasn't completed the survey—which is perfect for sending targeted reminders to those who forgot—but the actual answers remain disconnected from their names.
* **Full Tracking:** This provides the most data-rich results. Every response is linked to a specific contact, allowing you to follow up on specific complaints, reward loyal customers, or perform detailed demographic analysis.
{% hint style="info" %}
Once a distribution begins collecting data, the Anonymity Level is locked. This protects the integrity of the promise made to your respondents regarding their privacy.
{% endhint %}
# Creating a distribution
To start sending your survey via SMS or email, you must first create a distribution. This process allows you to define your audience, choose your delivery method, and set your preferred privacy levels.
{% hint style="info" %}
Before creating a distribution, ensure that a Population (contact list) is linked to your project. You cannot distribute a survey without a source of contacts.
{% endhint %}
To begin setting up a new distribution, follow these steps:
1. Click on **Distributions** in the left-hand menu, which is accessible from any page in the platform.
2. Click on the **+ New distribution** button.
3. In the Description field, provide a short description or name for the distribution. This name will help you identify the data source later when exporting your results.
{% hint style="info" %}
Use descriptive names like "Customer satisfaction May 2025" to make your data analysis more efficient later on.
{% endhint %}
4. Under Distribution Type, select the option that matches your goal:
* **One-time Delivery:** For sending a single batch to a specific list.
* **Ongoing/Periodic Survey:** For recurring surveys sent to a percentage of your audience.
* **Event-Based Survey:** For surveys triggered by a specific customer action.
5. Choose your Anonymity Level to determine how much respondent data you wish to track.
6. Click **Next** to save these settings and move to the specific configuration for your chosen type.
# One-time Delivery
A One-time Delivery is the standard method for sending a survey to a specific group of people in a single batch. It is ideal for ad-hoc research, marketing campaigns, or annual feedback cycles where you have a fixed list of contacts.
{% hint style="info" %}
Before creating a distribution, ensure that a Population (contact list) is linked to your project. You cannot distribute a survey without a source of contacts.
{% endhint %}
To configure a One-time Delivery, follow these steps:
1. Under **Distribution Type**, select One-time Delivery.
2. In the **Schedule Delivery** section that appears, choose when you want the invitations to be sent:
* **Immediate Delivery:** The surveys will be sent out as soon as you activate the distribution process.
* **Scheduled Delivery:** This allows you to select a precise future date and time for the survey to be sent.
3. Choose your **Anonymity Level** to determine how much respondent data you wish to track.
4. Click **Next** to proceed to the Samples tab where you will select your contact list.
***
## Defining the Sample
The **Samples** tab allows you to refine which contacts from your population will receive the survey and set limits on how often they can be contacted.
{% hint style="info" %}
These settings are optional. If you make no changes here, the survey will be sent to *all* contacts in your linked population with no frequency restrictions.
{% endhint %}
To configure your sample and distribution rules, follow these steps:
1. Under **Sampling Segmentation**, you can filter the specific group of contacts to receive this survey. If no segment is added, all contacts in the population will be included by default.
* ***Example:** You can add a rule to only include contacts where "City" is equal to "New York" or where "Age" is "Over 25".*
2. In the **Distribution Rules** section, you can set a global "cool-down" period. This prevents the system from sending this questionnaire to anyone who has received *any* survey from your account within the last X days.
3. You can also set a specific cool-down for this process. If a respondent is eligible to receive this survey more than once, define the minimum wait time between sends (e.g., "Wait between sending... at least 30 days").
4. Click **Next** to proceed to the Wording tab.
{% hint style="info" %}
If you leave the Distribution Rules at "0", the system will not check for recent activity and will send the survey regardless of when the contact was last messaged.
{% endhint %}
***
## Customizing the Message
The Wording tab is where you design the actual message your respondents will receive. You can choose your delivery channel, draft your content, and use dynamic variables to make each invitation feel personal.
To configure your message settings, follow these steps:
1. Under **Distribution Channel & Type**, select the method you want to use for this specific batch. You can choose between SMS, Email, or WhatsApp.
2. In the **Message content editor**, write the text of your invitation. Keep it clear and concise to encourage a higher response rate.
3. Click on the **Add variable** dropdown to insert dynamic fields. This automatically pulls specific details from your contact list into the message, ensuring each recipient feels personally addressed.
* {{Name}}: "Hi *{{Name}}*, thanks for visiting..." becomes "Hi *John*, thanks for visiting..."
* {{Last name}}: "Dear Mr. *{{Last name}}*..." becomes "Dear Mr. *Doe*..."
* {{Email}}: "We sent a confirmation to *{{Email}}*..."
4. Review the **Preview** section at the bottom to see exactly how the message will look on the user's device. Verify that the automated survey link and unsubscribe link appear correctly.
5. Click **Next** to complete the setup.
***
## Activating the Distribution
Once you have finished configuring the settings, samples, and wording, your distribution is created but remains in an Inactive state by default. This safety measure ensures that no surveys are sent until you explicitly confirm the campaign is ready to go.
To activate your distribution, follow these steps:
1. Locate your new distribution in the list. You will see its status marked as Inactive highlighted in red.
2. Click on the three dots (menu icon) located at the far right of the distribution row.
3. Select **Activate** from the dropdown menu.
4. The status will change to Active, and the system will begin processing the queue according to your schedule (either sending immediately or waiting for the scheduled time/trigger).
{% hint style="info" %}
Before activating the live campaign, use the Send test option in the same menu. This allows you to send a sample SMS or Email to yourself to verify exactly how it looks on a real device.
{% endhint %}
# Event-Based Survey
An Event-Based Survey is a transactional tool triggered by specific customer actions. It is ideal for capturing feedback immediately after an interaction, such as a support ticket closing, a product delivery, or a completed course.
{% hint style="info" %}
Before creating a distribution, ensure that a Population (contact list) is linked to your project. You cannot distribute a survey without a source of contacts.
{% endhint %}
To configure an Event-Based Survey, follow these steps:
1. Under **Distribution Type**, select Event-Based Survey.
2. In the **Event Settings** section, configure the specific rules that will trigger the survey:
* **Define Event Rules:** Use the dropdown menus to specify which events qualify for a survey. You can filter by event type and specific values (e.g., "Course Completion" *Equals* "Accounting").
* **Add Multiple Triggers:** You can add multiple event rules by clicking **+ Add additional event** to cover different scenarios in a single campaign.
3. Set the **Delay Timer** at the bottom of the section to decide exactly when the invitation should be sent. You can specify the delay in Days, Hours, and Minutes after the event occurs.
4. Choose your **Anonymity Level** to determine how much respondent data you wish to track.
5. Click **Next** to proceed to the Samples tab.
***
## Defining the Sample
The **Samples** tab allows you to refine which contacts from your population will receive the survey and set limits on how often they can be contacted.
{% hint style="info" %}
These settings are optional. If you make no changes here, the survey will be sent to *all* contacts in your linked population with no frequency restrictions.
{% endhint %}
To configure your sample and distribution rules, follow these steps:
1. Under **Sampling Segmentation**, you can filter the specific group of contacts to receive this survey. If no segment is added, all contacts in the population will be included by default.
* ***Example:** You can add a rule to only include contacts where "City" is equal to "New York" or where "Age" is "Over 25".*
2. In the **Distribution Rules** section, you can set a global "cool-down" period. This prevents the system from sending this questionnaire to anyone who has received *any* survey from your account within the last X days.
3. You can also set a specific cool-down for this process. If a respondent is eligible to receive this survey more than once, define the minimum wait time between sends (e.g., "Wait between sending... at least 30 days").
4. In the **Schedule Delivery** section, choose the specific days and times for distributing the surveys. You can use the "08:00-20:00" button at the top to quickly apply standard daytime delivery hours to all days. Alternatively, check the boxes next to individual days (e.g., Monday) and define custom active time windows using the "From" and "To" dropdowns (e.g., 10:00:00 to 11:00:00). This ensures triggered messages are only delivered during appropriate hours.
5. Click **Next** to proceed to the Wording tab.
***
## Customizing the Message
The Wording tab is where you design the actual message your respondents will receive. You can choose your delivery channel, draft your content, and use dynamic variables to make each invitation feel personal.
To configure your message settings, follow these steps:
1. Under **Distribution Channel & Type**, select the method you want to use for this specific batch. You can choose between SMS, Email, or WhatsApp.
2. In the **Message content editor**, write the text of your invitation. Keep it clear and concise to encourage a higher response rate.
3. Click on the **Add variable** dropdown to insert dynamic fields. This automatically pulls specific details from your contact list into the message, ensuring each recipient feels personally addressed.
* {{Name}}: "Hi *{{Name}}*, thanks for visiting..." becomes "Hi *John*, thanks for visiting..."
* {{Last name}}: "Dear Mr. *{{Last name}}*..." becomes "Dear Mr. *Doe*..."
* {{Email}}: "We sent a confirmation to *{{Email}}*..."
4. Review the **Preview** section at the bottom to see exactly how the message will look on the user's device. Verify that the automated survey link and unsubscribe link appear correctly.
5. Click **Next** to complete the setup.
***
## Activating the Distribution
Once you have finished configuring the settings, samples, and wording, your distribution is created but remains in an Inactive state by default. This safety measure ensures that no surveys are sent until you explicitly confirm the campaign is ready to go.
To activate your distribution, follow these steps:
1. Locate your new distribution in the list. You will see its status marked as Inactive highlighted in red.
2. Click on the three dots (menu icon) located at the far right of the distribution row.
3. Select **Activate** from the dropdown menu.
4. The status will change to Active, and the system will begin processing the queue according to your schedule (either sending immediately or waiting for the scheduled time/trigger).
{% hint style="info" %}
Before activating the live campaign, use the Send test option in the same menu. This allows you to send a sample SMS or Email to yourself to verify exactly how it looks on a real device.
{% endhint %}
# Ongoing/Periodic Survey
An Ongoing/Periodic Survey is designed for "always-on" research. Instead of emailing everyone at once, this method allows you to continuously sample a small percentage of your audience over time. This is ideal for tracking Customer Satisfaction (CSAT) or Employee Engagement (eNPS) trends without causing survey fatigue.
{% hint style="info" %}
Before creating a distribution, ensure that a Population (contact list) is linked to your project. You cannot distribute a survey without a source of contacts.
{% endhint %}
To configure an Ongoing/Periodic Survey, follow these steps:
1. Under **Distribution Type**, select Ongoing/Periodic Survey.
2. In the **Schedule Delivery** section, define the active time window for sending surveys:
* **Days of the week:** Select the specific days (e.g., Sunday through Thursday) when the system is permitted to send invitations.
* **Time range:** Set the start and end time (e.g., 09:00 to 17:00) to ensure surveys are only sent during appropriate hours.
3. Choose your **Anonymity Level** to determine how much respondent data you wish to track.
4. Click **Next** to proceed to the Samples tab.
***
## Defining the Sample
The **Samples** tab allows you to refine which contacts from your population will receive the survey and set limits on how often they can be contacted.
{% hint style="info" %}
These settings are optional. If you make no changes here, the survey will be sent to *all* contacts in your linked population with no frequency restrictions.
{% endhint %}
To configure your sample and distribution rules, follow these steps:
1. Under **Sampling Segmentation**, you can filter the specific group of contacts to receive this survey. If no segment is added, all contacts in the population will be included by default.
* ***Example:** You can add a rule to only include contacts where "City" is equal to "New York" or where "Age" is "Over 25".*
2. In the **Distribution Rules** section, you can set a global "cool-down" period. This prevents the system from sending this questionnaire to anyone who has received *any* survey from your account within the last X days.
3. You can also set a specific cool-down for this process. If a respondent is eligible to receive this survey more than once, define the minimum wait time between sends (e.g., "Wait between sending... at least 30 days").
4. Click **Next** to proceed to the Wording tab.
{% hint style="info" %}
If you leave the Distribution Rules at "0", the system will not check for recent activity and will send the survey regardless of when the contact was last messaged.
{% endhint %}
***
## Customizing the Message
The Wording tab is where you design the actual message your respondents will receive. You can choose your delivery channel, draft your content, and use dynamic variables to make each invitation feel personal.
To configure your message settings, follow these steps:
1. Under **Distribution Channel & Type**, select the method you want to use for this specific batch. You can choose between SMS, Email, or WhatsApp.
2. In the **Message content editor**, write the text of your invitation. Keep it clear and concise to encourage a higher response rate.
3. Click on the **Add variable** dropdown to insert dynamic fields. This automatically pulls specific details from your contact list into the message, ensuring each recipient feels personally addressed.
* {{Name}}: "Hi *{{Name}}*, thanks for visiting..." becomes "Hi *John*, thanks for visiting..."
* {{Last name}}: "Dear Mr. *{{Last name}}*..." becomes "Dear Mr. *Doe*..."
* {{Email}}: "We sent a confirmation to *{{Email}}*..."
4. Review the **Preview** section at the bottom to see exactly how the message will look on the user's device. Verify that the automated survey link and unsubscribe link appear correctly.
5. Click **Next** to complete the setup.
***
## Activating the Distribution
Once you have finished configuring the settings, samples, and wording, your distribution is created but remains in an Inactive state by default. This safety measure ensures that no surveys are sent until you explicitly confirm the campaign is ready to go.
To activate your distribution, follow these steps:
1. Locate your new distribution in the list. You will see its status marked as Inactive highlighted in red.
2. Click on the three dots (menu icon) located at the far right of the distribution row.
3. Select **Activate** from the dropdown menu.
4. The status will change to Active, and the system will begin processing the queue according to your schedule (either sending immediately or waiting for the scheduled time/trigger).
{% hint style="info" %}
Before activating the live campaign, use the Send test option in the same menu. This allows you to send a sample SMS or Email to yourself to verify exactly how it looks on a real device.
{% endhint %}
# API Introduction
### Overview
The **Pristo API** allows external systems to securely integrate with Pristo in order to manage contacts, send events, and synchronize operational and customer-related data.
The API is designed using a **RESTful, design-first approach**, with predictable resource-oriented URLs, standard HTTP methods, and structured JSON payloads.\
All endpoints are documented and versioned to ensure backward compatibility and safe evolution over time.
This documentation describes **Pristo API V1**, which is intended for production integrations.
###
### API Base URL & Versioning
All API requests are made against a versioned base URL:
```
https://api.pristo.example.com/v1
```
* Versioning is handled via the URL path (`/v1`)
* Breaking changes will be introduced only in new major versions
* Minor, backward-compatible enhancements may be added within the same version
### Authentication
The Pristo API uses **API Key authentication**.
#### How Authentication Works
* Each request must include a valid API key
* The API key identifies the client system and controls access permissions
* Requests without a valid API key will be rejected
#### Authentication Header
Include the API key in every request header:
```
X-API-Key: YOUR_API_KEY
```
#### Security Notes
* API keys should be kept secret and never exposed in client-side code
* Rotate API keys periodically according to your security policy
* Requests over HTTP are not supported — HTTPS is required
###
### Obtaining an API Key
Follow these steps to generate your unique key:
1\. Click on your **Profile** icon in the top right corner.
2\. Select **Account Settings** from the dropdown menu.
3\. Navigate to the **API Keys** tab and click the "**+Add**" button.
4. Enter a descriptive name for the key so you can easily identify it later.
5. **Copy** the new key immediately. Store it securely, as it will not be displayed again.
{% hint style="info" %}
Your API key will only be displayed once. You will not be able to view it again after closing the window.
{% endhint %}
###
### Request & Response Format
#### Content Type
All requests and responses use JSON:
```
Content-Type: application/json
Accept: application/json
```
#### Date & Time Format
All timestamps use **ISO 8601** format in UTC:
```
YYYY-MM-DDTHH:mm:ssZ
```
Example:
```
2026-02-04T13:25:00Z
```
# Contacts
Contacts management
## Create or update a contact
> Creates or updates a contact using a \*\*client-owned identifier\*\*.\
> The \`contact.id\` field is mandatory and represents the identifier used by the client system.\
> Optional fields (email, phone, language, name, etc.) will update the existing contact if provided.\
> Additional properties are treated as custom fields.
```json
{"openapi":"3.0.3","info":{"title":"Pristo Public API","version":"1.0.0"},"tags":[{"name":"Contacts","description":"Contacts management"}],"servers":[{"url":"https://api.pristo.io","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key (UUID)"}},"parameters":{"populationId":{"name":"populationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Population identifier (UUID)"},"requestIdHeader":{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional request correlation ID"}},"schemas":{"ContactUpsertRequest":{"type":"object","required":["contact"],"properties":{"contact":{"$ref":"#/components/schemas/Contact"}}},"Contact":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"Client-owned contact identifier"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"language":{"type":"string","description":"ISO 639-1 language code (e.g. en, he)"},"name":{"type":"string"},"lastName":{"type":"string"},"customFields":{"type":"object","description":"Dynamic contact fields (string values). Keys must match fields defined on the population.","additionalProperties":{"type":"string","maxLength":255}}},"additionalProperties":false},"ContactResponse":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}},"headers":{"requestId":{"schema":{"type":"string","format":"uuid"},"description":"Request correlation ID"}},"responses":{"BadRequest":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/contacts/save/{populationId}":{"post":{"tags":["Contacts"],"summary":"Create or update a contact","description":"Creates or updates a contact using a **client-owned identifier**.\nThe `contact.id` field is mandatory and represents the identifier used by the client system.\nOptional fields (email, phone, language, name, etc.) will update the existing contact if provided.\nAdditional properties are treated as custom fields.\n","operationId":"upsertContact","parameters":[{"$ref":"#/components/parameters/populationId"},{"$ref":"#/components/parameters/requestIdHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactUpsertRequest"}}}},"responses":{"200":{"description":"Contact updated","headers":{"X-Request-Id":{"$ref":"#/components/headers/requestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactResponse"}}}},"201":{"description":"Contact created","headers":{"X-Request-Id":{"$ref":"#/components/headers/requestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```
# Events
Events ingestion.
## Send an event
> Reports an event that occurred for a specific contact.\
> \
> The payload must include the contact identifier (\`contact.id\`). If this is the first time you report this contact, you must also provide at least one reachable identifier: \`contact.phone\` or \`contact.email\`.\
> \
> You can report events for contacts that do not yet exist in Pristo. In that case, Pristo will create the contact and add it to the population. If the contact already exists, its details will be updated according to the contact data you send.\
> \
> For the contact, you can send built-in fields or custom fields.\
> Built-in contact fields: \`id\` (required), \`email\`, \`phone\`, \`language\`, \`name\`, \`lastName\`.\
> Custom contact fields are fields you define on your population (e.g., \`gender\`, \`age\`) and are sent under \`contact.customFields\`.\
> \
> For the event itself, you can send built-in fields or custom fields.\
> Built-in event fields: \`type\` (required; must be defined in Pristo), \`occurredAt\` (optional timestamp).\
> Custom event fields are fields you attach to events (e.g., \`channel\`, \`purchaseAmount\`, \`transactionId\`) and are sent under \`customFields\`. All custom field values must be strings and are limited to 50 characters.
```json
{"openapi":"3.0.3","info":{"title":"Pristo Public API","version":"1.0.0"},"tags":[{"name":"Events","description":"Events ingestion."}],"servers":[{"url":"https://api.pristo.io","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key (UUID)"}},"parameters":{"populationId":{"name":"populationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Population identifier (UUID)"},"requestIdHeader":{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional request correlation ID"}},"schemas":{"SendEventRequest":{"type":"object","required":["contact","type"],"properties":{"contact":{"$ref":"#/components/schemas/Contact"},"type":{"type":"string","description":"Event type identifier"},"occurredAt":{"$ref":"#/components/schemas/IsoDateTime"},"customFields":{"type":"object","description":"Dynamic event fields (string values).","additionalProperties":{"type":"string","maxLength":255}}},"additionalProperties":false},"Contact":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"Client-owned contact identifier"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"language":{"type":"string","description":"ISO 639-1 language code (e.g. en, he)"},"name":{"type":"string"},"lastName":{"type":"string"},"customFields":{"type":"object","description":"Dynamic contact fields (string values). Keys must match fields defined on the population.","additionalProperties":{"type":"string","maxLength":255}}},"additionalProperties":false},"IsoDateTime":{"type":"string","format":"date-time"},"SendEventResponse":{"type":"object","required":["ok","status","statusText","raw"],"properties":{"ok":{"type":"boolean","description":"Indicates whether the request succeeded."},"status":{"type":"integer","description":"Application-level status code returned by the API."},"statusText":{"type":"string","description":"Application-level status text returned by the API."},"body":{"nullable":true,"description":"Optional response body. Null when no structured body is returned."},"raw":{"type":"string","description":"Raw response value returned by the API."}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}},"responses":{"BadRequest":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"ServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/events/send/{populationId}":{"post":{"tags":["Events"],"summary":"Send an event","description":"Reports an event that occurred for a specific contact.\n\nThe payload must include the contact identifier (`contact.id`). If this is the first time you report this contact, you must also provide at least one reachable identifier: `contact.phone` or `contact.email`.\n\nYou can report events for contacts that do not yet exist in Pristo. In that case, Pristo will create the contact and add it to the population. If the contact already exists, its details will be updated according to the contact data you send.\n\nFor the contact, you can send built-in fields or custom fields.\nBuilt-in contact fields: `id` (required), `email`, `phone`, `language`, `name`, `lastName`.\nCustom contact fields are fields you define on your population (e.g., `gender`, `age`) and are sent under `contact.customFields`.\n\nFor the event itself, you can send built-in fields or custom fields.\nBuilt-in event fields: `type` (required; must be defined in Pristo), `occurredAt` (optional timestamp).\nCustom event fields are fields you attach to events (e.g., `channel`, `purchaseAmount`, `transactionId`) and are sent under `customFields`. All custom field values must be strings and are limited to 50 characters.","operationId":"sendEvent","parameters":[{"$ref":"#/components/parameters/populationId"},{"$ref":"#/components/parameters/requestIdHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEventRequest"}}}},"responses":{"201":{"description":"Event stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEventResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/ServerError"}}}}}}
```
# Sharable Links
Generate shareable survey links
## Generate a shareable survey link
> Generates a dedicated, shareable link for a survey so you can distribute it independently.\
> The response is returned as JSON and contains the generated link identifier and URL.\
> Optional built-in fields:\
> \- \`expiresInMinutes\`: How long the link should stay active. If omitted, the link has no expiration.\
> \- \`language\`: The language to open the survey in. If omitted, the survey is shown in its default language.\
> \- \`isReusable\`: Indicates whether the link can be used multiple times. If omitted, the link is single-use.\
> \- \`title\`: A user-friendly name for the link, used for display in the UI.\
> \- \`customFields\` can contain any fields you want to attach to the generated link (e.g., conversation id, channel, campaign). All custom field values must be strings and are limited to 50 characters.
```json
{"openapi":"3.0.3","info":{"title":"Pristo Public API","version":"1.0.0"},"tags":[{"name":"Sharable Links","description":"Generate shareable survey links"}],"servers":[{"url":"https://api.pristo.io","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key (UUID)"}},"parameters":{"requestIdHeader":{"name":"X-Request-Id","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"Optional request correlation ID"}},"schemas":{"GenerateLinkRequest":{"type":"object","properties":{"expiresInMinutes":{"type":"integer","minimum":1,"description":"How long the link should stay active. If omitted, the link does not expire."},"language":{"type":"string","description":"Language to open the survey in. If omitted, the survey default language is used."},"isReusable":{"type":"boolean","description":"Indicates whether the generated link can be used multiple times. If omitted, the link is single-use."},"title":{"type":"string","description":"User-friendly name for the generated link, used for display in the UI."},"customFields":{"type":"object","description":"Custom fields to attach to the generated link. Values must be strings (max 50 characters).","additionalProperties":{"type":"string","maxLength":50}}},"additionalProperties":false},"GenerateLinkResponse":{"type":"object","required":["linkId","url"],"properties":{"linkId":{"type":"string","format":"uuid","description":"Unique identifier of the generated shareable link."},"url":{"type":"string","format":"uri","description":"The generated shareable link URL."}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}},"headers":{"requestId":{"schema":{"type":"string","format":"uuid"},"description":"Request correlation ID"}},"responses":{"BadRequest":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/links/generate/{surveyId}":{"post":{"tags":["Sharable Links"],"summary":"Generate a shareable survey link","description":"Generates a dedicated, shareable link for a survey so you can distribute it independently.\nThe response is returned as JSON and contains the generated link identifier and URL.\nOptional built-in fields:\n- `expiresInMinutes`: How long the link should stay active. If omitted, the link has no expiration.\n- `language`: The language to open the survey in. If omitted, the survey is shown in its default language.\n- `isReusable`: Indicates whether the link can be used multiple times. If omitted, the link is single-use.\n- `title`: A user-friendly name for the link, used for display in the UI.\n- `customFields` can contain any fields you want to attach to the generated link (e.g., conversation id, channel, campaign). All custom field values must be strings and are limited to 50 characters.","operationId":"generateLink","parameters":[{"name":"surveyId","in":"path","required":true,"schema":{"type":"string"},"description":"Survey identifier"},{"$ref":"#/components/parameters/requestIdHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateLinkRequest"}}}},"responses":{"201":{"description":"Shareable link generated successfully.","headers":{"X-Request-Id":{"$ref":"#/components/headers/requestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateLinkResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```
# Models
## The IsoDateTime object
```json
{"openapi":"3.0.3","info":{"title":"Pristo Public API","version":"1.0.0"},"components":{"schemas":{"IsoDateTime":{"type":"string","format":"date-time"}}}}
```
## The ErrorResponse object
```json
{"openapi":"3.0.3","info":{"title":"Pristo Public API","version":"1.0.0"},"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}
```
## The Contact object
```json
{"openapi":"3.0.3","info":{"title":"Pristo Public API","version":"1.0.0"},"components":{"schemas":{"Contact":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"Client-owned contact identifier"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"language":{"type":"string","description":"ISO 639-1 language code (e.g. en, he)"},"name":{"type":"string"},"lastName":{"type":"string"},"customFields":{"type":"object","description":"Dynamic contact fields (string values). Keys must match fields defined on the population.","additionalProperties":{"type":"string","maxLength":255}}},"additionalProperties":false}}}}
```
## The ContactUpsertRequest object
```json
{"openapi":"3.0.3","info":{"title":"Pristo Public API","version":"1.0.0"},"components":{"schemas":{"ContactUpsertRequest":{"type":"object","required":["contact"],"properties":{"contact":{"$ref":"#/components/schemas/Contact"}}},"Contact":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"Client-owned contact identifier"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"language":{"type":"string","description":"ISO 639-1 language code (e.g. en, he)"},"name":{"type":"string"},"lastName":{"type":"string"},"customFields":{"type":"object","description":"Dynamic contact fields (string values). Keys must match fields defined on the population.","additionalProperties":{"type":"string","maxLength":255}}},"additionalProperties":false}}}}
```
## The ContactResponse object
```json
{"openapi":"3.0.3","info":{"title":"Pristo Public API","version":"1.0.0"},"components":{"schemas":{"ContactResponse":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"}}},"Contact":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"Client-owned contact identifier"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"language":{"type":"string","description":"ISO 639-1 language code (e.g. en, he)"},"name":{"type":"string"},"lastName":{"type":"string"},"customFields":{"type":"object","description":"Dynamic contact fields (string values). Keys must match fields defined on the population.","additionalProperties":{"type":"string","maxLength":255}}},"additionalProperties":false}}}}
```
## The SendEventRequest object
```json
{"openapi":"3.0.3","info":{"title":"Pristo Public API","version":"1.0.0"},"components":{"schemas":{"SendEventRequest":{"type":"object","required":["contact","type"],"properties":{"contact":{"$ref":"#/components/schemas/Contact"},"type":{"type":"string","description":"Event type identifier"},"occurredAt":{"$ref":"#/components/schemas/IsoDateTime"},"customFields":{"type":"object","description":"Dynamic event fields (string values).","additionalProperties":{"type":"string","maxLength":255}}},"additionalProperties":false},"Contact":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"Client-owned contact identifier"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"language":{"type":"string","description":"ISO 639-1 language code (e.g. en, he)"},"name":{"type":"string"},"lastName":{"type":"string"},"customFields":{"type":"object","description":"Dynamic contact fields (string values). Keys must match fields defined on the population.","additionalProperties":{"type":"string","maxLength":255}}},"additionalProperties":false},"IsoDateTime":{"type":"string","format":"date-time"}}}}
```
## The SendEventResponse object
```json
{"openapi":"3.0.3","info":{"title":"Pristo Public API","version":"1.0.0"},"components":{"schemas":{"SendEventResponse":{"type":"object","required":["ok","status","statusText","raw"],"properties":{"ok":{"type":"boolean","description":"Indicates whether the request succeeded."},"status":{"type":"integer","description":"Application-level status code returned by the API."},"statusText":{"type":"string","description":"Application-level status text returned by the API."},"body":{"nullable":true,"description":"Optional response body. Null when no structured body is returned."},"raw":{"type":"string","description":"Raw response value returned by the API."}},"additionalProperties":false}}}}
```
## The GenerateLinkRequest object
```json
{"openapi":"3.0.3","info":{"title":"Pristo Public API","version":"1.0.0"},"components":{"schemas":{"GenerateLinkRequest":{"type":"object","properties":{"expiresInMinutes":{"type":"integer","minimum":1,"description":"How long the link should stay active. If omitted, the link does not expire."},"language":{"type":"string","description":"Language to open the survey in. If omitted, the survey default language is used."},"isReusable":{"type":"boolean","description":"Indicates whether the generated link can be used multiple times. If omitted, the link is single-use."},"title":{"type":"string","description":"User-friendly name for the generated link, used for display in the UI."},"customFields":{"type":"object","description":"Custom fields to attach to the generated link. Values must be strings (max 50 characters).","additionalProperties":{"type":"string","maxLength":50}}},"additionalProperties":false}}}}
```
## The GenerateLinkResponse object
```json
{"openapi":"3.0.3","info":{"title":"Pristo Public API","version":"1.0.0"},"components":{"schemas":{"GenerateLinkResponse":{"type":"object","required":["linkId","url"],"properties":{"linkId":{"type":"string","format":"uuid","description":"Unique identifier of the generated shareable link."},"url":{"type":"string","format":"uri","description":"The generated shareable link URL."}},"additionalProperties":false}}}}
```