# RightDoor

> Dutch (NL) and Belgian (BE) address lookup and validation against the official open registers: Kadaster BAG for the Netherlands, BeST Address (FPS BOSA, CC BY 4.0) for Belgium. Every answer says what to do next.

RightDoor keeps no submitted addresses: it compares them with the public registers and forgets them. If you send addresses for someone else, you are the controller and RightDoor the processor (data processing agreement: https://www.rightdoor.eu/dpa).

## Connect

- MCP (recommended for agents): https://api.rightdoor.eu/mcp. Streamable HTTP, spec revision 2026-07-28 (2025-era clients also work). Sign in with OAuth 2.1 (the server's protected resource metadata is at https://api.rightdoor.eu/.well-known/oauth-protected-resource/mcp; scope `address:verify`), or send an API key as `Authorization: Bearer rd_live_…`.
- REST: https://api.rightdoor.eu/v1/…, with `Authorization: Bearer <API key>`. Never put a key in a URL. OpenAPI: https://api.rightdoor.eu/openapi.json. Docs: https://api.rightdoor.eu/docs.
- API keys: https://app.rightdoor.eu/keys. TEST keys (rd_test_…) are free and limited to 100 calls a day.

## MCP tools

- verify_address: one address, free-form (`address`) or in parts → status, formatted postal lines, issues, nextStep.
- lookup_address: country, postcode, houseNumber (+ street in BE) → every address at that number, with the additions to choose from.
- suggest_address: country and partial text → up to 10 addresses; then verify the chosen one.
- verify_addresses_batch: up to 100 addresses with your ids → compact results in order.
- list_supported_countries: the countries, their required inputs and register versions (not counted).

## REST endpoints

- POST /v1/validate: { countryCode, address1, address2?, zip, city? } (Shopify shape) → status valid | corrected | ambiguous | invalid, normalized, formatted, issues, carrier, nextStep, meta.
- GET or POST /v1/nl/lookup (postcode, number), /v1/be/lookup (postcode, street, number) → every address at the number, with `additions`.
- GET or POST /v1/autocomplete (country, q, postcode?) → up to 10 addresses while someone types.
- GET or POST /v1/suggest (country, q, postcode?) → up to 10 streets.

## Using the answers

- Follow `nextStep`. valid: use the formatted address. corrected: show the correction and use it if the person agrees. ambiguous: ask them to choose, then check again. invalid: ask them to check the part the issue names.
- `blocking` is advice. Never refuse a real customer on your own.
- Fail open: on a timeout (1.5 s at checkout, 5 s elsewhere), a 5xx or an error, accept the address as given and check it again later.
- Answers carry provenance: the register (`source`), its `datasetVersion` and, for Belgium, the `attribution` to show.

## Issue codes

- FORMAT_INVALID: A part can't be valid as written (usually the postcode). Ask the user to correct the field the issue names.
- MISSING_HOUSE_NUMBER: Ask the user for the house number.
- POSTCODE_NOT_FOUND: The postcode doesn't exist in the register. Ask the user to check it.
- HOUSE_NUMBER_NOT_FOUND: The number isn't in the register at this postcode. Ask the user to check it; a new build may not be listed yet, so let them confirm.
- SUFFIX_NOT_FOUND: The letter or addition doesn't exist at this number. Offer the additions that do (lookup_address).
- UNIT_REQUIRED: This number has several units (toevoeging or bus). Ask the user which one.
- UNIT_NOT_FOUND: That unit doesn't exist at this number. Offer the ones that do (lookup_address).
- STREET_MISMATCH: The street didn't match; the answer carries the register's street. Show it to the user and use it if they agree.
- CITY_MISMATCH: The city didn't match; the answer carries the register's city. Use the corrected one.
- ADDRESS_PLANNED: A new build: the address is valid and deliverable soon or already. Accept it.
- CARRIER_LINE_TOO_LONG: A line is longer than the carrier allows; the issue suggests a shorter form. Never block on it.
- PO_BOX_NOT_ALLOWED: A PO box where a street address is needed. Ask for a street address.
- UNSUPPORTED_COUNTRY: RightDoor checks only the Netherlands and Belgium. Accept the address as given.
- COUNTRY_AMBIGUOUS: The address could be Dutch or Belgian. Ask the user which country, then check again with `country`.
- UNVERIFIED_CONFIRMED_BY_CUSTOMER: The customer confirmed an address the register doesn't know. Accept it and flag it for review.

## Limits

- Agents: 60 tool calls a minute (bursts of 20; a batch counts its items) and 10,000 a day per account, on top of the plan's limits.
- The same request more than 5 times in a minute is refused: stop retrying and ask the person.
- 429 RATE_LIMITED: wait for Retry-After. 429 QUOTA_EXCEEDED: the monthly verifications are used up; the answer has an upgrade link.
- Fields up to 200 characters, free-form addresses up to 500, request bodies up to 64 KB.