Diagnostic Assessment of a Tier-1 Bank's Developer Portal

Developer portals are often built with care, rigor, and deep technical expertise. When we review them, we always hope to see investment in high-quality documentation, well-designed APIs, and thoughtful developer experiences.

And yet, even with strong engineering foundations, many developer portals struggle to gain traction, deals are lost or stalling.

In many cases, this has little to do with the quality of the code or the capabilities of the assets. Instead, the challenge lies in how effectively the portal communicates business value and compliance beyond a purely technical audience.

Because a developer portal sits in an intermediary, awkward space:

- portals were originally built only for engineering,

- but it is now a primary information source consumed (directly or indirectly) by evaluating buyers

- and in such an evaluation phase especially, the portal directly signals the maturity and seriousness of the integrations on offer.

A developer portal isn’t only an engineering and developer experience artifact; it is a commercial surface, a trust signal, and often the first step in a B2B revenue motion.

Through our work at Pronovix, as well the Developer Portal Awards, we have observed a set of common and often unintentional oversights that introduce friction into buyers' evaluations, slow commercial momentum, and quietly erode trust. We have been trusted with the methodical betterment of our clients' portals for many years. At enterprise level portals serve so many needs that a dozen of best practices is of little use in a complex B2B situation. So we've built a diagnostic framework based on the observable practices, so that we can methodically surface where your current practices and available content objects help (or hinder) specific technical and commercial outcomes. 

How do I get a better developer portal?

If you run a quick search on "What's a better developer portal?", then you will get a too short, or too long washing list of best practices, and a few hints on where to start. Guaranteed it will refer to a known handful of developer portals generally circulated as "best" for many years now, with reason of course; but which of these examples would directly apply to your budget, expertise available in-house, and the domain-specific expectations in your market? 

Clear, comprehensive, intuitive, frictionless

As so much has been written about developer experience, much of which you will find among the Pronovix articles, you are likely to get that aspect covered well in a general search; other areas not so much or very opinionated without remark. When you drill down to the qualifiers in the details, you will get words such as "clear, comprehensive, intuitive, frictionless, and so forth".  The irony of professionalism is that the more you know about your own APIs, the less you are able to see what is intuitive or frictionless to a user outside your API team. We see this over and over in our consulting experience: the outsider professional's perspective and critique is irreplaceable. 

External objective validation and benchmark

What my work with the Developer Portal Awards jurors have taught me, is that any portal team really needs external validation, independent benchmarking, and an accelerator, a catalyst. Most teams are doing the right things, but they need an objective assistance in prioritization that prevents wasted effort.

Instead of asking, what are the best practices so "we can just copy them too," I suggest it is more valuable starting point to ask, 'What does our developer portal currently provide and signal, and to whom?'

We see the role of a snapshot assessment first and foremost to help you champion portal maturity to leadership, and to identify which are the highest-leverage gaps that are hard to see from inside.  

Of course, at a tactical execution level, it is specific practices that need to be put into place.

If you've been following the work and publications of Pronovix, you probably know that we have been working with a maturity model for a long time now. In the beginning, it was a thinking and planning framework, a mental model only, meanwhile in the past year we decided to list and catalogue what we recognise as practices in the domain of developer portals; then organized these domain-specific practices into a system that allows a quick diagnosis. We want to get as close as possible to snapshot what is going on a portal, and depict a specific situation, identify gaps and come up with the next priority steps for improvement.

Back to the Table of Contents

A focus area maturity model with domain-specific practices

What we developed is in research terms called a focus area maturity model. 

Now, if you consider developer portals not just static publishing tools, but as socio-technical systems, then what we are analyzing is a nonlinear, time-varying system, that is complex, sensitive to initial conditions, it shows butterfly effects and bifurcations.

To have an analysis of gradients, we will use linear solvers of course, and we are taking a snapshot in time. Most maturity models you find with an internet search will go for showing on what level of maturity something is, usually up to like 5-6 levels. What we want is more of a continuum, the overview has its uses but the actionable insights come from the details. What we want is a clear, iterative path to improve maturity for a specific purpose, in well-defined areas. 

Hybrid User Experience

Operational Excellence and Business Alignment are the engines driving a portal's success, they are often internal and invisible. In a digital ecosystem, these internal forces are only valuable if they produce tangible results for the technical and business users.

We consider Hybrid User Experience, the observable practices with verifiable external evidence on the developer portal, as the imprints of the underlying business maturity. This is our lens for a snapshot assessment, looking into the quality of everything you expose to consumers.

Search engines, semantic breadcrumbs

Ironically, in some functional areas which were until recently considered explored to their full potential, is where adjustments need to be rapidly implemented, for two reasons: 

