> ## Documentation Index > Fetch the complete documentation index at: https://docs.migma.ai/llms.txt > Use this file to discover all available pages before exploring further. # Track Event > Record a customer event for a project. Requires the audience:write permission. Contact resolution is consent safe: profile fields may update, subscription status never changes. Send an Idempotency-Key header (or a body dedupeKey) for replay safety; without either, every call stores a distinct event. Events carrying identifiers.externalOrderId and a numeric properties.value are recorded as conversions attributed to the last email the contact clicked within five days. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/events openapi: 3.1.0 info: title: Migma.ai API (v1) description: >- API for managing brands, contacts, email generation, sending, and integrations. license: name: MIT version: 1.0.0 servers: - url: https://api.migma.ai description: Production security: - apiKeyAuth: [] tags: - name: Projects/Brands description: Manage projects (brands) and import from websites - name: Contacts description: Manage your contacts, segments, tags, and topics - name: Segments description: Create and manage dynamic contact segments - name: Tags description: Organize contacts with tags - name: Topics description: Manage subscription topics and preferences - name: Emails description: Generate, send, and export emails - name: Email Validation description: Validate email content for compatibility and deliverability - name: Email Previews description: Preview emails across devices and email clients - name: Domains description: Manage sending domains and verification - name: Webhooks description: Manage webhook endpoints for real-time event notifications - name: Events description: Record customer events and conversions - name: Integrations description: Third-party platform integrations - name: Campaigns description: Create, schedule, send, and manage email campaigns - name: Project Editing description: Edit project assets, logos, images, and knowledge base entries paths: /v1/events: post: tags: - Events summary: Track Event description: >- Record a customer event for a project. Requires the audience:write permission. Contact resolution is consent safe: profile fields may update, subscription status never changes. Send an Idempotency-Key header (or a body dedupeKey) for replay safety; without either, every call stores a distinct event. Events carrying identifiers.externalOrderId and a numeric properties.value are recorded as conversions attributed to the last email the contact clicked within five days. parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 200 description: Replay-safe key. Takes precedence over the body dedupeKey. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IngestEventRequest' example: projectId: PROJECT_ID name: purchase.completed identifiers: email: ada@example.com externalOrderId: order_8891 properties: value: 49.99 currency: USD responses: '201': description: Event stored (or replayed) content: application/json: schema: $ref: '#/components/schemas/ApiResponseTrackEventResult' '400': description: Validation failed or no contact identifier content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '403': description: Missing audience:write permission or no access to the project content: application/json: schema: $ref: '#/components/schemas/ApiResponse' '404': description: Subscriber not found in this project content: application/json: schema: $ref: '#/components/schemas/ApiResponse' components: schemas: IngestEventRequest: type: object required: - projectId - name - identifiers properties: projectId: type: string name: type: string maxLength: 120 description: >- Event name, e.g. purchase.completed. Names containing refund or cancelled record negative conversion amounts. origin: type: string maxLength: 80 default: api eventVersion: type: string maxLength: 40 identifiers: $ref: '#/components/schemas/EventIdentifiers' profile: $ref: '#/components/schemas/EventProfile' properties: type: object additionalProperties: true description: >- Event facts. Up to 16KB, 50 top-level keys, 4 levels deep. A numeric value (major units, e.g. 49.99) together with identifiers.externalOrderId records a conversion; currency is an ISO code, default USD. occurredAt: type: string format: date-time description: When the event happened. Defaults to receipt time. dedupeKey: type: string maxLength: 200 description: >- Event-identity dedupe key. Replaying the same key stores nothing and returns the original eventId. ApiResponseTrackEventResult: allOf: - $ref: '#/components/schemas/ApiResponse' - type: object properties: data: $ref: '#/components/schemas/TrackEventResult' ApiResponse: type: object properties: success: type: boolean data: nullable: true error: type: string nullable: true required: - success EventIdentifiers: type: object description: >- Contact identity for the event. At least one of email or subscriberId is required. Provider ids (externalCustomerId, externalCheckoutId, externalOrderId) support integrations and conversion attribution. properties: email: type: string format: email subscriberId: type: string externalCustomerId: type: string maxLength: 200 externalCheckoutId: type: string maxLength: 200 externalOrderId: type: string maxLength: 200 description: >- The provider's order or charge id. Required for the event to record a conversion. EventProfile: type: object description: >- Contact metadata to update. Profile updates never change subscription status, tags, or consent. Events never opt a contact in. properties: firstName: type: string maxLength: 120 lastName: type: string maxLength: 120 phone: type: string maxLength: 80 country: type: string maxLength: 80 language: type: string maxLength: 40 customFields: type: object additionalProperties: true TrackEventResult: type: object properties: stored: type: boolean description: >- false when the dedupeKey was seen before; eventId then refers to the original event. eventId: type: string dedupeKey: type: string securitySchemes: apiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Use 'Authorization: Bearer YOUR_API_KEY' where YOUR_API_KEY is obtained from the Migma dashboard under Settings → Developers → API Keys. ````