# How to format API responses for easy parsing in Bubble.io workflows: Step-by-Ste

- Tool: Bubble
- Difficulty: Intermediate
- Time required: 20-25 min
- Compatibility: All Bubble plans
- Last updated: March 2026

## TL;DR

Parsing API responses in Bubble requires understanding how the API Connector maps JSON fields and how to handle nested objects, arrays, and unexpected formats. This tutorial covers initializing API calls to map response structures, accessing nested JSON data in workflows and elements, extracting items from lists, and building error handling for malformed responses.

## Overview: Formatting and Parsing API Responses in Bubble

This tutorial explains how to work with API response data in Bubble. You will learn how the API Connector's initialization process maps JSON fields, how to navigate nested objects, how to display API data in Repeating Groups, and how to handle cases where the API returns errors or unexpected formats.

## Before you start

- A Bubble app with the API Connector plugin installed
- At least one API call configured in the API Connector
- Basic understanding of JSON structure (objects, arrays, key-value pairs)
- Familiarity with Bubble data sources and dynamic data

## Step-by-step guide

### 1. Initialize an API call to map the response structure

In the API Connector, after configuring your API call (URL, method, headers, parameters), click Initialize call. Bubble sends a real request and uses the JSON response to create a field mapping. Each top-level key becomes an accessible field. Nested objects appear as sub-fields accessible with dot notation. Arrays become lists you can iterate over. If the API returns different structures for different requests (e.g., error vs success), initialize with a successful response first, then manually map error fields later. The initialization data becomes part of your app's schema — use sample or non-sensitive data.

> Pro tip: If the API response structure changes (new fields added or removed), re-initialize the call. Warning: removing fields may break existing references in your app.

**Expected result:** The API call is initialized with all response fields mapped and accessible in Bubble's expression editor.

### 2. Access nested JSON objects in expressions

After initialization, nested JSON objects appear as chained field names in Bubble's expression editor. For example, if the response is {"user": {"name": "John", "address": {"city": "NYC"}}}, you access the city as: API Response's user's address's city. When using the response as a data source in elements, the expression builder shows each nested level as you click through. For deeply nested objects (3+ levels), the expression can get long — consider creating a workflow that extracts key values into custom states for cleaner access throughout the page.

**Expected result:** You can access any nested field in the API response using chained field references in Bubble's expression editor.

### 3. Display API response lists in Repeating Groups

When an API response contains an array (e.g., {"results": [{"name": "Item 1"}, {"name": "Item 2"}]}), set the API call's Use as to Data. In your Repeating Group, set the data source to Get data from an external API → your API call. Bubble treats the array as a list. Inside each cell, reference Current Cell's fields (e.g., Current Cell's API Response's name). If the list is nested inside the response object, you may need to reference it as: API call's results (where results is the array field name). For pagination, pass page or offset parameters to the API call dynamically.

**Expected result:** API response arrays display as rows in a Repeating Group with individual fields accessible in each cell.

### 4. Handle mixed response formats and errors

APIs may return different structures for success vs error responses. For example, a 200 success might return {"data": [...]} while a 400 error returns {"error": "message"}. In the API Connector, check 'Include errors in response and allow workflow actions to continue.' This prevents your workflow from stopping on API errors. After the API call action, add a condition checking if the error field exists or if the status code indicates failure. Route to error handling — display an error message group, log the error, or retry the call. For robustly handling missing fields, use the :default operator to provide fallback values.

> Pro tip: Always check 'Include errors in response and allow workflow actions to continue' in the API Connector for any call that might fail — otherwise your entire workflow stops on an error.

**Expected result:** Your workflows handle both successful and error API responses without crashing.

### 5. Transform API data for display

Raw API data often needs formatting before display. Use Bubble's built-in operators to transform data: :formatted as for dates and numbers, :truncated to for long text strings, :find & replace for cleaning text, and :split by for parsing delimited strings. For more complex transformations (e.g., converting Unix timestamps to dates, parsing CSV within a JSON field), create a custom workflow that processes the raw API data and stores the formatted results in custom states or database records. This also serves as a caching layer — display the stored data instead of calling the API on every page load.