- because portals have to serve hybrid persona's, and

- the semantic breadcrumbs are crucial to be present to not get lost between your own domain model and that of the AI search engines.

To help transition your portal from a "technical library" to a "commercial offer," we apply two more critical filters in the assessment. These areas determine if the portal is capable of exposing solutions to human- and AI agents alike.

Use cases and business solutions

One is the Business Readiness layer, where we evaluate solution practices, for example if the portal exposes "Use Cases" and "Solutions" rather than just raw APIs. This involves checking for a "Solution Layer" that sits above the technical documentation. Many of these aspects in their proto-form are already in the user experience practice bundle, but we are currently working on spotlighting it because this is where most portals have a quality collapse. 

AI visibility, agent accessibility

Strategically, content gating serves as a business filter to prioritize high-value enterprise leads over smaller clients or to protect highly regulated, sensitive logic. While it helps in lead generation and partner-specific targeting, excessive gating is a barrier to entry, often counterproductive to broad adoption and market visibility. 

The need for  AI Visibility & Agent Accessibility is another area that is already part of the user experience as we evaluate it,  but we are going to spotlight these practices in the imminent future. It is a critical business risk if search engines and agents are not finding your offerings. If the content of your portal isn't adjusted for Search- and Answer Engines, the solution cannot be recommended by AI intermediaries to those users who haven't yet set foot on your portal.

Back to the Table of Contents

Maturity assessment of a Tier-1 Bank Developer Portal 

Let us take you on the journey of the assessment of a Tier-1 Bank's developer portal and explain what is happening in the background, and how we can help take that next step towards more potential, using the maturity model framework.

The assessment is that of the external developer portal of a large, globally operating banking institution with a presence across multiple regions and markets. This organization supports a broad range of regulated financial services and enables third-party developers and partners to integrate with its platforms through secure APIs. 
As such, the external developer portal plays a critical role in partner onboarding, API discovery, documentation, and access management, while operating under the strict security, compliance, and reliability expectations typical of global financial institutions.

Beyond PSD2: it is time for an update

The developer portal is an excellent example of one built with a lot of care, finesse and expertise, of course historically also motivated by the payments services EU directives, however it is time for an update in its potential. 

Through three steps we convert qualitative observations into actionable data. 

1. Map out a user’s high-level goals through 6 focus areas 

Discovery, decision-making, onboarding, go live, maintenance & troubleshooting, and community. These are the stages of a typical user journey. 

2. Analyze

We defined two dozen enablers that address the user’s high-level goals, and we measure more than 130 practices or activities that make those enablers work. For example, an enabler could be “visual harmony”, in which we have practices such as Consistent look and feel and Content-first design. The scoring system allows to get a high level overview, but also to then drill down again. 

3. Benchmark

Additionally we can do a benchmarking step, in which the portal’s current implementation is for example measured against a best-in-class standard or competitors.

SWOT: the assessment report

In our example, based on these steps, we conducted a snapshot assessment of the developer portal, and created very detailed a report based on the findings. Let's see some of the findings.

First is a birds-eye view of the six focus areas of user experience, and the aggregate maturity scoring for the publicly accessible aspects of this example developer portal. What such a rendering brings into focus are  the shortcomings in some areas, and the relative high performance in others. It is more constructive to go deeper in the analysis, to the enabler level: 

Strong technical foundations, weaker commercial and user-trust functions 

The enabler scores point to strong technical foundations but weaker commercial and user-trust functions.

In our example, onboarding is well supported in that API access and testing is great, and the practices enabling go-live are also in place although further improvement is needed. However, the onboarding experience could be much better, there are key gaps detected. 

The portal excels in initial Discovery and Go Live essentials, however, there are other business-driving and confidence-building enablers that are only in the foundational stage of maturity, at least in the non-logged in journey, which can pose major obstacles to evaluation.

Some of the core ecosystem enablers are lagging:

• Search practices could be much better on the site,
• and it is an opportunity to work on Community & Engagement enablers.
• There are several Marketing & Business Development practices, that could be brought in. 
   

Actionable steps on a prioritized roadmap to solve strategic friction points 

Aggregate results alone are not enough for task-level advice. We get you to actionable steps that can be put on a roadmap and executed by one team or a team of teams. 

Drilling down to the specific practices in each enabling area, the "Stage 3" practices are the tactical levers required to solve the strategic friction points. We suggest a practice-level roadmap that focuses on resolving zero-score practices that create friction and block commercial engagement. This roadmap is at a good level of detail to discuss prioritization, and set tasks for immediate execution.

Focus your resources on the changes that actually move discovery and adoption

