# Top 25 API onboarding experiences Effective technical onboarding gives new users the tools and knowledge to be successful. In this post, we’ll look at 25 examples of resources that were developed to onboard new users to public APIs. These resources can be reused throughout the developer’s lifecycle as they become aware of new features and expand to new use cases, and they can also be used for onboarding new team members who are learning about your technology. ## Prioritizing technical onboarding If you’re an API producer who wants to do a better job of onboarding your consumers, how important is it when there are other priorities competing for your attention? When it comes to API onboarding, it’s important to make sure it’s seamless, easy, and efficient. Here are some reasons to invest in a smooth technical onboarding experience: - **Faster time to value**: A smoother onboarding experience gives developers a [faster time to value](https://blog.postman.com/the-most-important-api-metric-is-time-to-first-call/) that results in real downstream impacts, like higher conversion and retention rates for your API. - **Have a market differentiator**: There are many [reasons why developers choose to consume APIs](https://www.postman.com/state-of-api/api-first-strategies/#api-first-strategies), such as quality, convenience, and usability. Some of these criteria are table stakes that are expected from every API producer, but having an API that is easy to get started with is still a good way to stand out from the crowd. - **Increase productivity**: Onboarding is not just for new users. Existing users rely on the same tools and resources to expand their knowledge for deeper integration and advanced use cases. Additionally, the onboarding resources you develop for public APIs are equally beneficial for teammates and collaborators who are consuming and integrating with your private and partner APIs. In the [2022 Postman State of the API](https://www.postman.com/state-of-api/) survey, respondents cited [faster development times](https://www.postman.com/state-of-api/api-first-strategies/#api-first-strategies) as a key factor in an organization's decision to consume an API: ![50% of respondents said “Speeding up development timelines” is a key factor in deciding to consume an API](https://blog.postman.com/wp-content/uploads/2022/10/1-1000x455.png) In the same survey, documentation and usability were both reported as being top factors in deciding to integrate with an API: ![Documentation” and “Usability” are factors when deciding to integrate with an API](https://blog.postman.com/wp-content/uploads/2022/10/2-1000x453.png) Even though other factors—like performance, security, and reliability—are ranked as more important when deciding to integrate with an API, they typically don’t come under full scrutiny until much later in the developer journey. If you don’t address friction early in the onboarding process, your pool of developers will dwindle before you can impress them with these other factors. ![Address pain points early in the developer journey to fix the leaks in your acquisition funnel](https://blog.postman.com/wp-content/uploads/2022/10/3-1000x460.png)Address pain points early in the developer journey to fix the leaks in your acquisition funnel It’s no longer enough to simply provide an API that does the job. It costs time and money for developers to learn new technologies. Investing in technical onboarding addresses some of the most pressing leaks in your acquisition funnel or flywheel throughout the developer journey. ## Insight into the developer experience API producers, like your consumers, have a limited amount of time and resources. How do you know where to start? Knowing the common pain points developers encounter with your APIs helps you prioritize what needs to be done. Here are some quantitative and qualitative ways to gain insight into the developer experience: - **Measure time to first call (TTFC)**: Pull the logs or run an experiment to see [how long it takes a developer to make their first successful API call](https://blog.postman.com/the-most-important-api-metric-is-time-to-first-call/). On average, is it a few minutes, a few hours, or a few days? If the answer is significantly more than you expected, start here first. - **Exposure hours**: As the API provider, you unfortunately have the “[curse of knowledge](https://en.wikipedia.org/wiki/Curse_of_knowledge),” which is the cognitive bias that makes it more difficult to communicate about a subject that you’re an expert in. Spend time with, or watch, developers as they learn how to use your APIs. You can also ask new team members to document their feedback with a fresh perspective so you can identify the gaps in onboarding. - **Optimize search**: Perform a search audit within your developer portal, in addition to broader search engines, to ensure you’re optimizing for expected keywords. You should also take a look at the most popular pages by impressions in your docs and search terms that yield zero results. - **Ask them**: Explicitly asking developers for their feedback can seem too obvious and daunting, but it yields immediate insights. This can involve structured usability testing with specific prompts for feedback. It can be accomplished with a brief survey sent to new and existing users, or it can be as quick as a few open-ended conversations with collaboration partners. Once you understand the biggest pain points for your developers, you can prioritize what to do next. ## Principles for more effective technical onboarding Let’s look at shining examples of API onboarding, grouped by the following principles, for more effective technical onboarding. 1. [Provide wayfinding](#1-provide-wayfinding) 2. [Address early blockers](#2-address-early-blockers) 3. [Show advanced usage](#3-show-advanced-usage) 4. [Enable troubleshooting](#4-enable-troubleshooting) 5. [Don't forget about discovery](#5-dont-forget-about-discovery) 6. [Delight your users](#6-delight-your-users) ### 1. Provide wayfinding Do not underestimate the importance of this one. The manner in which new information is organized and presented to new users is crucial. Some API producers organize resources by Postman [teams](https://learning.postman.com/docs/collaborating-in-postman/working-with-your-team/collaboration-overview/), [workspaces](https://blog.postman.com/solving-problems-together-with-postman-workspaces/), [collections](https://www.postman.com/collection/), and folders to more clearly communicate information architecture to the user. #### Navigation New users may not be familiar with industry-specific terminology, the branded names of products and services, or your company’s history of mergers and acquisitions. Information that is clearly organized reduces cognitive load for new developers. - [Cisco](https://www.postman.com/ciscodevnet?tab=workspaces) is a company with a history of mergers and acquisitions that resulted in a breadth of technology under one roof. Their team profile shows workspaces organized by business, with each business managing a workspace teeming with their own collections. This level of abstraction allows users to focus only on the technology they’re exploring. ![Cisco organizes workspaces by business unit](https://blog.postman.com/wp-content/uploads/2022/10/4-1000x626.png)Cisco organizes workspaces by business unit- Oracle is another company with independently managed businesses. If you’re looking for [Oracle Hospitality APIs](https://www.postman.com/hospitalityapis?tab=workspaces), that’s a far jump from [Oracle Cloud APIs](https://www.postman.com/oracledevs?tab=workspaces). Oracle is organized by team so each team can manage their workspaces independently. ![Oracle maintains separate teams to manage onboarding independently](https://blog.postman.com/wp-content/uploads/2022/10/5-1000x626.png)Oracle maintains separate teams to manage onboarding independently- [LinkedIn](https://www.postman.com/linkedin-developer-apis?tab=workspaces) has more public APIs than you might expect. On their team profile page, you can browse workspaces organized by departments at LinkedIn. Each department publishes collections to their own workspace, making it easier for developers looking for a specific API. ![Departments at LinkedIn each maintain their own workspace](https://blog.postman.com/wp-content/uploads/2022/10/6-1000x626.png)Departments at LinkedIn each maintain their own workspace#### Get started - [ArcGIS](https://www.postman.com/arcgis-developer/workspace/arcgis-location-services/overview) provides a guided tour of getting started with their APIs thorough documentation in the workspace. The collections are numerically listed to recommend an explicit order of operations. ![ArcGIS workspace documentation includes instructions to get started](https://blog.postman.com/wp-content/uploads/2022/10/7-1000x617.png)ArcGIS workspace documentation includes instructions to get started- [Infobip](https://www.postman.com/infobip/workspace/infobip/overview) collections are organized in their public workspace by service, and each collection contains a prominent **Get Started** folder that directs the user’s attention to their first API calls. ![Infobip collections include Getting Started folders](https://blog.postman.com/wp-content/uploads/2022/10/8-1000x617.png)Infobip collections include Getting Started folders- [Mercedes-Benz](https://www.postman.com/mbdevelopers/workspace/mercedes-benz/overview) collections are also organized in their public workspace by service, with workspace documentation directing users to “START HERE,” along with links to pre-requisites. ![Mercedes-Benz collections are grouped by service](https://blog.postman.com/wp-content/uploads/2022/10/9-1000x626.png)Mercedes-Benz collections are grouped by service#### By experience level - [EasyPost](https://www.postman.com/easypost-api/workspace/easypost-api/overview) maintains one primary collection with the top-level folders divided into **Basics**, **Advanced**, and **Account Management**, so users can self-select into experience level and role. The nested folders are then named by industry concepts. ![EasyPost organizes their collection with folders for experience level and role](https://blog.postman.com/wp-content/uploads/2022/10/10-1000x626.png)EasyPost organizes their collection with folders for experience level and role#### By industry concepts - [Lob](https://www.postman.com/lobteam/workspace/lob-public-workspace/overview) is another workspace that relies on one primary collection that contains industry concepts, which makes it easier for new users who are unfamiliar with terminology. ![Lob organizes folders by industry concept](https://blog.postman.com/wp-content/uploads/2022/10/11-1000x626.png)Lob organizes folders by industry concept Even though proper organization and naming seems like a no-brainer, sometimes it’s tough for API producers to explain things effectively to new users, which is partially due to the “[curse of knowledge](https://en.wikipedia.org/wiki/Curse_of_knowledge).” The bias can be countered by following the recommendations described earlier for gaining insight into the developer experience. ### 2. Address early blockers At the beginning, developers can give up because they’re stuck on authorization, or they don’t have the data or other pre-requisites in place to fully experience the API and understand the value it offers. Identifying these points of friction and easing the transition directly contributes to a faster time to first call and higher conversion rates. - [Amadeus](https://www.postman.com/amadeus4dev/workspace/098a1401-bc56-425e-8716-6f83fd3813d6/overview) has a folder called “Authorization,” which contains two API calls to programmatically set authorization tokens as Postman environment variables that can then be used throughout every request in the collection. ![Amadeus collection sets authorization token in an environment to re-use throughout the collection](https://blog.postman.com/wp-content/uploads/2022/10/12-1000x456.png)Amadeus collection sets authorization token in an environment to re-use throughout the collection- [Twitter](https://www.postman.com/twitter/workspace/twitter-s-public-workspace/overview) has a pre-request script that runs prior to every request in their collection to sign and generate a token according to their specific authorization method. ![Twitter uses a pre-request script to generate authorization tokens for every request](https://blog.postman.com/wp-content/uploads/2022/10/13-1000x598.png)Twitter uses a pre-request script to generate authorization tokens for every request- [Belvo](https://www.postman.com/belvo-api-team/workspace/belvo-api-workspace/overview) provides collections that contain the API calls required for different methods of authorization. Developers can step through each API call and see the scripts that set variables to then be reused in subsequent calls. ![Belvo provides collections to describe different authorization methods](https://blog.postman.com/wp-content/uploads/2022/10/14-1000x643.png)Belvo provides collections to describe different authorization methods- [Dwolla](https://www.postman.com/dwolladev/workspace/d0bc0b47-99a4-41cc-86f6-dfbca7ad22de/overview) provides a sandbox collection and environment. Providing example data and a playground for experimentation can help developers learn more quickly. This is especially true when consumers are dealing with sensitive information or don’t want to incur costs while still learning what the API offers. ![Dwolla sandbox provides sample data and a safe environment for learning](https://blog.postman.com/wp-content/uploads/2022/10/15-1000x643.png)Dwolla sandbox provides sample data and a safe environment for learning- [Withings](https://www.postman.com/withings/workspace/8d11a6a0-14c8-4586-9950-d9abc3579753/overview) provides two environments for developers to toggle between cloud environments. They include secret variable types to obscure sensitive information and placeholder text for variables intended to be filled automatically by scripts that run after an API call. ![Withings provides scripts to automatically populate values in a Postman environment](https://blog.postman.com/wp-content/uploads/2022/10/16-1000x643.png)Withings provides scripts to automatically populate values in a Postman environment### 3. Show advanced usage Successfully making a first API call gives developers hope, and they can immediately wonder what else is possible. Outlining next steps to complete after their first call shows them the possibilities when they are hopefully most receptive, even if they’re not ready to pursue them right away. - [New Relic](https://www.postman.com/new-relic/workspace/5207d7b4-814a-4107-a47e-0bd4d78bc8f6/overview) provides a collection that is filled with examples of GraphQL queries. They also include their GraphQL schema in the workspace, so if you’re not using their pre-formatted queries, you can enable auto-complete to write your own queries. ![New Relic provides examples of structured GraphQL queries along with the GraphQL schema](https://blog.postman.com/wp-content/uploads/2022/10/17-1000x643.png)New Relic provides examples of structured GraphQL queries along with the GraphQL schema- [Snowflake](https://www.postman.com/snowflake/workspace/snowflake-public-workspace/overview) provides examples of requests and responses. If you’re not used to working with SQL databases, the examples cover various scenarios and demonstrate the structures of the request and response bodies. ![Snowflake provides examples of requests and responses working with databases](https://blog.postman.com/wp-content/uploads/2022/10/18-1000x643.png)Snowflake provides examples of requests and responses working with databases- [PingOne](https://www.postman.com/ping-identity/workspace/pingone/overview) highlights use cases, outlining the specific sequence of API calls required to complete the task. Developers can step through each API call to better understand what’s happening at the API level, before choosing to integrate into their own applications with SDKs or APIs. ![PingOne outlines API workflows for advanced use cases](https://blog.postman.com/wp-content/uploads/2022/10/19-1000x643.png)PingOne outlines API workflows for advanced use cases- [UiPath](https://www.postman.com/uipath/workspace/968a55ba-7e20-42fd-aa2c-b424aeaf5ba2/overview) is another workspace filled with use cases that outline various API workflows for automation, which are supported by thorough documentation in the folder descriptions. ![UiPath outlines API workflows for automation use cases](https://blog.postman.com/wp-content/uploads/2022/10/20-1000x643.png)UiPath outlines API workflows for automation use cases- [Dropbox](https://www.postman.com/dropbox-api/workspace/07d9b250-92eb-480d-82e2-8312893e0dfc/overview) provides an entire collection for team administrators, in addition to the standard API reference. The Dropbox Team Admin Workflows collection includes common admin tasks that allow potentially non-technical users to execute and walk through different API workflows. ![Dropbox has API workflows for admin roles](https://blog.postman.com/wp-content/uploads/2022/10/21-1000x699.png)Dropbox has API workflows for admin roles- [Mist Systems](https://www.postman.com/juniper-mist/workspace/23332ab8-b103-4c6c-9583-175e751ff385/overview) includes a collection to automate deployment and configuration of networks. Developers can execute these API workflows from the Collection Runner on demand, or they can integrate this functionality into their own applications. ![Mist Systems demonstrates advanced automation scenarios for deployment and configuration](https://blog.postman.com/wp-content/uploads/2022/10/22-1000x699.png)Mist Systems demonstrates advanced automation scenarios for deployment and configuration### 4. Enable troubleshooting Even in the best case scenarios, troubleshooting is part of the job for any developer. API producers have control over their [API design](https://www.postman.com/api-platform/api-design/) and can directly control their API’s structure, response data, and response codes to make working with their APIs more predictable and intuitive. However, more can be done during onboarding to help developers while troubleshooting. - [Microsoft](https://www.postman.com/microsoftgraph/workspace/microsoft-graph/overview) adds log statements in their scripts to validate permissions and authorization. This key piece of feedback is modest, but it provides visibility during authorization, which is one of the first challenges developers face when engaging with a new API. ![Microsoft adds log statements in their Postman collection for more visibility](https://blog.postman.com/wp-content/uploads/2022/10/23-1000x510.png)Microsoft adds log statements in their Postman collection for more visibility- [Feishu](https://www.postman.com/feishu-op/workspace/55edcb9c-bbfe-45f5-a74a-efb882fe5384/overview) localized their workspace by providing a collection in Chinese for their customers. While most API producers link to their collection from their developer portal, Feishu also links to the collection from support and troubleshooting guides, as support engineers frequently use Postman Collections to reproduce issues for troubleshooting. ![Feishu links to Postman collection from support and troubleshooting guides](https://blog.postman.com/wp-content/uploads/2022/10/24-1000x554.png)Feishu links to Postman collection from support and troubleshooting guides- [Mulesoft](https://www.postman.com/mulesoft-api/workspace/mulesoft-platform-apis/overview) hosts a workspace created by the community with contributions and input from community members. The workspace description contains updates about new releases, short videos to get started, and a section that addresses common errors where developers get stuck. ![Mulesoft community workspace provides resources to unblock developers](https://blog.postman.com/wp-content/uploads/2022/10/25-1000x699.png)Mulesoft community workspace provides resources to unblock developers### 5. Don’t forget about discovery It’s important for new and existing users to be able to find your collections, troubleshooting guides, and advanced use cases. You should optimize for search within your own developer portal and on major platforms, like the [Postman API Network](https://www.postman.com/explore) and others. You should also optimize for external search engines by making videos and blog posts that link to the relevant resources. - [DataStax](https://www.postman.com/datastax/workspace/ef3ed3ef-3a50-4651-8965-01519e15a9ba/overview) is a NoSQL database built on Apache Cassandra. They named their collections and included adequate descriptions and summaries so that users searching for “cassandra” in Postman can find DataStax in the search results. ![DataStax optimized search results for specific keywords on the Postman API Network](https://blog.postman.com/wp-content/uploads/2022/10/26-1000x643.png)DataStax optimized search results for specific keywords on the Postman API Network### 6. Delight your users In most cases, the way to delight your users may not be something your developers are asking for, but it will make your API stand out from the competition. As the API producer, you are most intimately familiar with your API and its capabilities. It’s time to get creative or borrow ideas you’ve been wowed by in the past. - [Typeform](https://www.postman.com/typeform/workspace/441d7080-8d36-46be-99e7-2077bd40fc5d/overview) has a secondary workspace for scripting API solutions to address specific customer needs. Since a picture is worth a thousand words, Typeform illustrated API workflows using Postman Flows so non-technical, business customers could visualize scripted solutions and learn about APIs interactively. ![Typeform created low-code Flows to illustrate API workflows](https://blog.postman.com/wp-content/uploads/2022/10/27-1000x624.png)Typeform created low-code Flows to illustrate API workflows- [ShipEngine](https://www.postman.com/shipengine/workspace/shipengine-s-public-workspace/overview) has previously shared [what they do to enhance developer onboarding](https://medium.com/better-practices/accelerate-growth-conversions-with-these-key-developer-onboarding-strategies-e3f0bae48456). Their workspace includes a collection dedicated to walking new users through everything their API offers. Once you enter your sandbox API key, you can play with sample data. What’s more exciting than parsing JSON? Visualizing the JSON response. Data visualizations help new users understand the data returned from the server, and provide inspiration for future integrations. ![ShipEngine's collection visualizes JSON response data](https://blog.postman.com/wp-content/uploads/2022/10/28-1000x624.png)ShipEngine's collection visualizes JSON response data## Fix the leaks in your onboarding experience In the [2022 Stack Overflow developer survey](https://survey.stackoverflow.co/2022/), 66% of professional developers have at least some influence over their organization’s decisions to purchase new technologies. While it is expected at senior-level positions, this helps explain why top-down purchasing decisions frequently fail without bottom-up developer adoption. Many organizations are therefore re-prioritizing documentation, onboarding, and developer experience. For API producers, small investments in easing early friction points can make a big difference in a developer’s onboarding experience. Technical onboarding is not just about reducing the pain and suffering of developers in the early days, but also laying a solid foundation for the developer’s journey ahead. Many of the superstar APIs covered in this post satisfy lots of these onboarding principles, but were only highlighted in one instance, so feel free to dig deeper into any particular API. [You can also check out other APIs in the Postman API Network](https://www.postman.com/explore)—and let us know about your favorite API onboarding experiences in the comments below.