# 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"}}}}}}
```