API Reference

The Measura API is a small set of HTTPS endpoints. Most integrations never call it directly, since the SDKs handle ingestion, signing and retries for you. Call it directly for server to server tracking, or to build against the analytics data yourself.

Base URL

All endpoints are served from your Measura functions host. The SDKs default to the ingestion path below and derive the other paths from it.

https://api.measura.dev/v1/ingest        # SDK default ingestion endpoint
{functions-host}/functions/v1/{function}  # direct function invocation

If you are self hosting or pointing at a staging project, override the endpoint through SDK configuration rather than patching the SDK.

Conventions

• All request and response bodies are JSON, encoded as UTF-8.
• Timestamps are Unix milliseconds unless a field is documented as an ISO date.
• Identifiers described as UUIDs are validated as version 4.
• Ingestion accepts gzipped request bodies, which the SDKs use by default.

There are three separate mechanisms, used at different points. Do not mix them up: the API key never authenticates an event, and the signing secret never appears in a header.

1. API key

Issued per application. The format is the prefix msr_ followed by 64 hexadecimal characters.

GET /functions/v1/resolve-key
X-Measura-Api-Key: msr_4f3c...e91a

We store only a SHA-256 hash of the key. The plaintext is displayed once when it is created and cannot be recovered afterwards, so a lost key must be revoked and reissued.

The API key is used exactly once per SDK session, to exchange it for the identifiers and the signing secret. It does not authenticate event submission.

2. Event signature

Every event carries an HMAC-SHA256 signature computed with the signing secret returned by key resolution. This is what actually authenticates ingestion.

The canonical payload rules are strict and easy to get wrong:

• Serialise the event object as JSON with no whitespace.
• Sort top level keys alphabetically.
• Exclude the signature field itself.
• Compute HMAC-SHA256 over that string with the signing secret, and hex encode the result. It must be exactly 64 characters.

import { createHmac } from 'node:crypto'

function sign(event, sdkSecret) {
  const { signature: _omit, ...rest } = event

  // Top level keys sorted, no whitespace.
  const canonical = JSON.stringify(
    Object.keys(rest).sort().reduce((acc, k) => {
      acc[k] = rest[k]
      return acc
    }, {})
  )

  return createHmac('sha256', sdkSecret).update(canonical).digest('hex')
}

3. Dashboard session token

The analytics and migration endpoints authenticate with a session token issued at sign-in, sent as a bearer token. The account identity is read from server controlled token claims, so a client cannot request another tenant’s data by changing a parameter.

GET /functions/v1/analytics?resource=summary
Authorization: Bearer <session token>

Request

Send either a single event object, or an object with an events array. Cross origin requests are permitted from any origin.

{
  "events": [
    {
      "event_type": "install",
      "timestamp": 1754899200000,
      "sent_at": 1754899201500,
      "customer_id": "3f1c8a2e-9b47-4d1e-8a6f-2c5b9e7d1a03",
      "app_id": "7d2e5b1a-4c93-4f8e-b6a1-9e3c7f2d5b84",
      "event_id": "install_1754899200000_a3f9c1e7",
      "sdk_version": "1.0.0",
      "device_model": "Samsung SM-A245F",
      "os_name": "android",
      "os_version": "14",
      "app_version": "2.3.1",
      "device_fingerprint_components": {
        "user_agent": "MeasuraSDK/1.0.0 (Android 14; SM-A245F) App/2.3.1",
        "device_model": "Samsung SM-A245F",
        "os_version": "14",
        "screen_resolution": "1080x2340"
      },
      "referrer": "measura_click_id=8c1f...",
      "signature": "9f2a...c74e"
    }
  ]
}

Limits

Event fields

Required

Optional

Response

{
  "results": [
    {
      "status": "accepted",
      "event_id": "install_1754899200000_a3f9c1e7",
      "server_timestamp": "2026-08-11T09:20:01.732Z"
    },
    {
      "status": "deduplicated",
      "event_id": "open_1754899210000_b7d2f4a1",
      "server_timestamp": "2026-08-11T09:20:01.733Z"
    },
    {
      "error": "Invalid signature",
      "code": "AUTH_ERROR"
    }
  ],
  "batch_size": 3
}

