# Pristo API overview

Use the Pristo API to trigger event-based survey distributions and generate survey links from your own systems. Requires a Standard or Pro plan.

The Pristo API lets your own systems work with Pristo CX in two ways: send an event that starts an event-based distribution for a contact, and generate a survey link for a questionnaire. Both are `POST` requests with a JSON body to the base URL `https://api.pristo.io`.

Every Pristo API request carries an API key in the `X-API-Key` header. You create keys in the Pristo CX app under **Management** > **API keys**, and each key belongs to one program.

API access is part of the Standard and Pro plans. On the Free plan, the app doesn't show **API keys** and doesn't create keys. Events start surveys only through event-based distributions, and the app shows **Distributions** on the Pro plan only. See [Plans and limits](https://docs.pristo.io/cx/get-started/plans-and-limits).

## Endpoints

| Method and path | What it does | Guide |
|---|---|---|
| `POST /v1/events/send` | Records an event for a contact in the population of the API key's program. Active event-based distributions that select the event type then send their questionnaire. | [Send an event](https://docs.pristo.io/cx/api/send-an-event) |
| `POST /v1/links/generate/{prjId}` | Creates a single-use or reusable link to a questionnaire and returns its URL on `https://go.pristo.io`. | [Generate a survey link](https://docs.pristo.io/cx/api/generate-a-survey-link) |

The full request and response schemas are in the [API reference](https://docs.pristo.io/cx/api/reference). The reference is in English only.

## How it works

**Events.** Your system reports what happened to a customer, for example a purchase. Pristo CX stores the event right away and returns its `eventId`. Shortly afterwards, Pristo CX adds or updates the contact in the program's population and checks the active event-based distributions. Each distribution that selects this event type, and whose filters the event and the contact match, schedules the questionnaire by SMS or email.

**Contacts.** The API has no separate contacts endpoint. Contacts are created and updated from the `contact` object you send with each event.

**Survey links.** You ask for a link to one questionnaire and send the returned `url` to a respondent in your own channel, such as a chat, a receipt or an app. A single-use link collects one response. A reusable link collects a new response each time someone opens it.

## Conventions

| Topic | Rule |
|---|---|
| Base URL | `https://api.pristo.io` |
| Authentication | `X-API-Key: <your key>` on every request. See [Authenticate with an API key](https://docs.pristo.io/cx/api/authentication) |
| Request body | JSON, with the header `Content-Type: application/json`. At most 10,000 bytes |
| Success | `200 OK` with a small JSON object |
| Errors | Most `400` and `404` responses have a plain-text body, not JSON. See [API errors](https://docs.pristo.io/cx/api/errors) |
| IDs | Questionnaire IDs and event IDs are 22-character short IDs. Link IDs are standard UUIDs |

## Related

- [Authenticate with an API key](https://docs.pristo.io/cx/api/authentication)
- [Send an event](https://docs.pristo.io/cx/api/send-an-event)
- [Generate a survey link](https://docs.pristo.io/cx/api/generate-a-survey-link)
- [API errors](https://docs.pristo.io/cx/api/errors)

- [Send surveys after events](https://docs.pristo.io/cx/distributions/event-based)
- [Populations overview](https://docs.pristo.io/cx/populations/overview)
- [API reference](https://docs.pristo.io/cx/api/reference)