> ## Documentation Index > Fetch the complete documentation index at: https://docs.unitedpetroleum.app/llms.txt > Use this file to discover all available pages before exploring further. # Create telemetry events > Inserts one event object or an array of up to 1000 events. Idempotent on `(external_message_id, fleet_id)` — duplicate rows are skipped. `fleet_id` and `external_message_id` are required on each event. ## OpenAPI ````yaml /openapi.json post /events openapi: 3.1.0 info: title: United Logistics API version: 0.1.0 description: >- Industry-grade public API for fleet, fuel, and toll operations. Every endpoint is scoped to the organization owning the API key. Authentication: bearer API key (`ulk__`). Rate limit: 60 requests/minute/key by default (override per key via the dashboard). contact: name: United Logistics Engineering email: sfuentes@assetmg.tech servers: - url: https://app.unitedlogistics.com.do/api/v1 description: Production - url: http://localhost:3000/api/v1 description: Local development security: - ApiKeyAuth: [] paths: /events: post: tags: - Events summary: Create telemetry events description: >- Inserts one event object or an array of up to 1000 events. Idempotent on `(external_message_id, fleet_id)` — duplicate rows are skipped. `fleet_id` and `external_message_id` are required on each event. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/EventBulkCreateRequest' examples: single: summary: Single event value: vehicle_external_id: 11964 fleet_id: 42 provider: karma external_message_id: 55001234 event_date: '2026-05-15T14:32:10.000Z' latitude: 18.4861 longitude: -69.9312 speed_kph: 62.5 heading_deg: 180 eid: 1 bulk: summary: Bulk array value: - vehicle_external_id: 11964 fleet_id: 42 provider: karma external_message_id: 55001234 event_date: '2026-05-15T14:32:10.000Z' latitude: 18.4861 longitude: -69.9312 speed_kph: 62.5 - vehicle_external_id: 11964 fleet_id: 42 provider: karma external_message_id: 55001235 event_date: '2026-05-15T14:33:10.000Z' latitude: 18.487 longitude: -69.93 speed_kph: 65 responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/EventBulkCreateResponse' example: inserted: 2 skipped: 0 ids: - 987654321 - 987654322 '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorObject' example: error: code: bad_request message: limit must be an integer between 1 and 500. '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorObject' example: error: code: unauthorized message: API key missing or invalid. '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorObject' example: error: code: forbidden message: API key lacks the required scope. '404': description: Vehicle or fleet not found content: application/json: schema: $ref: '#/components/schemas/ErrorObject' example: error: code: not_found message: Evento no encontrado. '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorObject' example: error: code: too_many_requests message: Rate limit exceeded. security: - ApiKeyAuth: [] components: schemas: EventBulkCreateRequest: anyOf: - type: object properties: vehicle_external_id: type: integer exclusiveMinimum: 0 description: Provider vehicle id (= `vehicles.external_id`). example: 12345 fleet_id: type: integer exclusiveMinimum: 0 description: >- Fleet (provider account) scope. Required on each event; used for access validation. example: 1029 provider: anyOf: - type: string enum: - karma - internal - type: string pattern: ^[a-z][a-z0-9][a-z0-9_-]{0,62}$ description: >- Telematics provider slug (e.g. `karma`, `queclink`, custom integrator slug). example: karma external_message_id: type: integer exclusiveMinimum: 0 description: >- Provider message id. Required for idempotent bulk inserts; unique per `fleet_id`. example: 55001234 event_date: type: string format: date-time description: ISO 8601 timestamp when the event occurred. example: '2026-05-15T14:32:10.000Z' device_id: type: - string - 'null' maxLength: 255 example: GPS-DEV-001 latitude: type: - number - 'null' minimum: -90 maximum: 90 longitude: type: - number - 'null' minimum: -180 maximum: 180 eid: type: - integer - 'null' description: Provider event-type code. example: 1 speed_kph: type: - number - 'null' minimum: 0 heading_deg: type: - number - 'null' minimum: 0 maximum: 360 odometer_km: type: - number - 'null' minimum: 0 altitude_m: type: - number - 'null' engine_status: type: - integer - 'null' ignition_status: type: - integer - 'null' extra: type: - string - 'null' maxLength: 4096 description: Opaque provider payload (driver key, raw extras, etc.). required: - vehicle_external_id - fleet_id - provider - external_message_id - event_date - type: array items: type: object properties: vehicle_external_id: type: integer exclusiveMinimum: 0 description: Provider vehicle id (= `vehicles.external_id`). example: 12345 fleet_id: type: integer exclusiveMinimum: 0 description: >- Fleet (provider account) scope. Required on each event; used for access validation. example: 1029 provider: anyOf: - type: string enum: - karma - internal - type: string pattern: ^[a-z][a-z0-9][a-z0-9_-]{0,62}$ description: >- Telematics provider slug (e.g. `karma`, `queclink`, custom integrator slug). example: karma external_message_id: type: integer exclusiveMinimum: 0 description: >- Provider message id. Required for idempotent bulk inserts; unique per `fleet_id`. example: 55001234 event_date: type: string format: date-time description: ISO 8601 timestamp when the event occurred. example: '2026-05-15T14:32:10.000Z' device_id: type: - string - 'null' maxLength: 255 example: GPS-DEV-001 latitude: type: - number - 'null' minimum: -90 maximum: 90 longitude: type: - number - 'null' minimum: -180 maximum: 180 eid: type: - integer - 'null' description: Provider event-type code. example: 1 speed_kph: type: - number - 'null' minimum: 0 heading_deg: type: - number - 'null' minimum: 0 maximum: 360 odometer_km: type: - number - 'null' minimum: 0 altitude_m: type: - number - 'null' engine_status: type: - integer - 'null' ignition_status: type: - integer - 'null' extra: type: - string - 'null' maxLength: 4096 description: Opaque provider payload (driver key, raw extras, etc.). required: - vehicle_external_id - fleet_id - provider - external_message_id - event_date minItems: 1 maxItems: 1000 EventBulkCreateResponse: type: object properties: inserted: type: integer skipped: type: integer ids: type: array items: type: integer required: - inserted - skipped - ids ErrorObject: type: object properties: error: type: object properties: code: type: string example: unauthorized message: type: string example: Missing Authorization header. details: {} required: - code - message required: - error securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: ulk__ description: >- Authorization: Bearer ulk__. Cree la clave en Configuración → API. ````