Per event status is accepted, deduplicated or rejected.

Top level errors

{ "status": "ok", "service": "ingest" }

This endpoint backs our public status page. It is safe to poll, but please keep the interval reasonable.

The SDKs call this once at initialisation and cache the result for the session.

{
  "customer_id": "3f1c8a2e-9b47-4d1e-8a6f-2c5b9e7d1a03",
  "app_id": "7d2e5b1a-4c93-4f8e-b6a1-9e3c7f2d5b84",
  "sdk_secret": "b91f7c...4e2a"
}

Short links are normally served from a branded domain, so the URL your users see is link.measura.dev/{slug} rather than the function path.

Behaviour

• Android devices are redirected to the configured app destination. Everything else goes to your fallback URL, since there is no app for them to install.
• Appends measura_click_id and measura_deferred to the destination so the SDK can attribute the resulting install.
• For Google Play destinations, the identifier travels in the referrer parameter, which survives the install and gives deterministic attribution.
• An unknown or inactive slug redirects to the configured default rather than showing an error.

Parameters

Resources

Revenue is reported per currency, never summed

revenue returns a total for each currency separately rather than one figure. This is deliberate: adding NGN to USD produces a number that looks like revenue and means nothing. If you need a single figure, convert at a rate you control, at the moment you report, rather than relying on one baked in here.

{
  "period": { "from": "2026-07-01", "to": "2026-07-31" },
  "payment_count": 412,
  "by_currency": {
    "NGN": { "gross": 6120000.00, "count": 388, "attributed": 331 },
    "USD": { "gross": 2140.00, "count": 24, "attributed": 19 }
  },
  "by_provider": { "paystack": 388, "flutterwave": 24 },
  "attribution_rate_pct": 85.0
}

attributed counts payments tied to a known device, and attribution_rate_pct is that share across the period. A rate well below your install match rate usually means payments are arriving with an identifier the SDK never saw, rather than a fault in attribution.

{
  "period": { "from": "2026-07-12", "to": "2026-08-11" },
  "total_installs": 18432,
  "avg_confidence_score": 81.4,
  "high_confidence_rate_pct": 72.6,
  "installs_by_model": {
    "install_referrer": 8120,
    "click_id": 4306,
    "deterministic": 2988,
    "probabilistic": 1442,
    "organic": 1576
  },
  "installs_by_channel": {
    "whatsapp": 6210,
    "meta": 4980,
    "qr_code": 2110,
    "organic": 1576
  }
}

Play Billing does not see every payment. Bank transfers, USSD, and card payments taken through a local processor are invisible to it, and for many African apps that is most of the revenue. Point your payment provider at this endpoint and Measura ties each completed payment back to the campaign that produced the install.

Both query parameters are required. provider must be one of paystack, flutterwave or generic. The body is your provider's own payload, forwarded unmodified.

Creating a webhook

Create the endpoint in the dashboard under Integrations. Measura returns the URL to paste into your provider, and the signing secret once. It is not retrievable afterwards; revoke and create a new one if it is lost.

Signature verification

Every provider signs differently, so the header and algorithm depend on which one you configured. In all three cases the signature covers the exact bytes of the request body.

Responses

{
  "status": "recorded",
  "payment_event_id": "3f0a...",
  "reference": "your-provider-reference",
  "matched": true
}

matched reports whether the payer was tied to a known device. A payment with matched: false is still recorded and still counts toward revenue; it simply has no install to attribute to.

Amounts and currency

Paystack and Flutterwave send minor units. Measura converts on the way in, so 499900 kobo is stored as 4999.00. Revenue totals are always reported per currency and never summed across them, because adding NGN to USD produces a number that means nothing.

