# Events

Events are the core signal system in Bento. They capture meaningful user actions with detailed context so you can understand behavior, build better segments, and trigger automations. Use events to power workflows and reporting with accurate, real-time data.


> **Recommended**
> Before you start sending events, map names and follow-ups in the free [Event Tracking Plan](/docs/tools/event-tracking-plan) spreadsheet.


## Available Endpoints


---

## The Events Model

  
    The events model requires you to pass an event type and email. User fields, details, and the date are optional fields for recording metadata about the event or the visitor.
  
  
    ### Properties

    
      - **type** (`string`): 
        The name of the event
      
      - **email** (`string`): 
        Email of the event user
      
      - **fields** (`object`): 
        An object of key/value pairs written to the subscriber's profile fields. Must not be nested.
      
      - **details** (`object`): 
        An object of key/value pairs stored as event metadata. Can be nested.
      
      - **date** (`datetime`): 
        Optional timestamp for when the event happened. Omit it to use the time Bento receives the request.
      
    
  


---

## Create Events {{ tag: 'POST', label: '/v1/batch/events' }}


  
    Sends events to your site. Events create new users if they do not already exist in your account.

    
> This endpoint takes an array `events` that can contain 1 to 1000 events made up of the following keys.


    ### Required Attributes
    
      - **type** (`string`): 
        The name of the event
      
      - **email** (`string`): 
        Email of the event user
      
    

    ### Optional Attributes
    
      - **fields** (`object`): 
        An object of key/value pairs written to the subscriber's profile fields. Must not be nested.
      
      - **details** (`object`): 
        An object of key/value pairs stored as event metadata. Can be nested.
      
      - **date** (`datetime`): 
        Optional timestamp for when the event happened. Use an ISO 8601 value.
      
    

  
  
    
  


  
    ### Response
    Returns the count of events recorded.

    
      - **results** (`integer`): 
        Number of events accepted and queued for processing.
      
      - **failed** (`integer`): 
        Number of events Bento rejected from the request.