Send an event

View as Markdown Open in ChatGPT Open in Claude

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.
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.
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.

Steps

Build the JSON body with type and contact.id. Add contact.email or contact.phone so the contact can receive the survey.
Send the body to https://api.pristo.io/v1/events/send with the headers X-API-Key and Content-Type: application/json.
Store the eventId from the response.
Check the event in the app: open the contact in Population. The event appears under Events with its status.

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:

{
  "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.