Ingest API v2

Usually you’ll send events to TelemetryDeck using one of our SDKs. However, if you’re working with a language or framework that we don’t have an SDK for, you can send events directly to our Ingest API.

Ingest Endpoint

Please send your events as a POST request to our ingestion server at https://nom.telemetrydeck.com/v2/namespace/{namespace}/, with the headers Content-Type: application/json and charset=utf-8.

Replace {namespace} with your organization’s TelemetryDeck namespace. You can find your namespace in the TelemetryDeck Dashboard. If your organization has no namespace yet, send your events to https://nom.telemetrydeck.com/v2/ instead.

Here’s an example in cURL:

curl -X "POST" "https://nom.telemetrydeck.com/v2/namespace/your-namespace/" \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'[
        {
          "appID": "AAAA-BBBBBBBB-CCCC-DDDD",
          "clientUser": "myClientUserHash",
          "type": "Actions.LoginView.loginButtonSucceeded"
        }
      ]'

Body Structure

The post body should be an array of JSON objects, because you can send multiple events at once. Each event object must have these properties:

The following properties are optional:

Payload

The payload object can contain data you want to send to TelemetryDeck. It must be a JSON object containing primitives. Here’s an example:

{
  "appID": "AAAA-BBBBBBBB-CCCC-DDDD",
  "clientUser": "myClientUserHash",
  "type": "Curl.Development.apiCall",
  "sessionID": "mySessionID",
  "isTestMode": false,
  "floatValue": 3.14159,
  "payload": {
    "TelemetryDeck.RunContext.locale": "en_US",
    "TelemetryDeck.Device.architecture": "x86_64"
  }
}

Payload keys should be in the format Scope.OptionalSubScope.key, with the scopes capitalized and the key starting with a lowercase letter. This is not enforced but helps you organize your payload dimensions and fit in better with TelemetryDeck’s internal payload keys.

The value can be any primitive JSON value, but we’ll convert it to a string before storing it, except for a number of special cases that are stored as their original type.

The payload should not contain nested objects. The behavior of arrays of strings is left undefined and should be avoided (except if you have a deep knowledge of multi-value dimensions in Apache Druid).

Numeric Values

The floatValue field is a top-level property on the event object (see the optional properties table above). It is not part of the payload object. Use it for any numeric operations such as building averages or adding up values.

Responses

Reserved Payload Keys

Some payload keys are reserved for internal use by TelemetryDeck. See the complete list of reserved parameters which you’re not allowed to include in the payload.

In general, avoid using parameter names that begin with the TelemetryDeck. scope, as this is reserved for parameters set by TelemetryDeck SDKs and the ingestion server.

Web Events

Web SDK versions before 3.0 send page views to https://nom.telemetrydeck.com/v2/w/. This endpoint takes one event object per request and derives browser, system, location, and campaign data on the server. It keeps working for sites that still run an older Web SDK.

Web SDK 3.0 and later use the v3 web events endpoint. Use v3 for new website integrations.

Changelog

• September 2026: Events with an empty appID are rejected with HTTP 422 unless they carry a namespace. Before, the server accepted them and then dropped them, because they could not be attributed to an app.