How to push metrics into Clarion from your own systems

A scorecard is only useful if the numbers are current, and numbers typed by hand go stale the first week someone’s on holiday. If a metric already exists in your CRM, billing system, warehouse or a spreadsheet, the job is to get it into Clarion without anyone touching it.

Clarion gives you three ways to do that. This guide covers which to use when, how each one behaves, and the mistakes that cause silent gaps on the scorecard.

How values are stored

All three methods share one model, and it’s worth understanding first. Each metric has a frequency of daily, weekly or monthly, and each value belongs to a period: that day (UTC), that week starting Monday, or that month starting on the 1st.

Writing a value for a period that already has one replaces it. That makes every method safe to run on a schedule: a job that runs three times leaves one value, not three. It also means you can backfill: send a past date and the value snaps to the start of that period.

Option 1: A push URL per metric

Use it when the source is a no-code tool, such as Zapier, Make, n8n, a Google Sheets script or another product’s “call a webhook” step, or anything that can send a POST but can’t hold an API key.

Each push URL belongs to exactly one metric and can only write to that metric. It’s created in the app, in the metric’s edit form under Push URL, and shown once. There’s no API key: the URL is the credential.

The request is a POST with a value, as JSON, a form body, or a query string if the tool can only fire a bare POST. Numeric strings like "1,234" are accepted; anything that isn’t clearly a number, like "$12k", is refused rather than guessed at. An optional date records a past period, and notes stores a note with the value. A successful call returns the metric’s name, the value, and the start of the period it was stored under.

Two things to know:

• Treat the URL as a password. Because it’s in the path, it can end up in a tool’s logs. If it may have leaked, use Generate new URL: the old one stops working immediately.
• Unknown, replaced, turned-off and archived all return the same 404. That’s deliberate, so the endpoint can’t be used to probe for URLs. If a push suddenly 404s, check the metric in the app.

Details: metric push URLs.

Option 2: Let Clarion fetch the number

Use it when the number is already available at an HTTPS URL that returns JSON, like a reporting endpoint, a BI tool’s API or a small service you control, and you’d rather not run a scheduler.

An Owner or Admin configures it on the metric under Fetch from URL: the URL, a dot path to the number (such as data.totals.revenue or items[0].count), an optional single auth header, and how often to run: hourly, every six hours or daily. Test fetches once and shows what it found, without recording anything.

If you’re building the endpoint, the constraints are strict on purpose:

• HTTPS on port 443 only, and no internal or private addresses.
• Redirects are not followed. Give Clarion the final URL.
• The response must arrive within 5 seconds and be under 256 KB.
• The auth header is stored encrypted and never shown again. Changing the URL to a different host removes it.

When a fetch fails, the metric shows why. After 10 failures in a row the source pauses until someone saves it again. See pull metrics from a URL and the JSON API integration.

Option 3: The ingest API

Use it when you’re writing code: a cron job or a pipeline that sends many metrics at once.

Create an API key with the metrics:write scope in Settings → Integrations → API Keys. Keys belong to one company, are shown once, and can be revoked at any time. Then POST a batch of entries to /v1/companies/:companyId/metrics/ingest. See create API keys and API authentication and scopes.

Each entry names a metric by metric (its name, matched case-insensitively) or metricId, with a value and an optional weekOf for backfills. The traps:

• Names aren’t unique. Several teams can each have a “Revenue”. A name that matches more than one metric returns ambiguous_metric with the candidates, and nothing is written. Narrow it with teamId, or better, use metricId. Each successful entry returns the metricId it resolved to, so you can pin it after the first run.
• 201 doesn’t mean success. Entries fail individually without failing the batch. Check each result’s status: ok, unknown_metric, ambiguous_metric or invalid_value. A 201 with processed: 0 wrote nothing.

Full reference: ingest metric values with the API and the REST API.

Which one to choose

• No-code tool, one number per step: push URL.
• A JSON endpoint already exists: fetch from URL.
• Your own code, many metrics per run: ingest API.

You can mix them across metrics. All three fire the metric.ingested webhook: a push or a scheduled fetch when it records a value, and an ingest call when it completes, with counts of what was processed and skipped. See reacting to changes with webhooks.

A rollout checklist

• List the scorecard’s metrics and the system each comes from.
• Pick a method per metric.
• Run it in parallel with manual entry for two weeks and compare the numbers.
• For API jobs, log every non-ok status and alert on them.
• Tell each metric’s owner it’s automated, so they stop entering it.

Common mistakes

Trusting the status code. Read the per-entry results.

Matching by name forever. Pin metricId after the first successful run.

Pointing a fetch at a redirect. It fails every time. Use the final URL.

Wrong timezone for daily metrics. Daily periods are UTC days. A job that runs at 11pm local time may land on tomorrow.

Sharing push URLs in chat. Anyone with the URL can write that metric. Rotate it if it’s been passed around. For owners, keeping your metrics current covers checking automated numbers.