REST API Reference

The FunnelMob REST API is used by SDKs to submit events and register sessions. All endpoints require API key authentication.

Base URLs

Environment	URL
Production	https://api.funnelmob.com/v1
Sandbox	https://sandbox.funnelmob.com/v1

Authentication

All requests must include the X-FM-API-Key header:

X-FM-API-Key: fm_live_abc123

Endpoints

POST /events

Submit a batch of events for processing.

Request Body

{
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "platform": "ios",
  "events": [
    {
      "event_id": "unique-event-uuid",
      "event_name": "purchase_complete",
      "timestamp": "2025-12-21T10:30:00.000Z",
      "revenue": {
        "amount": "29.99",
        "currency": "USD"
      },
      "parameters": {
        "item_id": "sku_123",
        "quantity": 2
      }
    }
  ]
}

Field	Type	Required	Description
device_id	string	No	Device identifier (IDFV, GAID, or generated UUID)
session_id	string (uuid)	No	Current session identifier
platform	string	No	ios, android, or web
events	array	Yes	Array of events (1-100 items)

Event Object

Field	Type	Required	Description
event_id	string (uuid)	Yes	Unique identifier for this event
event_name	string	Yes	Event name (1-100 chars, pattern: ^[a-zA-Z][a-zA-Z0-9_]*$)
timestamp	string (date-time)	Yes	ISO 8601 timestamp with milliseconds
revenue	object	No	Revenue information
parameters	object	No	Custom key-value parameters

Revenue Object

Field	Type	Required	Description
amount	string	Yes	Decimal string (e.g., "29.99")
currency	string	Yes	ISO 4217 currency code, uppercase (e.g., "USD")

Responses

• 202 Accepted — Events accepted for processing

{
  "accepted": 5,
  "rejected": 0,
  "errors": []
}

• 400 Bad Request — Validation error
• 401 Unauthorized — Invalid API key
• 429 Too Many Requests — Rate limit exceeded

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "events[0].event_name",
        "message": "Must start with a letter"
      }
    ]
  }
}

---

POST /session

Register a new session when the app opens or comes to foreground.

Request Body

{
  "device_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "platform": "ios",
  "timestamp": "2025-12-21T10:30:00.000Z",
  "is_first_session": false,
  "context": {
    "app_version": "1.2.3",
    "os_name": "iOS",
    "os_version": "17.2",
    "device_model": "iPhone 15 Pro",
    "locale": "en_US",
    "timezone": "America/New_York",
    "screen_width": 1179,
    "screen_height": 2556
  }
}

Field	Type	Required	Description
device_id	string	Yes	Device identifier
session_id	string (uuid)	Yes	New session identifier
platform	string	No	ios, android, or web
timestamp	string (date-time)	Yes	ISO 8601 timestamp
is_first_session	boolean	No	Whether this is the first session (default: false)
context	object	No	Device context information

Device Context

Field	Type	Description
app_version	string	App version string
os_name	string	iOS, Android, or Web
os_version	string	OS version
device_model	string	Device model name
locale	string	Device locale
timezone	string	IANA timezone
screen_width	integer	Screen width in pixels
screen_height	integer	Screen height in pixels

Responses

• 200 OK — Session registered

{
  "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "server_timestamp": "2025-12-21T10:30:00.123Z"
}

• 400 Bad Request — Validation error

---

GET /health

Health check endpoint (no authentication required).

Response: 200 OK