API Reference

A small set of HTTPS endpoints. The SDK handles ingestion, signing and retries, so most integrations never call these. Call them for server to server tracking, or to build on the analytics data yourself.

Base URL

Every endpoint below is served from one host.

https://api.measura.dev/v1/{function}

Pointing at staging or a self-hosted project: override the endpoint in SDK configuration, do not patch 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.

Three mechanisms, three jobs. The API key never authenticates an event. 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 /v1/resolve-key
X-Measura-Api-Key: msr_4f3c...e91a

We store a SHA-256 hash only. The plaintext is shown once and cannot be recovered, so a lost key is revoked and reissued.

Used once per SDK session, to exchange for the identifiers and the signing secret. It does not authenticate events.

2. Event signature

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

The canonical payload rules are strict:

• 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

Analytics and migration take a bearer session token from sign-in. Account identity comes from server-controlled token claims, so no parameter change can reach another tenant’s data.

GET /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": "0.1.0",
      "device_model": "Samsung SM-A245F",
      "os_name": "android",
      "os_version": "14",
      "app_version": "2.3.1",
      "device_fingerprint_components": {
        "user_agent": "MeasuraSDK/0.1.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": 1786440001732
    },
    {
      "status": "deduplicated",
      "event_id": "open_1754899210000_b7d2f4a1",
      "server_timestamp": 1786440001733
    },
    {
      "error": "Invalid signature",
      "code": "AUTH_ERROR"
    }
  ],
  "batch_size": 3
}

Per event status is accepted, deduplicated or rejected. server_timestamp is Unix milliseconds.

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.

Called once at SDK initialisation and cached for the session.

{
  "customer_id": "3f1c8a2e-9b47-4d1e-8a6f-2c5b9e7d1a03",
  "app_id": "7d2e5b1a-4c93-4f8e-b6a1-9e3c7f2d5b84",
  "sdk_secret": "b91f7c...4e2a",
  "config": {
    "tracking_enabled": true,
    "sampling_rate": 1,
    "batch_size": 50,
    "flush_interval_ms": 30000,
    "wifi_only_mode": true,
    "suppress_on_low_battery": true,
    "low_battery_threshold": 15,
    "max_retry_attempts": 5,
    "max_offline_queue_size": 10000,
    "ingest_endpoint": null
  }
}

config is the remote SDK configuration (see Account operations). It is omitted if the lookup fails, and the SDK then keeps its built-in defaults.

Links are issued on the functions host.

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 to the destination so the SDK can attribute the resulting install. When the link has an in-app path and the destination opens your app directly, rather than a store page, measura_path is appended too.
• For Google Play destinations the click ID travels in the referrer parameter, which survives the install and gives deterministic attribution. It carries the click ID and nothing else: deferred parameters are exchanged for it afterwards at /deferred-link, so your campaign data never appears in a URL that Play truncates and anyone holding the link can read.
• A visitor on a phone that cannot install the app is sent to a page showing the link's USSD code, when one is configured.
• 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, "refunded": 84000, "net": 6036000, "count": 388, "attributed": 5110500 },
    "USD": { "gross": 2140, "refunded": 0, "net": 2140, "count": 24, "attributed": 1702 }
  },
  "by_provider": { "paystack": 6036000, "flutterwave": 2140 },
  "attributed_count": 350,
  "attribution_rate_pct": 85
}

gross is payments only. Refunds, partial refunds, chargebacks and disputes are summed into refunded and subtracted to give net. attributed is the net amount tied to a known device and by_provider is net per provider. count and attributed_count count payments, and attribution_rate_pct, a whole number, is the share of payments matched to a device. 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,
  "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
  }
}

Point your payment provider here and Measura ties each completed payment back to the campaign that produced the install. This covers revenue Play Billing never sees: bank transfer, USSD, and cards taken through a local processor.

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

Creating a webhook

Create the endpoint in the dashboard under Integrations. The dashboard shows the full 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

Header and algorithm depend on the provider. In every case the signature covers the exact bytes of the request body.

Event types

Every recorded payment has an event_type: payment, refund, partial_refund, chargeback, or dispute. A reversal is a separate, immutable record linked to the original payment where Measura can determine the link - it never overwrites or deletes the original. Revenue reporting subtracts every reversal from gross to give net, rather than summing every row blindly.