**Expected result:** API data is formatted and displayed in a user-friendly way with proper date formats, number formatting, and text truncation.

## Complete code example

File: `Workflow summary`

```text
API RESPONSE PARSING REFERENCE
================================

INITIALIZATION:
  API Connector → Configure call → Initialize
  Bubble maps JSON response to typed fields
  Re-initialize when response structure changes

ACCESSING NESTED DATA:
  JSON: {"user": {"name": "John", "address": {"city": "NYC"}}}
  Bubble: API Response's user's name → "John"
  Bubble: API Response's user's address's city → "NYC"

WORKING WITH ARRAYS:
  JSON: {"results": [{"name": "A"}, {"name": "B"}]}
  Repeating Group data source: Get data from API → Call Name
  Cell reference: Current Cell's name
  Specific item: API Response's results :first item's name
  Count: API Response's results :count

ERROR HANDLING:
  API Connector: Check 'Include errors in response...'
  Workflow:
    Step 1: API call (Action or Data)
    Step 2: Only when Result of step 1's error is not empty
      → Show error message
      → Log error to database
    Step 3: Only when Result of step 1's error is empty
      → Process successful response

DATA TRANSFORMATION OPERATORS:
  :formatted as       → Format dates/numbers
  :truncated to       → Limit text length
  :find & replace     → Clean or modify text
  :split by           → Parse delimited strings
  :default            → Fallback for empty values
  :converted to number → Text to number
  :formatted as date  → Text to date
```

## Common mistakes

- **Not re-initializing API calls when the response structure changes** — Bubble's field mapping is based on the initialization response. If the API adds or removes fields, your references may break or miss new data Fix: Re-initialize the API call whenever you know the response structure has changed, and update any broken references
- **Not checking 'Include errors in response' on API calls** — Without this option, a 400 or 500 API response terminates the entire workflow, preventing any error handling or user notification Fix: Check 'Include errors in response and allow workflow actions to continue' in the API Connector for every call that might fail
- **Calling the API on every page load instead of caching results** — Frequent API calls increase latency, consume workload units, and may trigger rate limits from the external API provider Fix: Cache API responses in your Bubble database and refresh on a schedule or when the user explicitly requests updated data

## Best practices

- Initialize API calls with representative sample data to map all possible response fields
- Always enable 'Include errors in response' for production API calls
- Cache API responses in your database to reduce calls and improve page load speed
- Use the :default operator to provide fallback values for fields that may be empty
- Extract deeply nested data into custom states for cleaner access across the page
- Re-initialize API calls when you know the response schema has changed
- Log API errors to a database for monitoring and debugging

## Frequently asked questions

### How do I access nested JSON fields in Bubble?

After initializing the API call, nested fields appear as chained references: API Response's parent's child's field. Click through each level in the expression builder.

### What happens if the API response structure changes?

Existing field references may break. Re-initialize the API call to update the mapping, then fix any broken references in your app.

### Can I parse JSON strings stored in text fields?

Bubble does not have native JSON parsing for text fields. To parse JSON text, use a JavaScript-based plugin or send the text to an API endpoint that returns it as structured JSON.

### How do I handle API rate limits?

Cache API responses in your Bubble database, use backend scheduled workflows to fetch data at controlled intervals, and add retry logic with increasing delays when rate limit errors occur.

### Can RapidDev help with complex API integrations in Bubble?

Yes. RapidDev can configure API Connector calls, handle complex response parsing, build caching layers, and implement robust error handling for any external API integration in your Bubble app.

---

Source: https://www.rapidevelopers.com/bubble-tutorial/format-api-responses-parsing-bubble-workflows
© RapidDev — https://www.rapidevelopers.com/bubble-tutorial/format-api-responses-parsing-bubble-workflows