In the Bubble API section we covered API requests that are incoming – they are initiated by an outside system and Bubble takes some kind of action based on their credentials, endpoint and parameters.

In this section we’ll look at requests that are outbound – when your Bubble app sends a request to an external system. When you use the API Connector, your Bubble app is the client and the API service is the server. You can read more about the client/server relationship in our Introduction to APIs.

The API Connector lets you connect your Bubble app to almost any external API. You can set up headers, parameters, and a call body, and each call can be used as an action or as a data source in your app.

The API Connector lets you set up outbound API calls, meaning calls from your app to a third party app or system.

This opens up a wide range of possibilities. You can pull live data from external services, such as weather forecasts, stock prices, exchange rates, or social media feeds. You can trigger actions on other platforms, like creating a customer in a CRM, sending a message through a chat service, or generating an invoice. You can also connect to AI services to generate text, analyze images, or translate content, and to payment providers to process transactions.

Anything a service exposes through its API is potentially reachable from your app, which means you can extend your app's capabilities far beyond Bubble's built-in features. By pointing the API Connector to different URLs, you can access specific resources offered by the API provider. Like incoming requests, these calls can either request data or trigger an action.

Structurally, they look the same as incoming requests: an HTTP request with a method such as GET, POST, PATCH, or DELETE.

The API Connector supports any service that exposes a JSON-based API. You can supply headers, parameters, and a call body, and the response is returned as structured data that Bubble can work with directly.

Each call you set up can be used in one of two ways:

An API call set to Action will show up in the API Connections submenu.

All calls made through the API Connector are routed through Bubble's server by default. This keeps your API credentials, parameters, and other sensitive data secure, since none of it ever passes through the user's device.

It's possible to configure certain calls to run directly from the browser, but for security reasons this option is only available under specific conditions: the call must be public (no authentication), have no headers or private parameters, and be configured as a data call.

Read more in the box below about how to send calls directly from the browser:

Connecting your Bubble app to an external API involves a few clear steps. Each one builds on the last, and once you've gone through the process once, you'll find the pattern is similar across most services. This article walks through the workflow at a high level, with links to more detailed articles where relevant.

Before setting anything up, it helps to have a mental model of what's happening behind the scenes. An API call is a single, isolated exchange between two systems. Your Bubble app sends a request to the external service, the service processes it, and a response is returned. Once the response is received, the connection is closed. The next call starts fresh.

This means each call is self-contained. Your app doesn't maintain an open connection to the external service. Instead, every interaction is a brief, structured request and response.

Most API services follow a two-step pattern: first, your app proves who it is through authentication, then it sends individual calls to perform specific actions or retrieve specific data.

Every external API is different, and the provider's documentation is the authoritative source on how to connect to it. Before configuring anything in Bubble, take time to read through the documentation for the service you want to connect to. You'll typically be looking for:

If this is your first time working with APIs, the documentation can feel dense. Most providers follow similar conventions, so the second and third APIs you set up will feel much more familiar than the first.

In the API Connector, each external service is configured as a collection. Start by adding a new collection and giving it a name, typically the name of the provider, such as Stripe, OpenAI, or Google Cloud. This name is used throughout the editor to organize the calls you'll add later, so choose something easy to recognize.

The collection holds all the calls for that provider, along with any authentication or shared headers and parameters that apply to all of them.

Most APIs require some form of authentication to verify that your app has permission to access the service. Authentication is configured at the collection level, which means you only set it up once per provider. Once authentication is in place, every call in that collection automatically uses it.

The specific method depends on the provider. Common options include sending an API key in the request header, using basic auth with a username and password, or following an OAuth flow. The provider's documentation will tell you which method to use and how to generate the necessary credentials.

For a full walkthrough of authentication options, see Authentication.

With the collection named and authentication configured, you can start adding individual calls. Each call represents a specific request to the API, such as fetching a list of records, creating a new item, or updating an existing one. You'll configure the HTTP method, the URL, any parameters or headers specific to that call, and decide whether the call is used as data or as an action.

For a detailed walkthrough of adding and configuring calls, see Adding calls.

