---
title: "Ingest events"
method: POST
path: "/v0/raw_events"
tags: ["Events"]
---

# Ingest events

`POST /v0/raw_events`

## Request

- Base URL: `https://events.formo.so`
- URL: `https://events.formo.so/v0/raw_events`
- Auth: HTTP bearer

Send analytics events to Formo. This endpoint runs on events.formo.so (not api.formo.so). Authenticate with your project's SDK write key.

## Request body

- Event[]
  - `type` 'page' | 'connect' | 'disconnect' | 'chain' | 'signature' | 'transaction' | 'track' | 'decoded_log' | 'detect' | 'identify' | 'web_vitals', required
  - `channel` 'web' | 'mobile' | 'server' | 'api' | 'import', required: Source of the event. The Formo Web SDK uses `web`; mobile SDK uses `mobile`; server SDK uses `server`. Use `api` for direct HTTP submissions and `import` for backfills.
  - `version` string, required: SDK schema version. Web SDK 1.x emits `1`; legacy clients emit `0`.
  - `anonymous_id` string, required: Anonymous visitor identifier
  - `user_id` string, nullable: Identified user ID
  - `address` string, nullable: Wallet address
  - `event` string, nullable: Event name (for track events)
  - `context` EventContext: Contextual information about the event environment
    - `user_agent` string
    - `locale` string: e.g. en-US
    - `timezone` string: e.g. America/New_York
    - `page_url` string
    - `page_path` string
    - `page_title` string
    - `page_query` string
    - `page_hash` string
    - `referrer_url` string
    - `referrer` string
    - `ref` string
    - `utm_source` string
    - `utm_medium` string
    - `utm_campaign` string
    - `utm_term` string
    - `utm_content` string
    - `browser` string
    - `device` 'desktop' | 'mobile' | 'tablet'
    - `os` string
    - `screen_width` integer
    - `screen_height` integer
    - `screen_density` number: Pixel density of the device screen (devicePixelRatio)
    - `viewport_width` integer: Width of the browser viewport in pixels
    - `viewport_height` integer: Height of the browser viewport in pixels
    - `location` string: Geographic location country code (e.g., US, NG)
    - `library_name` string
    - `library_version` string
  - `properties` EventProperties: Event-specific properties. Can contain any key-value pairs relevant to the event.
  - `original_timestamp` string, date-time
  - `sent_at` string, date-time
  - `message_id` string: Unique ID for deduplication. Optional; a UUID is generated server-side when omitted.

## Response `200`

Batch accepted. The body carries an ingestion summary when one is available, otherwise `{}`.

- object

## Other responses

- `202`: Batch accepted for asynchronous processing. Returns `{ "queued": true }` when the batch was buffered for retry, an ingestion summary when one is available, otherwise `{}`.
- `400`: The request body is missing. A body that is present but not valid JSON returns 500 instead.
- `401`: The request could not be authenticated.
- `403`: Missing or invalid SDK write key. The body for this status is not the shape shown here.
- `500`: The batch could not be ingested, or the request body was not valid JSON.

---

[API](https://skmtc.dev/formo/apis/formo-public-api.md) · [All operations](https://skmtc.dev/formo/apis/formo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/formo/apis/formo-public-api/revisions/67ada57df63c?raw)