One tag, the right door.

1. Quickstart

1. In the dashboard, open API keys and create a publishable key. List the sites it may be used on, like https://shop.example. A test key works anywhere, localhost included.
2. Add the script and the element to your form.
3. Read the fields when the form is submitted, or listen for the change event.

<script src="https://js.rightdoor.eu/v1/address.js" async></script>

<form action="/checkout" method="post">
  <rightdoor-address key="rd_pk_live_…" countries="NL,BE"></rightdoor-address>
  <button>Continue</button>
</form>

2. Your own fields, or ours

Our fields. An empty <rightdoor-address> creates labelled fields in your page, in the order shoppers know: NL postcode, number and toevoeging, then street and city; BE postcode, street, number, bus and municipality. They submit with your form:

Your fields. Put your own inputs inside the element and mark them with data-rightdoor. The form adds the lookup, the picker and the messages, and writes the register's values back into your inputs (with input and change events, so React and Vue see them).

<rightdoor-address key="rd_pk_live_…" country="NL" theme="none">
  <input name="zip" data-rightdoor="postcode" autocomplete="shipping postal-code">
  <input name="number" data-rightdoor="house-number">
  <input name="addition" data-rightdoor="addition">
  <input name="street" data-rightdoor="street">
  <input name="city" data-rightdoor="city" autocomplete="shipping address-level2">
  <input type="hidden" name="receipt" data-rightdoor="receipt">
  <div data-rightdoor="slot"></div>  <!-- where the picker and messages go -->
</rightdoor-address>

Both modes keep the inputs in your page itself, not in an iframe or a shadow root, so the browser's saved addresses and password managers fill them as usual.

3. Attributes

4. The result

const form = document.querySelector("rightdoor-address");
form.addEventListener("rightdoor:change", (event) => {
  const { status, complete, address, carrier, receipt } = event.detail;
  // status: valid | corrected | ambiguous | invalid | unverified | incomplete
});
form.getValue(); // the same, any time

The result also has carrier (street, number and addition apart, as PostNL, bpost, DHL and Sendcloud want them), issues with messages in the shopper's language, and blocking: advice, true only for hard format errors. The form itself never stops a submit; you decide what blocks.

5. Trusting it on your server

Anything a browser sends can be changed on the way. Two ways to be sure on your server, without trusting the fields alone:

• Verify the receipt. Every checked address comes with a receipt signed by RightDoor, valid for 24 hours. It costs nothing and needs no API call.
• Or validate again with your secret key and the same sessionId: it then counts as the same verification.

import { createRemoteJWKSet, jwtVerify } from "jose";

const keys = createRemoteJWKSet(new URL("https://api.rightdoor.eu/.well-known/jwks.json"));

// receipt: the rightdoor_receipt field your form received
const { payload } = await jwtVerify(receipt, keys, {
  issuer: "https://api.rightdoor.eu",
  audience: "rd_pk_live_AbCdEf12", // your publishable key without its last part
  algorithms: ["EdDSA"],
});
// Then check that the address you received is the one RightDoor checked:
// payload.address = { countryCode, address1, address2, zip, city }
// payload.status, payload.confidence, payload.sub (the session id)

6. When RightDoor can't answer

If RightDoor doesn't answer within 1.5 seconds, answers with an error, refuses the key or the key reached its daily cap, the fields quietly become an ordinary form and the result is unverified. The shopper is never stuck, and nothing blocks the submit. Check those orders later with the API.

7. Content Security Policy

No unsafe-inline, no unsafe-eval, no frames. The form builds its fields without HTML strings, so it also runs under Trusted Types.

8. Versions

/v1/address.js is always the newest 1.x: fixes reach your page within minutes, and nothing changes for you. Breaking changes only ever come in a new major version, at a new address (/v2/), so you choose when to move.

9. Styling

The default theme is a stylesheet of a few kB, set with CSS variables on the element: --rd-af-accent, --rd-af-text, --rd-af-muted, --rd-af-border, --rd-af-bg, --rd-af-error, --rd-af-radius, --rd-af-font and --rd-af-gap. With theme="none", your own CSS styles everything (the fields have rd-af- classes).

rightdoor-address {
  --rd-af-accent: #0a7c55;
  --rd-af-radius: 6px;
  --rd-af-font: "Inter", sans-serif;
}

10. Keys, limits and billing

• Publishable keys are public by design. A live key only works from the origins you list (https, exact, or https://*.example.com for subdomains), and only for lookups, suggestions and single validations.
• One address is one verification: every lookup, suggestion and the validation of one address entry share a session. At most 50 calls per session.
• A daily cap per key (default 1,000 verifications), with an email at 80% and 100%. At the cap the form falls back to manual entry until midnight UTC.
• Test keys are free on every plan, work from any site including localhost, 100 calls a day.
• The form is included in every plan, the free plan too.

11. Privacy

The form sets no cookies, uses no local storage, and sends no analytics or fingerprints. It talks to api.rightdoor.eu only, and only once the shopper types an address. RightDoor compares the address with the public registers and forgets it: nothing is stored or logged. For your customers' addresses, you are the controller and RightDoor the processor (data processing agreement).