REST API Reference

FunnelMob SDK-to-Backend REST API reference.

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

Base URL

All requests go to https://api.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

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