Once a call is configured, it needs to be initialized before it can be used in your app. Initialization runs the call once and reads the response, so Bubble can understand the structure of the data being returned. This is what makes the call available in the editor.

Keep in mind that initialization is a real request to the API. If the call creates, updates, or deletes data on the external service, that change will actually happen. For calls with side effects, you may want to test against a sandbox or test environment if the provider offers one.

After a call has been initialized, it's available throughout your app. Data calls appear in the Get data from an external API option when inserting dynamic data, while action calls appear in the workflow editor under API Connections. From here, the call behaves like any other data source or action in Bubble.

The API Connector lets you connect to any service that exposes a JSON-based, RESTful web API. You can use this to add API calls to fetch data from an external service, or post data to trigger some actions on the service's end.

The API Connector is a separate tab found in the left-hand navigation menu:

Every API service is different and to make it possible to connect successfully to their platform, most providers offer API documentation. Using the external documentation is critical to understand how to authenticate and make calls to that specific service, so we recommend you get to know it before you start.

That said, most modern APIs follow similar conventions. Once you've set up one working connection, the next one is usually easier. You'll also find that API documentation tends to follow familiar patterns, which makes each new provider faster to read and understand.

The API Connector gives you the tools to make calls, but it can't tell you what to put in them. That information lives in the provider's documentation. Reading it first will save time, prevent guesswork, and help you avoid errors that can be hard to diagnose later. Most issues that come up when setting up an API connection trace back to a missed detail in the documentation, such as a misspelled parameter, the wrong HTTP method, or an authentication header sent in the wrong format.

If you're new to working with APIs, the documentation can feel dense and technical at first. Most providers follow similar conventions, though, and after working through one or two APIs you'll find that the patterns start to feel familiar. Reading API documentation is a skill that gets easier with practice.

Most API providers publish their documentation on their own website, usually under a section called Developers, API, or Docs. A quick search for the provider's name followed by API documentation will typically lead you straight to it. Larger providers like Stripe, OpenAI, and Google have dedicated developer portals with comprehensive documentation, while smaller services may include their API reference inside their general help center.

If the service offers more than one API, make sure you're reading the documentation for the version you intend to use. APIs often go through major versions over time, and older versions may behave differently or be deprecated.

When reading API documentation for the first time, focus on the information you'll need to configure the connection in Bubble. This usually includes:

Many providers offer a sandbox or test environment where you can make calls without affecting real data. Stripe, for example, provides separate test API keys that work against a sandboxed version of their service. Check the documentation to see whether a sandbox is available, especially if your calls will create, update, or delete data. Testing against a sandbox lets you initialize calls in Bubble and experiment with parameters without worrying about side effects.

Start with the introduction or Getting started section, if one exists. This usually gives an overview of the API's structure, authentication method, and common patterns. With that foundation in place, the rest of the documentation will be easier to navigate.

Look for code samples. Most providers include example requests in formats like cURL, JavaScript, or Python. You don't need to know these languages to benefit from the examples. They show you exactly how the request should be structured, which translates directly to what you'll configure in the API Connector.

Bookmark the pages you reference often. When setting up multiple calls for the same provider, you'll likely return to the same endpoint references repeatedly.

Keep the provider's documentation open in a separate tab while you work in Bubble. Switching back and forth is much faster than trying to memorize the details.

If this is your first time working with APIs, the documentation may seem fairly technical at first, but you’ll find that with the RESTful API style most providers follow a similar standard.

Many API providers such as Stripe offer a demo account that you can use to test your API calls without making any actual changes (or payments in the case of Stripe). Check whether the service you want to connect to offers this kind of testing environment to be able to properly test all your calls with no risk.

Most API providers offer a developer dashboard, sometimes called an API portal, developer console, or account portal. This is where you manage everything related to your account with the provider, including the credentials your Bubble app will use to authenticate.

The exact features vary by provider, but most dashboards let you:

Anything you configure in the API Connector relies on credentials and settings that originate in the developer dashboard. If a call fails, the dashboard is often the first place to check. You can usually see whether the key is still valid, whether the call hit a rate limit, or whether the provider returned a specific error.

