#docs #ingest #overview

Ingest API v2

Use the TelemetryDeck Ingest API to send signals to TelemetryDeck

Ingest API v2

Usually you’ll send signals 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 signals directly to our Ingest API.

Ingest Endpoint

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

Here’s an example in cURL:

curl -X "POST" "https://nom.telemetrydeck.com/v2/" \
     -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 signals at once. Each signal object must have these properties:

appIDstringYour app’s ID
clientUserstringA hash of the user’s ID. This should always be the same for the same user.
typestringThe type of signal. While it is not enforced, we recommend structuring your signal names in namespaces separated by dots, with the signal type beginning with a lower case letter and any namespaced beginning with an uppercase letter.

The following properties are optional:

sessionIDstringThe user’s session ID. This should be the same value for the same session/user combination.
isTestModeboolIf true, the signal will be excluded from production queries. Defaults to false.
payloadobjectA JSON object with additional data.


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

  "clientUser": "myClientUserHash",
  "type": "Curl.Development.apiCall",
  "sessionID": "mySessionID",
  "isTestMode": false,
  "payload": {
    "TelemetryDeck.RunContext.locale": "en_US",
    "TelemetryDeck.Device.architecture": "x86_64",
    "floatValue": 3.14159

Payload keys should be in the format Namespace.OptionalSubNamespace.key, with the namespaces 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).

Special Payload Values

The following payload values are not converted to strings, but need to be sent as their respective types:

floatValueFloatA floating point number. Use for any numeric operations, such as building averages or adding up values.

Forbidden Payload Values

You are not allowed to send the following keys in the payload:

  • count
  • type
  • appID
  • clientUser
  • __time
  • payload
  • platform
  • receivedAt

These keys are reserved for internal use. If you use them, we’ll rename them on the server for you by prepending an underscore. For example, if you send count, we’ll store it as _count.