> ## Documentation Index > Fetch the complete documentation index at: https://docs.justpaid.io/llms.txt > Use this file to discover all available pages before exploring further. # Ingest Event > Ingests a list of customer events, creating new events and identifying duplicates. This endpoint processes a batch of customer events, checks for idempotency to prevent duplicates, and attempts to create new events in the system. It returns detailed information about the process, including the number of successfully created events, any duplicates identified, and errors encountered. Parameters: request: The request object, which includes details about the HTTP request. This is typically provided by the FastAPI framework. customer_event_list (CustomerEventList): An object containing a list of customer events to be ingested. Each event must include an idempotency key to prevent duplicate processing. Returns: A dictionary with two keys: - 'info': A dictionary containing details about the ingestion process, including the number of events successfully created ('created_events') and a list of idempotency keys for events identified as duplicates ('duplicates'). - 'errors': A list of dictionaries, each representing an error encountered during the ingestion process. Each dictionary includes the 'idempotency_key' of the event that caused the error and a description of the error ('error'). ## OpenAPI ````yaml post /api/v1/usage/ingest openapi: 3.1.0 info: title: NinjaAPI version: 1.0.0 description: '' servers: - url: https://api.justpaid.io security: [] paths: /api/v1/usage/ingest: post: summary: Ingest Event description: >- Ingests a list of customer events, creating new events and identifying duplicates. This endpoint processes a batch of customer events, checks for idempotency to prevent duplicates, and attempts to create new events in the system. It returns detailed information about the process, including the number of successfully created events, any duplicates identified, and errors encountered. Parameters: request: The request object, which includes details about the HTTP request. This is typically provided by the FastAPI framework. customer_event_list (CustomerEventList): An object containing a list of customer events to be ingested. Each event must include an idempotency key to prevent duplicate processing. Returns: A dictionary with two keys: - 'info': A dictionary containing details about the ingestion process, including the number of events successfully created ('created_events') and a list of idempotency keys for events identified as duplicates ('duplicates'). - 'errors': A list of dictionaries, each representing an error encountered during the ingestion process. Each dictionary includes the 'idempotency_key' of the event that caused the error and a description of the error ('error'). operationId: loopfour_backend_external_api_usage_ingest_event parameters: [] requestBody: content: application/json: schema: $ref: '#/components/schemas/CustomerEventList' required: true responses: '200': description: Detailed information about the customer event ingestion process. content: application/json: schema: $ref: '#/components/schemas/CustomerEventIngestResponseSchema' examples: example1: summary: Successful ingestion with no errors value: info: created_events: 5 duplicates: [] errors: [] example2: summary: Ingestion with errors value: info: created_events: 2 duplicates: - f47ac10b-58cc-4372-a567-0e02b2c3d479 errors: - idempotency_key: f47ac10b-58cc-4372-a567-0e02b2c3d479 error: Invalid event_name security: - HttpBearerAuth: [] components: schemas: CustomerEventList: description: |- Represents a list of customer events. Attributes: events (list[CustomerEvent]): A list of customer events. Each event should be a dictionary with at-least the following keys: event_name, timestamp, idempotency_key. properties: events: default: [] items: $ref: '#/components/schemas/CustomerEvent' title: Events type: array title: CustomerEventList type: object CustomerEventIngestResponseSchema: description: |- Schema for the response of the customer event ingestion process. Attributes: info (InfoSchema): Detailed information about the ingestion process, including the number of created events and duplicates. errors (list[ErrorSchema]): A list of errors that occurred during the ingestion process. properties: info: $ref: '#/components/schemas/InfoSchema' description: Detailed information about the customer event ingestion process. errors: default: [] description: A list of errors that occurred during the ingestion process. items: $ref: '#/components/schemas/ErrorSchema' title: Errors type: array required: - info title: CustomerEventIngestResponseSchema type: object CustomerEvent: description: |- Represents an event associated with a customer in the system. Attributes: customer_id (Optional[Union[str, uuid.UUID]]): The unique identifier for the customer. This can be either a email or a UUID. event_name (str): The name of the event being recorded, it should be in snake_case format without spaces. for example: 'customer_created'. timestamp (str): The timestamp when the event occurred, in ISO 8601 format (e.g. 2024-08-09T00:00:00Z). idempotency_key (str): A unique string key to ensure idempotency of event processing. This key is used to identify duplicate events. item (Optional[uuid.UUID]): An optional billable item UUID that the event can be associated with. event_value (Union[float, int]): The value associated with the event. This can be either an integer or a float. external_customer_id (Optional[str]): An optional external identifier for the customer, provided as a string. properties (Optional[dict]): An optional dictionary containing additional properties or metadata associated with the event. properties: customer_id: anyOf: - type: string - format: uuid type: string - type: 'null' description: >- The unique identifier for the customer. This can be either an email or a UUID obtained from JustPaid Platform. example: 123e4567-e89b-12d3-a456-426614174000 title: Customer Id event_name: anyOf: - type: string - type: 'null' description: >- The name of the event being recorded, this is used to map the event in the JustPaid. For example: 'customer_created' or 'invoice_parsed'. example: customer_created title: Event Name timestamp: description: >- The timestamp when the event occurred, in ISO 8601 format. the tiemstamp should be in UTC timezone. example: '2024-08-09T00:00:00Z' title: Timestamp type: string idempotency_key: description: >- A unique string key to ensure idempotency of event processing. This key is used to identify duplicate events. It's recommended to generate a new UUID for each event to prevent duplicates. example: f47ac10b-58cc-4372-a567-0e02b2c3d479 title: Idempotency Key type: string item_id: anyOf: - format: uuid type: string - type: 'null' description: >- An optional UUID that the event can be associated with. If provided, this should be a UUID obtained from JustPaid Platform using `api/v1/usage/events` endpoint. and each item_id is associated with a plan_item in the system while creating the customer contract example: d3dc2e8f-2c78-4e3c-8b2c-649efdf5dd21 title: Item Id event_value: anyOf: - type: number - type: integer description: >- The value associated with the event. This can be either an integer or a float, this value is used to calculate the billing amount for the customer provided that a billing metic is associated with the event. example: 100 title: Event Value external_customer_id: anyOf: - type: string - type: 'null' description: >- An optional external identifier for the customer, provided as a string. this used as an alias to JustPaid customer. example: external_12345 title: External Customer Id properties: anyOf: - additionalProperties: true type: object - type: 'null' description: >- An optional dictionary containing additional properties or metadata associated with the event. example: property1: value1 property2: 5 title: Properties required: - event_name - timestamp - idempotency_key title: CustomerEvent type: object InfoSchema: description: |- Detailed information about the customer event ingestion process. Attributes: created_events (int): The number of events successfully created. duplicates (list[str]): A list of idempotency keys for events identified as duplicates. properties: created_events: description: >- The number of events successfully created in the system from the input list of events provided to the endpoint. example: 5 title: Created Events type: integer duplicates: default: [] description: >- A list of idempotency keys for events identified as duplicates during the ingestion process. example: - f47ac10b-58cc-4372-a567-0e02b2c3d479 items: type: string title: Duplicates type: array required: - created_events title: InfoSchema type: object ErrorSchema: description: |- Represents an error that occurred during the ingestion process. Attributes: idempotency_key (str): The idempotency key of the event that caused the error. error (str): A description of the error that occurred. properties: idempotency_key: description: The idempotency key of the event that caused the error. example: f47ac10b-58cc-4372-a567-0e02b2c3d479 title: Idempotency Key type: string error: description: A description of the error that occurred. example: Invalid event_name title: Error type: string required: - idempotency_key - error title: ErrorSchema type: object securitySchemes: HttpBearerAuth: type: http scheme: bearer ````