The dashboard is also where you'll generate the credentials you need for setting up authentication in Bubble. Treat it as the source of truth for everything tied to your account with the provider.

Providers use different names for this part of their service. Stripe calls it the Dashboard, Google has the Cloud Console, OpenAI uses Platform, and others use names like Developer Portal or Account Settings. They all serve a similar purpose, but where to find them and what they include varies. The provider's documentation will usually link to the dashboard from the introduction or Getting started section.

Each API you add through the API Connector comes from a provider; the company or service that exposes the API. For example, OpenAI and Anthropic provide LLM endpoints, Stripe provides payment services, and Google and Facebook provide authentication services.

Each of these providers are usually added as an API Collection. API collections serve two purposes:

In most cases, authentication is configured at the provider level and applies to all endpoints from that provider. For example, you only need to set up authentication for Stripe once to access all of their endpoints. Each provider you connect to is listed as an API collection in the sidebar on the left. Click on a collection to see its list of calls.

Clicking + New adds a new collection and prompts you to give it a name — typically the name of the provider, such as Stripe, Google Cloud, or OpenWeatherMap.

The name is used throughout the editor to organize the API calls you add to the collection, so choose something that makes them easy to identify later.

As we covered in our general guide on how APIs work, many API services will require authentication. This is the process of identifying who the client is in order to determine what resources it should have access to.

There are many different ways to authenticate. Most API providers will have documentation available online that specifies their authentication method and many require you to generate a unique API token.

If you're new to working with APIs, it's worth emphasizing the importance of keeping your API tokens secret. API tokens serve the same basic function as a username and password: they identify who's making the request (authentication) and grant access to specific resources (authorization).

But they offer a few advantages that make them better suited to machine-to-machine communication.

They can be easily generated and revoked. Unlike a username and password, which are typically tied to a specific person, API tokens can be created and revoked on demand. If a token is compromised or no longer needed, it can be invalidated immediately without affecting the rest of your account. Many providers also let you generate multiple tokens with different permissions, so you can scope each one to a specific app or use case.

They are more secure. Tokens are typically long, random strings that are far harder to guess or brute-force than a human-chosen password. Many providers also let you rotate tokens regularly, which limits the damage if one is exposed.

They are easier to work with. Tokens don't require special handling like a password might, such as prompting for input or managing user sessions. This makes them well suited to automated processes and integrations.

That said, a token is only as secure as the person managing it. Tokens for sensitive services like Stripe, payment processors, or anything tied to user data should be treated with the same care as a master password.

A few best practices to keep in mind:

Shared headers are headers that apply to every call within a collection. Once added to the collection's shared headers section, they're automatically included with every request, so you don't need to repeat them on each individual call.

Shared headers are useful when the same value needs to accompany every call to the provider. The most common use case is authentication. For example, if a provider requires an Authorization header with a bearer token on every request, adding it as a shared header means it's applied automatically across all calls in the collection.

Another common example is the Content-Type header, which tells the provider how the request body is formatted. If every call to the API sends JSON, setting Content-Type: application/json as a shared header saves you from configuring it on each call individually.

Use shared headers for any header that:

If a header is only relevant to one or two specific calls, it's better to add it directly to those calls rather than including it as a shared header.

Shared parameters work the same way as shared headers, but they're added to the body of the request rather than the header. Once configured at the collection level, they're automatically included in every call within that collection.

Shared parameters are static, meaning their values are set once and don't change between calls. Because they can't be assigned dynamically from the editor, they're kept on the server and never exposed to the client. This makes them well suited to storing values you want to apply across all calls without revealing in your app's source code.

Use shared parameters for any value that:

If a parameter is only relevant to specific calls, or if it needs to be assigned dynamically, add it at the call level instead.

Now that we have 1) given our API service a descriptive name and 2) authenticated as a client (if necessary) it’s time to add the actual calls.

Give the call a descriptive name that works together with the provider name to identify what it does. For example, a provider named Stripe and a call named Create payment. Then use the Use as dropdown to tell Bubble how this call will be used.

The Use as dropdown lets you select whether to use that particular API call as a data source or an action:

Use as instructs Bubble to use the call as a data source, or an action.

