RUIAN API
Analytics & DataLook up and validate Czech addresses against RUIAN, the official state register of territorial identification, addresses, and real estate. Agents confirm an address exists before it reaches a contract or a delivery.
What This Integration Enables
RUIAN is not a geocoder and this is not address autocomplete. RUIAN is the Czech state register of territorial identification, addresses, and real estate, which means an address either exists in it or it does not, and every one that does carries a numeric identifier assigned by the state. That identifier is the useful part. It turns an address from a string that three systems will spell three ways into a key that matches exactly, every time, across your CRM, your ERP, and your carrier integration. This connector wraps the free REST service at ruian.fnx.io, which mirrors the registry data without requiring its SOAP interface, and runs on a free key requested by email with a usage allowance sized for validation rather than for bulk export.
Two approaches sit side by side. The validator takes an address as a person typed it, tolerates typos and the very common case of descriptive and orientation house numbers being swapped, and answers with one of four statuses: MATCH for an exact hit, POSSIBLE for a close candidate it is proposing, NOT_FOUND when there is no such place, and ERROR when the query itself was malformed. Those four are genuinely different outcomes and a flow should treat them as four branches rather than as true and false. The builder walks the territorial hierarchy instead, from region to municipality to street to addressable place, which is what you want behind a cascading form where the user picks rather than types, and what you want when a long street spans more than one postal code and List Postal Codes has to settle which one applies.
Without FlowRunner
With FlowRunner
Use Case Scenarios
Checkout Address Validation With Four Outcomes
A customer submits a Czech shipping address on Shopify. The agent runs Validate Address with everything the form captured, at minimum a municipality and a house number. A MATCH continues straight to fulfilment with the RUIAN identifier stored on the order. An ERROR means the query was malformed and the flow fixes its own field mapping rather than blaming the customer. A NOT_FOUND goes back to the customer while they are still on the page, which is the cheapest possible moment to correct an address. A POSSIBLE is the interesting one: the registry is proposing a specific real place that is close to what was typed, and the agent holds it rather than accepting it. One API call has separated the orders that can ship from the orders that need a decision, and it has done so before a label was printed.
Legacy Address Master Cleanup
A customer table in PostgreSQL has accumulated years of hand-entered Czech addresses, with the same building written several different ways across several different records. The agent runs Validate Address over the table and, for each match, calls Get Address By RUIAN ID to pull the canonical municipality, municipality part, street, house numbers, and postal code. Writing the RUIAN identifier onto each row does something that string normalisation cannot: two rows that resolve to the same identifier are the same physical place regardless of how they were spelled, so deduplication becomes an exact join instead of a fuzzy one. The cleaned records feed reporting in Snowflake with a stable key that survives the next round of manual data entry.
Contract Intake With a Cascading Picker
A property or service contract needs an address that will hold up if the contract is ever read closely. Instead of a free-text field, the agent drives the builder flow: List Regions, then List Municipalities for the chosen region, then List Streets, then List Places, which returns each addressable place with its descriptive, orientation, and registration numbers and its RUIAN identifier. Where the street spans several postal codes, List Postal Codes resolves which codes actually serve it and reports how many addressable places it inspected to decide. The selected place, its identifier, and its canonical formatting go into the document sent through DocuSign. The person preparing the contract confirms the specific building before it is sent, because a lease that names the wrong entrance is a legal problem rather than a shipping inconvenience.
Human-in-Loop Highlight
The gate is the POSSIBLE status. When Validate Address cannot match exactly, it proposes the closest real place it can find, and that proposal is a rewrite of something a customer wrote deliberately. Silently accepting it means a parcel goes to an address the customer never typed, or a contract names a building they did not choose, and neither error announces itself until it has already cost something. So the agent treats a POSSIBLE as an automation exception rather than as a near-enough pass. It posts both versions to the fulfilment queue side by side: "Order 8842. Customer entered: Nadrazni 12, Brno. RUIAN proposes: Nadrazni 12/1247, Brno, Zabovresky, PSC 61600, confidence [score], status POSSIBLE. Ship to the proposed address, keep the original, or contact the customer?" The reviewer picks, and only then does anything reach the label or the contract. Exact matches never surface, and neither do the NOT_FOUND cases, which bounce back to the customer automatically while they are still in the form. What reaches a person is the narrow band where the register is guessing, which is exactly the band where a guess should not be made by software.
Agent Capabilities
7 actionsAddress Validation
2- Validate Address Verifies whether a Czech address exists in the RUIAN state registry and returns the matched place with a confidence score. Tolerates typos and swapped descriptive and orientation numbers, proposing the closest candidate when no exact match exists. Returns MATCH, POSSIBLE, NOT_FOUND, or ERROR. Supply as many fields as you have, with a municipality plus a house number as the practical minimum.
- Get Address By RUIAN ID Retrieves the full detail of one address directly by its RUIAN identifier, bypassing fuzzy matching entirely. Returns municipality, municipality part, street, house numbers, and postal code for that exact address. Feed it the ruianId or placeId returned by Validate Address or List Places.
Address Builder
5- List Regions Returns all higher territorial units of the Czech Republic with their NUTS codes and names. The first step of the builder flow, and the returned regionId is what List Municipalities expects.
- List Municipalities Returns every municipality within a region, each with its RUIAN municipality code and name. The returned municipalityId feeds List Streets, List Places, and List Postal Codes.
- List Streets Returns the streets of a municipality. Entries expose either a street name for a regular street or a municipality part name where there are no named streets, and either value can be passed as the street to List Places.
- List Places Returns every addressable place on a street of a municipality, with descriptive, orientation, and registration numbers, postal code, and RUIAN place identifier. Pass a returned placeId to Get Address By RUIAN ID for the complete record.
- List Postal Codes Resolves the distinct postal codes serving a street within a municipality, derived from the addressable places on that street, and reports how many places were inspected. Used to prefill or cross-check a postal code, since a long street can span more than one.
Frequently Asked Questions
What can FlowRunner do with RUIAN API?
FlowRunner agents can run Validate Address, Get Address By RUIAN ID, and List Regions in RUIAN API, plus 4 more actions.
Does connecting RUIAN API to FlowRunner require OAuth?
No. RUIAN API connects to FlowRunner with an API key, no OAuth flow required.
Can RUIAN API trigger a FlowRunner workflow automatically?
RUIAN API doesn't currently expose triggers in FlowRunner. It connects as an action step inside workflows started by another trigger.
Start building with RUIAN API
$100 in credits. No card required. Connect in minutes.