Real-Estate Registry Developer Portal
Where licensed companies and government bodies get permission, and a key, so their own software can pull property records from a national real-estate regulator. Twenty-five services in one catalogue, Arabic-first, with identity from the national ID service and no password anywhere in it.
- Role
- Lead UI/UX designer & researcher
- Team
- Two: design and portal delivery
- Timeline
- Feb – Dec 2024
- Status
- Live
In the proposal the portal was one line in a scope of eleven, written as build the developer portal. The things that decide whether a developer portal works sat in the other ten lines, or outside the contract.
Five things sat with other people. The national ID service owned identity. The commercial register decided who was entitled to what. The authority supplied the logo, the palette and the hero artwork, then changed all three partway through. Their cybersecurity team held security sign-off. Their technical teams wrote the API specifications, and eleven of the twenty-five existed when design started. My job was to keep one route running through all of it. A developer who wants a key and a working call never has to think about which system they are in.
The interactive prototype and information architecture, the onboarding and entitlement flows, the catalogue and technical documentation experience, the application and credential screens, the system email templates, and the Arabic-first interface with its bilingual rules, all carried through a mid-project change of corporate identity.
Two of us worked on the portal. I did design and research, and the portal delivery lead did the build. With two people and twenty-five services, every decision had to be made once and then reused across the catalogue.
Everything on this page is a recreation. The client is not named; their branding, real identifiers, customer data and internal documents are replaced with fictional equivalents built for this portfolio. Figures appear only where they describe my own process, and anything commercially sensitive is left out.
This one carries a second constraint: it is a government platform. The authority’s name and emblem are removed, the services shown are invented, and the security findings raised during technical review are deliberately not described here at all.
How this was tested
This is the weakest part of the project. There was no lab testing with strangers. The method was an end-to-end interactive prototype, reviewed weekly with the authority's project and technical leads. There were one or two rounds with expert users, mostly the client's own engineers.
None of that measures whether anyone can get a key.
It catches wording that is wrong in a way only an insider would notice. It catches missing states, such as pending, blocked and expired. It catches entitlement errors, where someone can see a service they have no right to call. All of those have a correct answer that somebody in the room already knows.
It cannot tell me whether a developer who has never dealt with this authority can register, find the right service and make a call without asking anyone. Experts work around a bad structure without noticing they have done it, and the client’s own engineers already know what everything is called.
Two audiences, one way in
The portal serves two populations that look similar and behave differently. A commercial partner is a company that must prove it exists before it can be granted anything. A government entity already has the right to the data and is only there for the credentials and the documentation.
Building two portals would have doubled the number of screens and split the catalogue in two. There is one route. It splits where entitlement is decided and comes back together straight afterwards.
Registration without a password
Nobody sets a password here. A person authenticates with their national identity, and a company proves itself with the registry code every registered organisation already has. Entering that code looks up the official record and fills in the legal entity name.
That removes a common source of bad data in partner onboarding. Somebody types their own company’s registered name from memory into a field that has to match a government register exactly.
The applicant enters one code and the legal name comes back filled in. All they have to do is confirm it, and the record that reaches the reviewer already matches the register.
The relabel sounds cosmetic. Every other field on that form is drawn from an official register, so people read “phone number” as one more field that has to match a record somewhere. “Contact number” tells them it is simply how we reach them.
A sign-in can fail because the account was never registered, or because it is registered and not yet activated. Those are two different problems with two different next steps, so each one gets its own screen.
A catalogue grouped by sector and access
Services are grouped by the sector they serve and by who may call them, not presented as a flat list of endpoints. Permission is the first thing a developer needs. A broker-licence lookup is no use to a bank, and finding that out after registering wastes their time.
It also solved a delivery problem. Fewer than half the specifications existed when design started. A catalogue built around categories and access states could be complete on day one, with the services added underneath as their specifications arrived. It never looked half-built.
Right to left, with exceptions
The portal is Arabic-first, and a large part of what it displays is not Arabic. Endpoints, parameter names, HTTP verbs, status codes, timestamps, identifiers and sample data are literal strings that a developer copies into code. Mirroring them stops them working.
So direction became a rule about content rather than a setting on the page. Anything a developer reads runs right to left; anything a developer copies runs left to right, set in mono, and is never reflowed. On the service page the technical file is a left-to-right block inside a right-to-left page. It is the better arrangement because it does not match the page around it.
Prose, labels and navigation run right to left. Endpoints, parameter names, HTTP verbs, status codes, timestamps and identifiers do not. A developer copies those literally, and mirroring them breaks them.
Dashed: the parts of the line that must stay left-to-right.Key decisions
Two of these are about showing something that could have been hidden. The third I argued for, got agreement on in review, and still did not get.
The environment is always on screen
A persistent badge in the header says which environment the session is pointed at, in every view, for authenticated and unauthenticated visitors alike. Switching is one control and does not require signing in again. The cost of guessing wrong here is a live call against real property records.
Credentials are not metadata
The application page separates what the app is from what it can do. Name, description and dates on one side. The key, the secret, their status and the services each is attached to on the other. The platform issues credentials at creation, so both timestamps read identically and look like a bug. We kept them visible anyway: a developer debugging an expired key needs to know when it was issued.
One name field
Saudi names do not split cleanly into first and last, and forcing them produces records that are wrong in a way nobody can correct later. This was agreed in a design review and did not make it into the built registration form, which still asks for two. I raised it in a review thread and never wrote it into the requirements document.
One application, room for more
A standard partner account holds one active application. That is a policy decision, and it changes the screen completely. With a single application there is no list, no empty state and no naming problem. The page goes straight to the credentials, their status and what they are attached to.
The layout still had to survive the exception. Larger partners are granted more. The same page has to hold several applications without becoming a different design, so the single-application view is the one-item case of a list.
Three rounds to meet the standard
This portal was redesigned three times. The first look was mine. The second was my attempt at a standard nobody had given me yet, and the third was that standard, handed over and applied as given.
The first version had a deep teal palette on a soft off-white ground, a gradient hero card, service cards on their own shadows and pill-shaped questions. The part I still like best is the charcoal band. It lifted the technical documentation out of the page and marked it as a different kind of reading.
Then the authority changed its corporate identity, and the colour had to follow. The client took that as meeting compliance as well. It did not.
The second round went further and reset the lettering across the portal. That was not enough either.
Then the client sent the government's mandated design system. Primary colour, body text, buttons, footer and logo treatment all moved to it, and the portal joined the standard family: white ground, one institutional green, square cards, bordered rows, no dark zone anywhere. The name moved at the same time, from an integration portal to a developer portal, which is the one change I would have asked for myself.
What the swap cost
The colour move itself was cheap, because colour and type were already tokens mapped straight through to CSS variables: a new palette and a contrast re-check, done in days.
What cost us was everything that was not colour. The charcoal documentation band had no equivalent in the standard, so it went white. The technical file now looks like the marketing copy above it. Telling them apart was the one thing that band was for. Every screen that had been approved on appearance also had to go round again, because component variants were not tokenised the way colour was.
Designing on someone else’s calendar
Most of the risk on this project was not in the design. It sat in a chain of dependencies that other people owned. The useful skill was finding work that could be finished before their inputs arrived.
The deliverable included training and documents
The engagement ends with the authority running this themselves. It includes a series of recorded workshops, a user guide and an administrator guide, and the stated goal is to train the client’s team to work without us.
That widened what design was responsible for. The administration side is part of the deliverable, and so is every piece of system email the portal sends. I designed the transactional templates as options in the same file as the portal and the client chose between them. Those messages are the only part of the product that reaches a developer when they are not looking at it.
What I’d do differently
Two things went wrong. The research one matters more.
The single name field was agreed in a walkthrough and never written down anywhere the build would read. A decision made in conversation with the client has to reach the requirements document that same week.
Reviewing with the client’s own experts is quick, but it is not user research. They know the vocabulary, the entitlement model and where everything is. Three outside developers, timed once from landing page to first successful call, would have cost two days and tested what the walkthroughs could not.