Selecting Use as data tells Bubble to treat the API call as a data source, used for retrieving data to display in your app. Calls configured this way are available as Get data from an external API in the data source dropdown.

In this example, Get data from an external API is selected as the data source to populate a repeating group with results from an API call.

Use as action makes the API call available as an action in your Workflow editor. You will find API action calls in the workflow editor under API Connections.

When a call is made to a specific resource, we need to specify an HTTP method that tells the server what kind of action we want to initiate. The five most used HTTP methods are:

HTTP methods are sometimes called HTTP verbs. Generally they are used as illustrated in the table above, but to find the correct HTTP method for the resource you want to access, check the API providers documentation.

The examples below illustrate how HTTP methods would be used in a few different scenarios. Let's say you are connecting to a CRM and want to interact with users stored in that system. Different HTTP methods would be needed for the server to understand your request:

In our general article on APIs we explored how a RESTful API call uses a URL to identify a specific resource. Every API call you make targets an endpoint, and the endpoint determines what the call does.

You can think of an endpoint as an address. Just as a street address points to a specific building, an endpoint points to a specific resource on the provider's server. Different endpoints handle different parts of the service.

An endpoint is made up of two parts:

Together, the method and the URL form a unique endpoint that defines a specific request. The same URL can support multiple endpoints depending on the method used. For example, a GET request to /users might return a list of users, while a POST request to /users might create a new one. The URL is the same, but the method changes what the call does.

Each API provider documents the endpoints they offer, usually grouped by resource type. For example, a payment provider might have endpoints for customers, charges, subscriptions, and refunds. The documentation will list the URL, the HTTP method, and the parameters each endpoint expects.

When setting up a call in Bubble, you'll typically copy the endpoint URL from the provider's documentation and configure the matching HTTP method in the API Connector.

Most APIs use a base URL that all endpoints build on. For example, if the base URL is https://api.example.com/v1, then the full URL for a List users endpoint might be https://api.example.com/v1/users. The base URL stays the same across all endpoints, while the path after it changes depending on the resource.

Some providers version their APIs in the base URL, such as /v1 or /v2. This lets them introduce changes without breaking existing integrations. Always check the documentation to make sure you're using the version the provider recommends.

Once a call is configured in the API Connector, it needs to be initialized before it can be used in your app. Initialization is a one-time step that sends a real request to the provider and reads the response. Until a call is initialized, it won't appear in the editor as a data source or action.

Initialization serves three purposes:

Some calls require parameters with non-empty values. To initialize these calls, set a temporary placeholder value, run the initialization, and then clear the placeholder. The call will remain initialized even after the value is removed.

If you change the structure of a call, such as adding or removing parameters or modifying the response format on the provider's side, you'll need to re-initialize the call so Bubble can read the updated response. Re-initialization works the same way as the first run and sends another live request to the provider.

After a successful initialization, the API Connector displays the response from the provider. You can view it as structured data, which shows the fields Bubble has identified, or as raw output, which shows the unprocessed JSON. Reviewing the response is a good way to confirm that the data you expect is being returned and that the structure matches what you'll need in your app.

When you initialize a call, the API Connector shows both the structured response and the raw body text returned by the provider. The raw body text is the unprocessed response, exactly as the provider sent it, before Bubble parses it into fields you can reference in dynamic expressions.

Why the raw response is useful

The structured view shows the data Bubble has identified and mapped, which is what you'll typically use when building your app. The raw view is useful in a few specific situations:

Sometimes you'll want to test a call without actually sending a request to the provider, or define a sample response manually instead of relying on initialization. The API Connector supports this by letting you provide a manual response for the call.

Manual responses are useful in a few specific situations:

Instead of sending a real request, you paste a sample response that matches the structure of what the API will return. Bubble reads the sample, maps the available fields, and makes the call available in the editor just as if it had been initialized normally.

The sample should match the actual API response as closely as possible. If fields are missing or named differently, the call won't behave correctly when the live response comes in.

Once the API is available and you're ready to use real data, re-initialize the call with a real request. The API Connector updates the response structure with the live data, and the call behaves like any other initialized call from that point on.