# Send an event

Send an event to the Pristo API with POST /v1/events/send to start an event-based distribution for a contact, with request and response examples.

`POST https://api.pristo.io/v1/events/send` reports an event for a contact, such as a purchase, to Pristo CX. Pristo CX adds or updates the contact in the population of the API key's program, and active event-based distributions that select this event type send their questionnaire by SMS or email.

## Before you start

- API key: a key for the program. See [Authenticate with an API key](https://docs.pristo.io/cx/api/authentication).
- Plan: API access needs Standard or Pro. The app shows **Distributions**, where you set up event-based distributions, on the Pro plan only.
- Population: the program has a population. If **Population** shows **This program has no population yet**, the API returns `404`. See the [populations overview](https://docs.pristo.io/cx/populations/overview).
- Event type: in **Population**, open **Actions** > **Events attributes** > **Event types**. The **Unique Identifier** of the event type is the value you send in `type`.
- Distribution: an active event-based distribution selects that event type. See [Send surveys after events](https://docs.pristo.io/cx/distributions/event-based).

## Steps

1. Build the JSON body with `type` and `contact.id`. Add `contact.email` or `contact.phone` so the contact can receive the survey.

2. Send the body to `https://api.pristo.io/v1/events/send` with the headers `X-API-Key` and `Content-Type: application/json`.

3. Store the `eventId` from the response.

4. Check the event in the app: open the contact in **Population**. The event appears under **Events** with its status.

```bash
curl -X POST "https://api.pristo.io/v1/events/send" \
  -H "X-API-Key: $PRISTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "purchase",
    "contact": {
      "id": "CUST-1042",
      "email": "dana@example.com",
      "phone": "+972501234567",
      "name": "Dana",
      "lastName": "Example",
      "language": "en",
      "customFields": { "tier": "gold" }
    },
    "customFields": { "branch": "example_branch", "amount": "120" }
  }'
```

## Request body

| Field | Type | Required | What it does |
|---|---|---|---|
| `type` | string | Yes | The event type's **Unique Identifier**. 1 to 50 characters |
| `contact` | object | Yes | The contact the event happened to |
| `contact.id` | string | Yes | Your own ID for the contact, 1 to 50 characters. Pristo CX matches an existing contact by this ID, ignoring case, or creates a new one |
| `contact.email` | string | No | The contact's email address. An invalid address is ignored |
| `contact.phone` | string | No | An Israeli mobile number, such as `+972501234567` or `0501234567`. Other numbers are stored but can't receive SMS |
| `contact.name`, `contact.lastName` | string | No | First and last name. Longer values are cut to 50 characters |
| `contact.language` | string | No | A two-letter code such as `he` or `en`. If you leave it out, the contact gets the population's default language |
| `contact.customFields` | object | No | Contact attribute values, keyed by each attribute's **Unique Identifier** in **Contact attributes**. Unknown keys and values that don't fit the attribute are ignored |
| `customFields` | object | No | Event attribute values, keyed by each event attribute's **Unique Identifier** on the **Attributes** tab. Distribution filters read each value as the event attribute's type, and a value that cannot be read that way does not match |

Except for `contact.language`, fields you leave out keep the values already stored on the contact. The API ignores fields it doesn't know, such as `occurredAt`: the event time is the time Pristo CX receives it.

## Result

The API answers `200 OK` with the event's ID:

```json
{
  "eventId": "AbCdEfGhIjKlMnOpQrStUv"
}
```

`200` means Pristo CX stored the event. Pristo CX then updates the contact and schedules the survey, so they appear shortly after the call returns, not while it runs.

The older route `POST /v1/events/send/{popId}` still works and does the same thing. Its `popId` is ignored: the population always comes from the API key's program. Use `/v1/events/send` in new code.

## Limits

- The request body can be at most 10,000 bytes. Only the fields the API knows count toward the limit, and each non-ASCII character, such as a Hebrew letter, counts as 6 bytes.
- `type` and `contact.id`: 1 to 50 characters each.
- The distribution's spacing rules decide how often a contact can get the survey. A spacing of 0 days still keeps at least 10 minutes between two surveys to the same contact, counting surveys that are scheduled but not sent yet.

## Troubleshooting

**The API returned 200, but no survey was sent.** Check that `type` matches an event type that an active event-based distribution selects, and that the contact has an email address for an email distribution or an Israeli mobile number for SMS. A contact who unsubscribed, or who doesn't match the distribution's filters, gets nothing. The distribution's delay and sending windows can also move the send to later.

**The API returned 404 with `no population is associated with this api key`.** The API key's program has no population. Create the population first, or use a key from a program that has one.

**The contact's language changed.** When `contact.language` is missing, Pristo CX sets the contact's language to the population's default. Send `contact.language` with every event.

**The API returned 400 or 401.** Most 400 bodies name the problem in plain text. A 401 means the API key is missing or not active. See [API errors](https://docs.pristo.io/cx/api/errors).

## Related

- [Send surveys after events](https://docs.pristo.io/cx/distributions/event-based)
- [Populations overview](https://docs.pristo.io/cx/populations/overview)
- [Import activities](https://docs.pristo.io/cx/populations/import-activities)
- [Authenticate with an API key](https://docs.pristo.io/cx/api/authentication)
- [API errors](https://docs.pristo.io/cx/api/errors)
- [API reference: Send an event](https://docs.pristo.io/cx/api/reference/operations/sendevent)