> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octavehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk import events

> Imports a batch of events (calls, emails, CRM, social) into the analytics pipeline. Accepts up to 1000 events per request; events are ingested asynchronously.

One import job is created per event type present in the request; each job is tracked independently via GET /event/import/status.

**Deduplication**: supply `eventId` on each event for predictable dedupe, otherwise a deterministic ID is derived from the event's content. Events whose ID matches an existing event in the workspace are skipped (reported as `preSkipped`); duplicate IDs within one request keep the first occurrence (later indices reported in `duplicatesInBatch`).

**Skipped vs failed**: only processable event types produce analytics events (email `sent`/`reply`, call `transcript`, all CRM types, all social types) — other event types are accepted but land in the job's `skipped` count, alongside duplicates and internal-only events. `ingested` is the authoritative success count.

**Callback**: if `callbackUrl` is provided, each job POSTs its final counts to that URL once on completion (one callback per job; delivery is best-effort — poll the status endpoint as the source of truth).



## OpenAPI

````yaml post /api/v2/event/import
openapi: 3.0.0
info:
  version: 1.0.0
  title: Octave API
  description: API for Octave workspace management and AI-powered content generation
servers:
  - url: https://app.octavehq.com
security:
  - ApiKeyAuth: []
paths:
  /api/v2/event/import:
    post:
      tags:
        - Events
      summary: Bulk import events
      description: >-
        Imports a batch of events (calls, emails, CRM, social) into the
        analytics pipeline. Accepts up to 1000 events per request; events are
        ingested asynchronously.


        One import job is created per event type present in the request; each
        job is tracked independently via GET /event/import/status.


        **Deduplication**: supply `eventId` on each event for predictable
        dedupe, otherwise a deterministic ID is derived from the event's
        content. Events whose ID matches an existing event in the workspace are
        skipped (reported as `preSkipped`); duplicate IDs within one request
        keep the first occurrence (later indices reported in
        `duplicatesInBatch`).


        **Skipped vs failed**: only processable event types produce analytics
        events (email `sent`/`reply`, call `transcript`, all CRM types, all
        social types) — other event types are accepted but land in the job's
        `skipped` count, alongside duplicates and internal-only events.
        `ingested` is the authoritative success count.


        **Callback**: if `callbackUrl` is provided, each job POSTs its final
        counts to that URL once on completion (one callback per job; delivery is
        best-effort — poll the status endpoint as the source of truth).
      operationId: importEvents
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                events:
                  type: array
                  items:
                    oneOf:
                      - type: object
                        properties:
                          eventTimestamp:
                            anyOf:
                              - type: string
                              - type: number
                              - type: string
                                format: date-time
                          eventType:
                            type: string
                            enum:
                              - sent
                              - reply
                              - opened
                              - clicked
                              - bounced
                              - unsubscribed
                          subject:
                            type: string
                          body:
                            type: object
                            properties:
                              text:
                                type: string
                              html:
                                type: string
                          from:
                            type: object
                            properties:
                              email:
                                type: string
                                format: email
                              name:
                                type: string
                            required:
                              - email
                          to:
                            type: array
                            items:
                              type: object
                              properties:
                                email:
                                  type: string
                                  format: email
                                name:
                                  type: string
                              required:
                                - email
                            minItems: 1
                          cc:
                            type: array
                            items:
                              type: object
                              properties:
                                email:
                                  type: string
                                  format: email
                                name:
                                  type: string
                              required:
                                - email
                          bcc:
                            type: array
                            items:
                              type: object
                              properties:
                                email:
                                  type: string
                                  format: email
                                name:
                                  type: string
                              required:
                                - email
                          eventId:
                            type: string
                            maxLength: 255
                          conversationId:
                            type: string
                          campaignId:
                            type: string
                          octaveRequestId:
                            type: string
                          sourceProviderName:
                            type: string
                          customMetadata:
                            type: object
                            additionalProperties:
                              nullable: true
                          type:
                            type: string
                            enum:
                              - email
                        required:
                          - eventTimestamp
                          - eventType
                          - subject
                          - body
                          - from
                          - to
                          - type
                      - type: object
                        properties:
                          eventTimestamp:
                            anyOf:
                              - type: string
                              - type: number
                              - type: string
                                format: date-time
                          eventType:
                            type: string
                            enum:
                              - transcript
                              - scheduled
                              - completed
                              - missed
                          title:
                            type: string
                          transcript:
                            anyOf:
                              - type: string
                                minLength: 1
                              - type: array
                                items:
                                  type: object
                                  properties:
                                    speaker:
                                      type: object
                                      properties:
                                        name:
                                          type: string
                                        email:
                                          type: string
                                          format: email
                                        role:
                                          type: string
                                          enum:
                                            - internal
                                            - external
                                      required:
                                        - name
                                    text:
                                      type: string
                                    timestamp:
                                      type: string
                                  required:
                                    - speaker
                                    - text
                                minItems: 1
                          participants:
                            type: array
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                email:
                                  type: string
                                  format: email
                                role:
                                  type: string
                                  enum:
                                    - internal
                                    - external
                              required:
                                - name
                            minItems: 1
                          duration:
                            type: number
                          recordingUrl:
                            type: string
                            format: uri
                          meetingPlatform:
                            type: string
                          eventId:
                            type: string
                            maxLength: 255
                          conversationId:
                            type: string
                          sourceProviderName:
                            type: string
                          customMetadata:
                            type: object
                            additionalProperties:
                              nullable: true
                          type:
                            type: string
                            enum:
                              - call
                        required:
                          - eventTimestamp
                          - eventType
                          - title
                          - transcript
                          - participants
                          - type
                      - type: object
                        properties:
                          eventTimestamp:
                            anyOf:
                              - type: string
                              - type: number
                              - type: string
                                format: date-time
                          eventType:
                            type: string
                            enum:
                              - opportunity_created
                              - deal_won
                              - deal_lost
                              - meeting_booked
                          eventId:
                            type: string
                            maxLength: 255
                          opportunityId:
                            type: string
                            maxLength: 200
                          opportunityName:
                            type: string
                          amount:
                            type: number
                          stage:
                            type: string
                          accountName:
                            type: string
                          contactEmail:
                            type: string
                            format: email
                          contactName:
                            type: string
                          closeDate:
                            anyOf:
                              - type: string
                              - type: number
                              - type: string
                                format: date-time
                          sourceProviderName:
                            type: string
                          customMetadata:
                            type: object
                            additionalProperties:
                              nullable: true
                          type:
                            type: string
                            enum:
                              - crm
                        required:
                          - eventTimestamp
                          - eventType
                          - opportunityId
                          - opportunityName
                          - type
                      - type: object
                        properties:
                          eventTimestamp:
                            anyOf:
                              - type: string
                              - type: number
                              - type: string
                                format: date-time
                          eventType:
                            type: string
                            enum:
                              - connection_sent
                              - connection_accepted
                              - message_sent
                              - message_received
                          body:
                            type: object
                            properties:
                              text:
                                type: string
                              html:
                                type: string
                          from:
                            type: object
                            properties:
                              email:
                                type: string
                                format: email
                              name:
                                type: string
                            required:
                              - email
                          to:
                            type: array
                            items:
                              type: object
                              properties:
                                email:
                                  type: string
                                  format: email
                                name:
                                  type: string
                              required:
                                - email
                            minItems: 1
                          subject:
                            type: string
                          eventId:
                            type: string
                            maxLength: 255
                          conversationId:
                            type: string
                          campaignId:
                            type: string
                          messageType:
                            type: string
                          campaignName:
                            type: string
                          octaveRequestId:
                            type: string
                          sourceProviderName:
                            type: string
                          customMetadata:
                            type: object
                            additionalProperties:
                              nullable: true
                          type:
                            type: string
                            enum:
                              - social
                        required:
                          - eventTimestamp
                          - eventType
                          - body
                          - from
                          - to
                          - type
                  minItems: 1
                  maxItems: 1000
                callbackUrl:
                  type: string
                  format: uri
              required:
                - events
              description: >-
                Up to 1000 events per request. Each event carries a `type`
                discriminator (`email` | `call` | `crm` | `social`) and
                otherwise follows the corresponding generic event structure used
                by the single-event webhook endpoints.
      responses:
        '200':
          description: Import jobs created
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
                  jobs:
                    type: array
                    items:
                      type: object
                      properties:
                        eventType:
                          type: string
                          enum:
                            - email
                            - call
                            - crm
                            - social
                          description: The event type this job covers
                        provider:
                          type: string
                          description: The generic provider the events were imported under
                          example: OCTAVE_GENERIC_CALL
                        jobOId:
                          type: string
                          description: >-
                            The import job OId — poll GET /event/import/status
                            with this value
                          example: pbj_3rgkoHhR00cEdE9DjKeIK
                        accepted:
                          type: integer
                          description: Events queued for ingestion
                        preSkipped:
                          type: integer
                          description: >-
                            Events skipped immediately because the workspace
                            already has an event with the same ID
                        duplicatesInBatch:
                          type: array
                          items:
                            type: integer
                          description: >-
                            Zero-based request indices of events dropped because
                            an earlier event in this request had the same ID
                      required:
                        - eventType
                        - provider
                        - jobOId
                        - accepted
                        - preSkipped
                        - duplicatesInBatch
                    description: One import job per event type present in the request
                  totalAccepted:
                    type: integer
                    description: Sum of accepted events across all jobs
                  totalPreSkipped:
                    type: integer
                    description: Sum of pre-skipped events across all jobs
                required:
                  - _metadata
                  - jobs
                  - totalAccepted
                  - totalPreSkipped
        '400':
          description: >-
            Validation failed — no events were imported. The message lists the
            offending event indices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
                  message:
                    type: string
                required:
                  - _metadata
                  - message
      deprecated: false
components:
  schemas:
    Metadata:
      type: object
      properties:
        usage:
          type: number
          default: 0
          example: 0
          description: API usage
        requestId:
          type: string
          example: requestId
          description: Request ID
        message:
          type: string
          example: message
          description: Message
        timestamp:
          type: string
          example: '2021-01-01T00:00:00.000Z'
          description: Timestamp
      required:
        - requestId
        - timestamp
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key

````