# 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"}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pristo.io/events.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.