In the case of the example bank, Priority 1  addresses the missing commercial transparency and the broken developer workflow tool (Search). Resolving these issues is necessary for business conversion and basic site functionality.

Priority 2 addresses deficiencies that break user trust during live integration (Maintenance & Troubleshooting) and prevent long-term commitment (Lifecycle).

Furthermore we also suggest specific practices to expand the audience and foster community resilience (Priority 3). Building advanced tools, namely multi-language and downloadable SDKs for developers is also a route for betterment.

Back to the Table of Contents

It is a sales enablement failure

Do these practices resolve the business problems? Business problems are often systemic issues, and can become a hyperobject for insiders staring themselves blind - this is where an external catalyst can help address the crux.

Lack of a clear business model, no publicly available pricing nor solution alternatives: this is not a "content" failure; it is a sales enablement failure. By implementing these specific practices, the organization takes a good step in resolving the evaluation and procurement blockage that often stalls integrations.

Resolving operational opacity, with a Status Page, Changelog, and Roadmap, does not just "improve Developer eXperience"; it reduces support costs by deflecting them in the first place, and on the long run also mitigates liability (like think of audit trails).

In our example I showed the suggestions for an Active Site-Wide Search and Context-Aware Search. Removing artificial, legacy walls in the integrations documentation, helps to create a unified interface to the organization. Such a unified interface is crucial so that your prospects don't get tripped up by the organization's internal complexities.
 

Discovery- and commercial gaps are a risk

Beyond excerpts from an example assessment, what are some typical high level issues that we see overall?  

The following two gaps go beyond what you can solve with cosmetics, these are issues that are bigger than one of your talented employees could tackle alone, and yet such change would benefit everyone. 

Banking developer portals: quality collapse in decision-making enablers

In discovery areas, banking developer portals generally score higher, indicating those aspects are very good. However, information important for buyer decision-making is often hidden behind a login wall or may not exist even after logging in. This is a very typical current state in banking developer portals. There are good historical reasons for walling in such information, but it is a good time now to reconsider.

Potential partners abandon the integration during the "exploration" phase because the complexity barrier is too high, leading to wasted business development efforts. 

One challenge teams often have is how to go beyond exposing APIs to (mainly) developers, and expose services as a recognisable use-case to for example a buyer team in the exploration and evaluation phase, and demonstrate business-fit and value. Our assessments typically show that business discovery is not scoring too high: the core APIs are discoverable, but the overall information structure is failing to guide the various users.

"Assume nothing, explain everything."

With hybrid users emerging (for example an agent being your direct visitor instead of the human persona, or a business analyst using a co-pilot to aid them in a lightweight fit-check), we cannot emphasise enough that an intuitive, machine accessible and clear portal with a well-defined documentation structure, clear taxonomy and domain model, with exhaustive non-assuming documentation matters more than ever. Quoting the words of an awards juror, "Assume nothing, explain everything."

An old but gold truth of UX is that people are different kinds of learners. We have our own preferred ways of exploring and processing new information. You need to balance just-in-time disclosure with the full freedom of choice. 

Align the developer portal goals with broader business goals

It is a broad challenge to align portal goals with broader business goals.

To shift the portal from merely exposing data integrations to actively driving partner sales and cross-selling, technical endpoint documentation however spotless is not sufficient. This should not be viewed as originally a documentation problem, but as a sales enablement problem, which however can be fundamentally supported on the content side. 

Relieve pre-sales engineering, support the buyer directly with solutions

Almost all banking portals show a lack in supporting the buyer persona's decision-making process: 
Partners often still lack the necessary business information (such as value propositions, clear pricing, comparisons, ...) needed to commit to a solution without lengthy conversations and hand-holding from pre-sales engineering.

Internal sales and account managers also often cannot find their way on the portal, albeit the portal should help them sell solutions.
 

Back to the Table of Contents

Business-ready, AI-ready: Solution Portals

Figuring out how to take care of all that is involved, is hard. Pronovix is at your service, and we are a formidable help.

At least in the beginning, an outside-in perspective might be the crux, in making sure to empathise with all targeted users and with all involved internal teams, to discover hidden possibilities and use existing knowledge. Also to stand out against direct and indirect competitors.

This a strength that Pronovix as your partner can play on, we bring with us a Full Solution Discovery Framework and professional services to figure out your portal's real user needs through stakeholder- and client interviews, professional research, interactive prototyping, testing and iterating.

Furthermore, to get your portal ready for the next growth level, we focus on information architecture and adjusted workflows that support discovery and translate or generate user needs into solutions, to answer your “what’s next” question.

All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.

Back to the Top