Quickstart

This guide takes you from a Noryo identity to a first enrichment read back, in seven steps, entirely in the sandbox: no production key exists today, and nothing is billed. You will need:

• a Noryo identity (https://auth.noryo.app) and membership of a workspace on https://platform.noryo.app;
• curl, or a recent Node.js where fetch is built in, for the TypeScript examples.

11. Enable the sandbox on Platform

Sign in to https://platform.noryo.app with your Noryo identity and open the Clés d'API (API keys) page at /keys.

Complete the workspace's developer profile first: first and last name, verified email, professional phone number, organisation name, then what you are building and your integration context. An owner or an admin fills it in once, for the whole workspace. While anything is missing, enabling is refused and no key is issued; Platform lists the missing items. Details on Production access.

With the profile complete, an owner or an admin clicks Activer le sandbox Transaction Intelligence (enable the Transaction Intelligence sandbox). Enabling it is a workspace decision, and it is logged: it creates nothing but the right to issue nry_txn_sbx_ keys, with no intervention from Noryo.

22. Create a key and copy the secret

Name the key (for instance "test integration") and click Créer une clé Sandbox (create a sandbox key). An owner, an admin or a developer can create and revoke keys; every member can list them. The number of active keys per workspace is capped (the cap is read from the server; revoked keys do not count).

The credential has the form nry_txn_sbx_<key_id>.<secret>. The key_id is public (10 characters) and stays visible in the list. The secret is shown once only, at creation: Noryo does not keep it, only an HMAC verifier is stored. Copy it now. If you lose it there is no rotate button: revoke the key and create a new one. A revoked key returns 401 from the very next request.

33. Put the secret in an environment variable

The secret lives server-side, in an environment variable. Every example reads NORYO_API_KEY.

export NORYO_API_KEY="nry_txn_sbx_..."

Never put it in a browser bundle, a public repository, a mobile binary or client-side JavaScript. An nry_mer_* key (Merchant API) is refused on Transaction Intelligence, and the reverse is also true. Details on Authentication.

44. First call: enrich a transaction

The body is a TransactionInput. Two fields are enough: descriptor, the label as the bank renders it, and direction, either incoming or outgoing. The schema is closed: an unknown field is refused with 422, never ignored. The body is application/json, otherwise 415.

Minimal body

curl -sS -i https://api.noryo.app/transactions/v1/enrichments \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"descriptor":"CARTE 09/09 MONOPRIX PARIS","direction":"outgoing"}'

const response = await fetch("https://api.noryo.app/transactions/v1/enrichments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NORYO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ descriptor: "CARTE 09/09 MONOPRIX PARIS", direction: "outgoing" }),
});

console.log(response.status, response.headers.get("location")); // 201
const enrichment = await response.json();
console.log(enrichment.enrichment_id);

Status 201: the enrichment has been created. The Location header says where it lives, and the body carries its enrichment_id, of the form enr_<uuid>. Keep it for step 5.

Full example

The contract's achat_carte example: occurred_at in RFC 3339 with an offset, amount.value as a string, the account in account_hint (so that a coverage window can be linked to it), your own identifier in external_transaction_id.

curl -sS https://api.noryo.app/transactions/v1/enrichments \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "descriptor": "CARTE 09/09 MONOPRIX PARIS 15",
    "direction": "outgoing",
    "occurred_at": "2026-09-09T07:31:00+02:00",
    "amount": { "value": "49.90", "currency": "EUR" },
    "payment": { "rail": "card", "mcc": "5411", "card_present": true },
    "location_hint": { "country": "FR" },
    "account_hint": { "iban": "FR7630006000011234567890189" },
    "external_transaction_id": "tx-2026-09-09-0042"
  }'

const transaction = {
  descriptor: "CARTE 09/09 MONOPRIX PARIS 15",
  direction: "outgoing",
  occurred_at: "2026-09-09T07:31:00+02:00",
  amount: { value: "49.90", currency: "EUR" },
  payment: { rail: "card", mcc: "5411", card_present: true },
  location_hint: { country: "FR" },
  account_hint: { iban: "FR7630006000011234567890189" },
  external_transaction_id: "tx-2026-09-09-0042",
};

const response = await fetch("https://api.noryo.app/transactions/v1/enrichments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NORYO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(transaction),
});

const enrichment = await response.json();
console.log(enrichment.resolution.policy.outcome);

What the response contains

An extract of the contract's 201 response for this example:

{
  "enrichment_id": "enr_3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "created_at": "2026-09-09T05:31:02Z",
  "contract_version": "ti_v1",
  "canonical_version": "canon_ti_v1",
  "fingerprint": "canon_ti_v1:c2a1…",
  "signals": {
    "used": ["descriptor", "direction", "payment.rail", "location_hint.country", "occurred_at", "amount", "account_hint.iban", "external_transaction_id"],
    "ignored": ["payment.mcc", "payment.card_present"],
    "conflicting": []
  },
  "resolution": {
    "policy": { "outcome": "resolved", "archetype": "achat_carte", "missing": [], "policy_version": "ti_resolution_v1" },
    "counterparty": { "entity_id": "b83d1756-258c-4541-adc7-54eec83dbd3c", "name": "Monoprix", "kind": "brand" },
    "category": { "slug": "alimentation.supermarche", "label": "Supermarché", "source": "entity_graph" },
    "transaction_type": { "canonical": "card_purchase", "evidence": "rail_rule", "contradiction": null }
  },
  "relationships": [],
  "series": [],
  "relationships_policy": {
    "detector_version": "rel_v1",
    "calibration": "non_calibree",
    "unresolved": [{ "type": "series", "outcome": "single_occurrence", "occurrences": 1 }]
  }
}

Read these first:

• signals.used and signals.ignored say which of the signals you sent were passed to the engine and which nobody read (here payment.mcc and payment.card_present).
• resolution.policy.outcome is the verdict (resolved). Read that, not the numbers under confidence: declared constants, not probabilities (see Score semantics).
• counterparty can be null: an honest unknown, not a failure, and counterparty_note says why.

A single occurrence does not make a series: relationships_policy.unresolved says so (single_occurrence). Every field is on Enrich a transaction.

55. Read the enrichment back

With the identifier received in step 4:

curl -sS https://api.noryo.app/transactions/v1/enrichments/enr_3f2504e0-4f89-41d3-9a0c-0305e82c3301 \
  -H "Authorization: Bearer $NORYO_API_KEY"

const enrichmentId = "enr_3f2504e0-4f89-41d3-9a0c-0305e82c3301";
const response = await fetch(
  `https://api.noryo.app/transactions/v1/enrichments/${enrichmentId}`,
  { headers: { Authorization: `Bearer ${process.env.NORYO_API_KEY}` } },
);

console.log(response.status); // 200
const stored = await response.json();
console.log(stored.expires_at);

The 200 response is a StoredEnrichment:

An identifier that is unknown, malformed, expired or from another workspace returns 404, the same response in all four cases. See Read an enrichment.

66. Declare an observation coverage window (optional)

A coverage window is a fact about an account and a period, not about a transaction: you declare whether every operation on an account between two dates has been provided (completeness: complete, partial or unknown). Only complete lets Noryo draw a conclusion from an absence. Without it, a missing instalment proves nothing and a series' lifecycle stays unknown. The account is the enrichment's (account_hint).

curl -sS https://api.noryo.app/transactions/v1/coverage-windows \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_hint": { "iban": "FR7630006000011234567890189" },
    "covered_from": "2026-07-01",
    "covered_to": "2026-07-31",
    "completeness": "complete"
  }'

const response = await fetch("https://api.noryo.app/transactions/v1/coverage-windows", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NORYO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    account_hint: { iban: "FR7630006000011234567890189" },
    covered_from: "2026-07-01",
    covered_to: "2026-07-31",
    completeness: "complete",
  }),
});

console.log(response.status, await response.json()); // 200

The contract's 200 response:

{
  "covered_from": "2026-07-01",
  "covered_to": "2026-07-31",
  "completeness": "complete",
  "provenance": "caller_asserted",
  "merged_intervals": 0,
  "policy_version": "cov_v1",
  "note": "",
  "request_id": "req_01J9…"
}

provenance is always caller_asserted: Noryo records your declaration without verifying it. Adjacent intervals are merged (merged_intervals); covered_to cannot be in the future. See Observation coverage.

77. Check usage on Platform

On https://platform.noryo.app/usage, Transaction Intelligence section, you read over 24 hours, 7 days or 30 days, per UTC day, per call family and per key: the total of authenticated requests, successes (2xx), client errors (4xx excluding 429), rate-limited requests (429, per key or per workspace) and server errors (5xx). A revoked key keeps its history; the register is kept for 35 days.

This is not a billing ledger: a 422 counts as a request, a 401 is never counted, and nothing is billed. A zero is distinct from "not observed" (before the register went into service) and from "unavailable". See Usage and API keys.

Headers and rate limits

Once the credential is accepted, every response carries noryo-request-id, the identifier to quote to support (on an error it is also in the body, as request_id), together with noryo-ratelimit-limit and noryo-ratelimit-remaining. On 429, Retry-After gives the seconds to wait. Rate limiting is an operational protection:

What next

• Authentication: key families, revocation, where to keep the secret.
• Enrich a transaction, Read an enrichment, Observation coverage.
• Recurring series and Relationships: what several transactions reveal together.
• Errors, Rate limits, Sandbox limitations.
• The reference and the error catalogue, generated from https://api.noryo.app/openapi.json.