SDK keys are normally created in the dashboard. This endpoint exists for teams that provision apps programmatically.

{
  "app_id": "0f7c...",
  "label": "Production Android"
}

label is optional and defaults to SDK Key. The app must belong to the account the session is linked to; passing another tenant's app_id returns 403 rather than a working key.

Everything the dashboard does, it does through these. They are ordinary PostgREST procedure calls, so anything that speaks HTTP can drive them: provisioning a new app, flipping the SDK kill switch during an incident, or rotating a payment webhook secret from a deploy script.

SDK configuration

The SDK asks the server for its settings, so these take effect on the next configuration fetch without an app release. This is the lever to reach for during an incident rather than shipping a hotfix to the store.

curl -X POST "$MEASURA_URL/rest/v1/rpc/upsert_sdk_config" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"p_tracking_enabled": false}'

Payment webhooks

create_payment_webhook checks the app belongs to you before issuing anything, so a valid session cannot mint a webhook against another account. Paystack and Flutterwave require the secret from their own dashboard; generic generates one for you.

Team

Both require the caller to be an owner. A session without that role is refused rather than silently doing nothing.

Everything Measura holds for your account, in one JSON document. There is no notice period, no support ticket, and no export fee. If you decide to leave, your attribution history leaves with you.

curl -X POST "$MEASURA_URL/rest/v1/rpc/export_my_account_data" \
  -H "apikey: $ANON_KEY" \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{"p_max_rows": 50000}' > measura-export.json

p_max_rows caps rows per table and defaults to 50,000. It is clamped to 200,000: a single response has to fit in memory, and an uncapped export of a large account would not. For accounts beyond that, export in date ranges or ask us for a bulk dump.

The document includes a totals block per table, so you can confirm the export is complete before relying on it. If a count there equals your cap, the table was truncated and you should re-export that range with a higher one.

Three endpoints, called in order, import historical data from another attribution platform. The Migration Guide covers the column mappings and file preparation in detail.

// Request
{ "app_id": "7d2e5b1a-...", "source_platform": "appsflyer" }

// 200 OK
{
  "job_id": "c4a9...",
  "message": "Import job created",
  "column_mapping": { "Install Time": "installed_at", "Advertising ID": "gaid" }
}

Accepts application/json, text/csv or text/plain. Maximum 5 MB and 50,000 rows.

{
  "job_id": "c4a9...",
  "status": "processing",
  "total_rows": 24500,
  "processed_rows": 11200,
  "progress_pct": 45.7,
  "errors": [],
  "started_at": "2026-08-11T09:04:22.010Z",
  "completed_at": null
}

Per event errors inside an ingestion response carry a machine readable code.

Kotlin, minimum SDK 21. The release archive measures under 64 KB gzipped, enforced by a build gate at the same figure, so the number here cannot drift from the shipped artifact. Integrating it grows a minified APK by about 310 KB, since the archive excludes AndroidX WorkManager and the Room storage behind its job queue. Apps already using Kotlin coroutines see less.

import dev.measura.sdk.Measura
import dev.measura.sdk.core.MeasuraConfig

Measura.init(
    context = applicationContext,
    apiKey = "msr_4f3c...e91a",
    config = MeasuraConfig(
        batchSize = 50,
        flushIntervalMs = 30_000L,
        wifiOnlyMode = true,
        maxOfflineQueueSize = 10_000
    )
)

Methods

Configuration

There is no handleDeepLink method and no tracking permission call. The Play Install Referrer carries the click identifier through the store install automatically, which covers the attribution path without either.

The SDK is built to survive poor connectivity without losing events. Understanding the deferral rules explains most reports of missing data.

When sending is deferred

In every case below the event is written to persistent storage rather than dropped.

• No network connectivity.
• wifiOnlyMode is on and the device is on cellular. This is the default.
• Battery below the threshold with battery suppression enabled.
• The API key has not finished resolving.

Storage and limits

When retries are exhausted the batch returns to persistent storage and is retried in a later session rather than discarded.