Norra docs

Quickstart

Send one delivery to Norra and read the receipt. It takes about two minutes.

Before you start

You need a company in Norra and the sources.manage permission on it. Making a key needs a fresh BankID sign-in.

To try a call first, the API reference sends real requests with Test Request: to the demo deployment with the demo key, or to your own sandbox with a sandbox key you paste in.

1. Add a source

A source is one system that sends numbers to Norra. Open the company in the app, go to Sources, and fill in Add a source:

  • Give it a name, for example Billing system.
  • Choose Push as the way it delivers.
  • List the fields it sends, for example period, revenue and active_users.

Save it with Add the source. The fields are the source's shape. Each save is a new shape version, and the first is version 1.

2. Make a write key

Go to the company's Developer page. Under Make a key:

  • Pick the source.
  • Choose Write as what the key may do.
  • Tick Sandbox key while you try things out. What a sandbox key sends is marked test and reaches no report.

Select Make the key. The key is shown once. Copy it into your secret store now.

3. Send one delivery

shell
export NORRA_KEY="paste the key here"

curl https://app.norra.hello-why.com/v1/ingest \
  --request POST \
  --header "Authorization: Bearer $NORRA_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "idempotency_key": "2026-09",
    "shape_version": 1,
    "payload": {
      "period": "2026-09-01",
      "revenue": "4201000",
      "active_users": "1200"
    }
  }'

The idempotency key is your own name for the delivery. Sending the same one again returns the same receipt and stores nothing twice, so a retry is safe.

Values are strings. An amount is an exact decimal, and a string keeps a JSON parser from reading it as a float.

4. Read the receipt

202 Accepted means the delivery is stored:

json
{
  "artifact_id": "0199c1f4-6b3a-7c21-9f10-2a5b4c6d8e90",
  "sandbox": true,
  "shape_version": 1,
  "status": "queued"
}
  • artifact_id names what was stored. Keep it. It is what you cite when you ask why a number in a report is what it is.
  • status is queued. The delivery is parsed after it is stored.
  • sandbox is true for a sandbox key.

The Developer page shows when the source last received a delivery, when it last parsed one, and the last error if there was one.

Next