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 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.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, stripe 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 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 nets these against each other 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",
  "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 the format that network actually accepts.

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.

None of the native formats (Meta, Google, Snapchat, TikTok) have been verified against a live vendor account. Each request is built exactly to the vendor's published contract and covered by tests that pin the wire format byte for byte, but the only way to confirm a specific network accepts it is to configure your real credentials and check that network's own delivery log.

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 to at least one configured network 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; 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, Flutterwave and Stripe 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 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 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.