Enrich a transaction

A raw transaction goes in; a structured enrichment comes out. POST /transactions/v1/enrichments takes a TransactionInput object, authenticated with your nry_txn_sbx_* key (see Authentication), and returns an Enrichment: counterparty, transaction type, relationships, series. This page covers the request body, the Idempotency-Key header, the difference between 201 and 200, and the two blocks of the response to read first: signals and resolution.policy.

The operation

The body must be application/json, otherwise 415. Every error carries request_id in its body, which is what you quote to support; once the credential is accepted, every response also carries the noryo-request-id, noryo-ratelimit-limit and noryo-ratelimit-remaining headers (see Rate limits).

The body: TransactionInput

Only descriptor and direction are required; an optional field is only worth sending if it is actually read (see signals.used below).

A closed schema

An unknown field is never silently dropped: it is rejected with a 422 invalid_input whose errors[] entries carry field and code, here unknown_field. The same rule applies inside payment, location_hint, counterparty_hint and account_hint, and an array in place of any of those objects is rejected with must_be_object.

occurred_at: an instant, not a date

The value is an RFC 3339 timestamp with an offset, for example 2026-09-09T07:31:00+02:00. A bare date is refused: midnight is not the same day everywhere, and series cadence is read against the calendar. The must_be_rfc3339_with_offset code covers both form and calendar: 2026-02-30T00:00:00Z, an offset of +16:00 or a 23:59:60 second are all refused.

amount: a decimal as a string

amount.value is a string ("49.90"), never a JSON number: a float would lose pence in silence. The number of decimal places allowed depends on the currency: 5.905 in EUR is refused (amount_precision_exceeds_currency), and so is 100.50 in ISK, because ISK and JPY have none and KWD has three. currency must belong to the Money.currency enum; any other currency returns a 422 of type unknown_currency.

account_hint and counterparty_hint

The IBAN, whether the account's or the counterparty's, is reduced on entry to its country and bank code: the account number never enters the system. Without account_hint, a transfer pair cannot be identified. For a card or wallet with no IBAN, external_account_id carries your own identifier; its single purpose is to link the transaction to an observation coverage declaration on the same account, and it does not enter the fingerprint.

external_transaction_id does not enter the fingerprint either: it says how you name the transaction, not what it is, and it stops two submissions of the same transaction from being related to each other.

Idempotency-Key

The header is optional. Its value is 1 to 255 bytes of visible ASCII (0x21 to 0x7E); an empty value, or one outside that alphabet, returns a 400 invalid_idempotency_key.

"Different request" is judged on the economic fingerprint and on nothing else. Two bodies that differ only by external_transaction_id, account_hint or counterparty_hint share a fingerprint: the first submission is replayed. So do not reuse a key for two transactions you distinguish by those fields alone. A key is retained for at least 24 hours; beyond that it may open a new operation.

201 or 200

A 201 means an enrichment was created; a 200, that an already processed request was replayed, creating nothing. Both carry a Location header pointing at the resource, which stays readable for 30 days through GET /transactions/v1/enrichments/{enrichment_id} (see Read an enrichment). The body is an Enrichment: enrichment_id, created_at, contract_version, canonical_version, fingerprint, signals, resolution, then relationships and series (empty lists when no relationship or series was concluded) and relationships_policy, whose unresolved says why a detector did not conclude.

signals.used and signals.ignored

signals.used lists the received signals that were passed to the engine: to the identity resolver, or to the store for series, relationships and observation coverage. signals.ignored lists those nobody read. Only fields present in your request appear in either list. Today, payment.mcc, payment.card_present, payment.network_merchant_id, location_hint.city, location_hint.postal_code and counterparty_hint.bic are accepted and then ignored.

This block is not a convenience: without it you could send an MCC for months, receive 201, and believe it weighs on the response. Check in your integration tests that no field you rely on shows up in ignored. signals.conflicting mirrors resolution.signal_conflicts, so that the block is complete.

What policy.outcome means

resolution.policy states what the response asserts, and it is the field to base decisions on. It carries outcome, archetype, missing and policy_version.

What "resolved" means depends on the nature of the transaction. A transfer to a person is resolved without any identity being created; a cash withdrawal is resolved without a merchant; a card purchase, on the other hand, requires its counterparty, and its absence yields partial with missing: ["counterparty_entity"]. A counterparty of null is a result, not a failure, and counterparty_note says why. The numbers under resolution.confidence are declared constants, neither probabilities nor thresholds: see Score semantics.

Examples

With curl:

curl -X POST https://api.noryo.app/transactions/v1/enrichments \
  -H "Authorization: Bearer $NORYO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tx-2026-09-09-0042" \
  -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"
  }'

With fetch:

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",
    "Idempotency-Key": "tx-2026-09-09-0042",
  },
  body: JSON.stringify({
    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 enrichment = await response.json();
console.log(response.status, enrichment.signals, enrichment.resolution.policy);

For this request, the response lists payment.mcc and payment.card_present under signals.ignored.

Error responses

Every error returned by the API is a Problem object with type, title, status and request_id, detail when the API provides one and, on a 422, errors[]. A 401 means the credential is missing, malformed, from another family, unknown or revoked; a 403 an inactive workspace; a 413 a body that is too large; a 415 a body that is not application/json; a 429 a rate limit reached, to be retried after Retry-After. The 400, 409 and 422 cases are described above. The full catalogue lives on Errors and on /transaction-intelligence/errors/<code>.