APIs & BI integrations that work for every side

Sonaflo doesn’t replace your data stack—it feeds it cleaner inputs. Brands, agencies, and publishers can all wire standardized results into their own BI tools and workflows instead of copying and pasting charts between systems.

  • Feed standardized results into platforms like Snowflake, Looker, or Tableau—whether you’re a brand, agency, or publisher.
  • Trigger exports and notifications when studies are ingested, updated, or approved so no team is working from stale numbers.
  • Push finished decks and PDFs into the tools where sales, marketing, planning, and finance already live.

What you’ll build in ~30 minutes

  • Submit reports to POST /v1/reports
  • Register webhooks to get async status & mapping requests
  • (Recommended) Attach a field map so we auto-standardize your schema

How it works

Simple, robust, vendor-friendly

  • One payload shape across all campaigns
  • Async webhooks for status updates & mapping prompts
  • Idempotent writes (safe retries with X-Idempotency-Key)
  • Audit trail on every vendor write

Authentication

Headers & base URLs

  • Header: X-API-Key: <your-api-key>
  • Content-Type: application/json
  • Production: https://api.sonaflo.com
  • Sandbox: https://api.sandbox.sonaflo.com (relaxed limits)

Submit a report

Endpoint

POST /v1/reports

Minimum payload

{
  "vendor_id": "vendor_123",
  "campaign_id": "cmp_456",
  "reported_at": "2025-10-10T12:00:00Z",
  "samples": 5234,
  "currency": "USD",
  "metadata": {"panel":"ExamplePanel","country":"US"},
  "metrics": [
    {"name":"brand_lift_awareness_pct","value":4.6,"ci_low":2.0,"ci_high":6.9,"segment":"18-34"},
    {"name":"brand_lift_favorability_pct","value":1.7}
  ]
}

cURL

curl -X POST https://api.sonaflo.com/v1/reports \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $SONAFLO_API_KEY" \
  -d @examples/submit_report.json

Python

from sdk.python.sonaflo_sdk import SonafloClient
client = SonafloClient(api_key="YOUR_KEY")
resp = client.create_report({
  "vendor_id":"vendor_123","campaign_id":"cmp_456",
  "reported_at":"2025-10-10T12:00:00Z","samples":5234,"currency":"USD",
  "metadata":{"panel":"ExamplePanel","country":"US"},
  "metrics":[
    {"name":"brand_lift_awareness_pct","value":4.6,"ci_low":2.0,"ci_high":6.9,"segment":"18-34"},
    {"name":"brand_lift_favorability_pct","value":1.7}
  ]
})
print(resp)

Node

const { SonafloClient } = require('./sdk/node/sonaflo');
const client = new SonafloClient(process.env.SONAFLO_API_KEY);
(async () => {
  const out = await client.createReport({
    vendor_id:"vendor_123", campaign_id:"cmp_456",
    reported_at:"2025-10-10T12:00:00Z", samples:5234, currency:"USD",
    metadata:{ panel:"ExamplePanel", country:"US" },
    metrics:[
      { name:"brand_lift_awareness_pct", value:4.6, ci_low:2.0, ci_high:6.9, segment:"18-34" },
      { name:"brand_lift_favorability_pct", value:1.7 }
    ]
  });
  console.log(out);
})();

Webhooks

Register your endpoint

PATCH /v1/vendors/{vendor_id}

curl -X PATCH https://api.sonaflo.com/v1/vendors/$VENDOR_ID \
  -H "X-API-Key: $SONAFLO_API_KEY" -H "Content-Type: application/json" \
  -d '{"webhook_url":"https://yourdomain.com/sonaflo/webhooks","events":["report.created","report.updated","report.failed","mapping.requested"]}'

Example event

{
  "id": "evt_abc123",
  "type": "report.updated",
  "created": "2025-10-10T12:05:00Z",
  "data": {"report_id":"rep_789","status":"standardized","next_actions":[]},
  "signature": "v1,t=1696940000,sha256=deadbeef..."
}

Signature verification: Use our JWKS (sample in the kit at security/jwks_public.json). Reject if the signature or kid doesn’t match.

Field mapping

Start with our template

Use templates/field_mapping.csv from the Integration Kit.

vendor_fieldsonaflo_fieldnotestransform
lift_awarenessbrand_lift_awareness_pctpercent
lift_considerationbrand_lift_consideration_pctpercent
sample_sizesamplesint
countrycountry_codeuppercase

We’ll prompt you via the mapping.requested webhook if we need additional info.

Error handling

Clear responses & safe retries

  • 400 — Schema issue (field validation)
  • 401 — Missing/invalid API key
  • 422 — Metric conflicts (e.g., CI bounds)
  • 429 — Backoff and retry with exponential jitter
  • 5xx — Retry with X-Idempotency-Key to avoid duplicates

Performance & limits

Targets & guardrails

  • Payload size: ≤ 5 MB per request
  • Rate limit: 600 writes/min per vendor (burstable)
  • Latency: P95 ≤ 200 ms for writes; webhooks within 30 s

Security

Designed for enterprise workflows

  • TLS 1.2+ only
  • Separate sandbox & production keys
  • Webhook signing with rotating keys (kid in header)
  • Full audit trail on vendor writes

Environments

  • Sandbox: https://api.sandbox.sonaflo.com (fake data, relaxed rate limits)
  • Production: https://api.sonaflo.com

Get the kit

  • OpenAPI 3.0 spec (openapi.yaml)
  • Postman collection (postman_collection.json)
  • Python & Node SDK helpers
  • Example payloads & webhook event
  • CSV field-mapping template
  • Use header X-Sonaflo-Priority: vendor for priority routing.
Download Integration Kit (ZIP)

Need help? integrations@sonaflo.com

Scroll to Top