Idempotency

Redelivering the same event - same provider, same reference, same event_type, scoped to your account - is safely ignored. Measura answers {"status": "duplicate"} with 200 rather than recording it twice. Providers retry on any non-2xx, so redelivery is expected and normal, not an error condition.

Responses

{
  "status": "recorded",
  "payment_event_id": "3f0a...",
  "reference": "your-provider-reference",
  "event_type": "payment",
  "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 Stripe send minor units (kobo, cents); Measura converts on the way in, so 499900 kobo is stored as 4999.00. Flutterwave sends major units already and is stored as received. Revenue totals are always reported per currency and never summed across them, because adding NGN to USD produces a number that means nothing.

This is the reason a mobile measurement partner exists. An ad network will not optimise a campaign it cannot measure, and it will not take your word for which installs it caused. So Measura attributes the install and reports it back to the network you configured, in that network's documented format.

Configuring a network

Each network you configure has a postback_format, which decides the wire shape Measura sends:

whatsapp_business is not a separate wire format. Click-to-WhatsApp ad attribution is measured through Meta's own Conversions API, so a WhatsApp Business config uses meta_capi with WhatsApp-specific event naming, the same integration as a plain Meta config.

Which network receives an install

An install is sent only to the network whose link was clicked, taken from the click's channel. Installs with no ad click are not sent, except to google_ads_app, which receives every install because Google decides attribution itself and says so in its response. A config can apply to all apps or to one app; an app's own config wins. Step-by-step setup per network is in the Ad Network Setup guide.

Canonical payload shape

When a config uses measura_canonical, this is exactly what arrives at your URL:

{
  "event_type": "install",
  "attribution_id": "b7e1...",
  "install_id": "9a02...",
  "installed_at": "2026-09-08T10:00:00.000Z",
  "model": "last_click",
  "confidence_score": 87,
  "click_id": "c441...",
  "campaign_id": "8f10...",
  "gaid": "38400000-8cf0-11bd-b23e-10b96e40000d",
  "measura_customer_id": "1d55...",
  "timestamp": 1788800000000
}

A purchase postback carries the same envelope with event_type: "purchase" plus value and currency. Purchase postbacks fire when a payment recorded through the payment webhook below resolves to a device that already has an attributed install.

Event types

A network config opts into install, purchase, or both. Choosing purchase is what makes revenue-based campaign optimisation possible on the network side, rather than install counts alone.

Delivery and retries

Delivery is attempted roughly every 60 seconds. A failure is classified before Measura decides whether to retry it:

After the final attempt, the attribution's postback status is marked failed for manual review. A successful delivery marks it sent.

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; another tenant's app_id is answered 404, exactly as if it did not exist.

{
  "api_key": "msr_4f3c...e91a",
  "key_id": "5b1e...",
  "label": "Production Android",
  "app_id": "0f7c...",
  "warning": "Store this now. It is shown once and cannot be recovered."
}

These are the main procedures the dashboard itself calls. 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, Flutterwave and Stripe require the secret from their own dashboard; generic generates one for you.

Teams and members

An account holds one or more teams, and apps belong to a team. Creating a team and inviting someone are separate operations.

Roles are checked in the database. A session without the required role is refused with an error rather than silently doing nothing.

Apps, keys and links

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,
  "errors": [],
  "started_at": "2026-08-11T09:04:22.010Z",
  "completed_at": null
}

Ingestion errors, and the 403 a plan gate returns, carry a machine readable code. Other endpoints return {"error": "..."} with the HTTP status alone.

Kotlin, minimum SDK 21. The release archive measures under 100 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 312 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 tracking permission requirement. Install attribution rides the Play Install Referrer through the store install automatically, and deferred deep link delivery is push based: setDeferredDeepLinkListener is called for you, at most once, if the install came from a Measura link with a configured destination. The one URL you hand the SDK yourself is a link that opens an app already installed:

intent?.data?.let { uri ->
    Measura.handleDeepLink(uri)?.let { path -> navigateTo(path) }
}

A failed send is retried after 1, 2, 4 and 8 seconds and then written to disk, never dropped. A 4xx other than 408 or 429 is not retried: the batch is written to disk at once, since the same bytes would get the same answer.

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.