# Postman

- Tool: Bubble
- Difficulty: Beginner
- Time required: 45–90 minutes
- Last updated: July 2026

## TL;DR

Postman is the essential development companion for Bubble's built-in REST API. Enable the Bubble API and Workflow API in Settings → API, generate an API token, then use Postman to test data endpoints (`/api/1.1/obj/{type}`) and Backend Workflow triggers (`/api/1.1/wf/{workflow-name}`). Postman also helps you prototype third-party API calls before translating them to Bubble's API Connector.

## Two Ways Postman Powers Your Bubble Development

Most Bubble tutorials focus on connecting to external services. But Bubble has its own fully featured REST API — and most Bubble builders have never used it. Enabling this built-in API unlocks a workflow that transforms how you develop, debug, and share your Bubble app.

First: Bubble's native REST API. When you enable it in Settings → API, Bubble automatically generates endpoints for every data type in your app. Need to list all 'User' records? `GET /api/1.1/obj/user`. Need to create a new 'Project'? `POST /api/1.1/obj/project`. Need to trigger a 'Send Invoice' Backend Workflow? `POST /api/1.1/wf/send-invoice`. Postman lets you test every one of these endpoints with precision — see exactly what fields come back, debug Privacy Rule restrictions, and document the API for external developers who need to integrate with your Bubble app.

Second: prototyping outbound API calls. Before you configure an API in Bubble's API Connector, spending 15 minutes in Postman to verify the auth header format, test the endpoint, and inspect the response structure saves you from the frustrating 'There was an issue setting up your call' error in Bubble. A request that works in Postman will work in Bubble's API Connector — the same method, headers, and body translate directly.

Bubble's Backend Workflow API requires at least the Starter paid plan. The data CRUD endpoints (`/obj/`) are available on all plans when the Bubble API is enabled.

## Before you start

- A Bubble app on at least the Free plan (CRUD API) or Starter plan (Workflow API + Backend Workflows)
- Postman installed on your computer (free at postman.com) or access to Postman's web client
- Admin access to your Bubble app editor to enable the API and generate a token
- Basic understanding of HTTP methods (GET, POST, PATCH, DELETE) and JSON

## Step-by-step guide

### 1. Enable Bubble's REST API and Generate an API Token

Before Postman can talk to your Bubble app, you need to enable the API and create an authentication token. In the Bubble editor, click Settings in the top navigation bar. In the left panel, click the API tab.

You'll see two toggle switches to enable:
1. 'Enable the Bubble API' — activates the auto-generated CRUD endpoints for all your data types (`/obj/{type}`)
2. 'Enable Workflow API' — exposes Backend Workflow endpoints (`/wf/{workflow-name}`). Note: Backend Workflows only exist on paid Bubble plans (Starter and above). If you're on the Free plan, you can still use the data CRUD API.

Click 'Generate a new API token' (or 'New token'). Give it a name like 'Postman Testing' so you can identify it later. Copy the token value — it looks like a long string of random characters. Store it somewhere safe, like a password manager. You won't be able to see this token again after leaving the page.

This token grants full access to all your app's data and workflows — treat it like a password. Never commit it to a GitHub repository or paste it in a public Postman workspace.

```
// Bubble API token authentication format for Postman
// Header key: Authorization
// Header value: Bearer YOUR_TOKEN_HERE
//
// OR as a query parameter (alternative method):
// GET https://yourapp.bubbleapps.io/api/1.1/obj/user?api_token=YOUR_TOKEN_HERE
//
// Bearer header is recommended — keeps the token out of URL logs
```

**Expected result:** Bubble's Settings → API page shows the API enabled, Workflow API enabled (if on paid plan), and at least one API token listed in the tokens table. The token value has been copied to a safe location.

### 2. Set Up a Postman Environment and Collection

Environments in Postman store variables (like your Bubble token and base URL) so you can reuse them across all requests without hardcoding sensitive values. Collections organize related requests into a named group that can be shared and exported.

In Postman, click the Environments icon (the eye icon in the top-right, or the 'Environments' tab in the sidebar). Click 'Create Environment' and name it 'Bubble - [Your App Name]'.

Add these environment variables:
- `base_url` — Initial value: `https://yourapp.bubbleapps.io/api/1.1` (replace `yourapp` with your actual Bubble app name)
- `api_token` — Initial value: the token you generated in Step 1. Check the 'Secret' box on this variable so the value is masked in the UI and not visible in shared collections.

Click 'Save'. In the top-right dropdown, select the new environment so it's active.

Next, create a Collection: click the 'Collections' tab in the sidebar, click the '+' button, and name it 'Bubble API - [Your App Name]'. This is where you'll save all your Bubble API requests. Organizing requests into folders (Users, Projects, Workflows, etc.) by data type keeps things clean as your API grows.

```
// Postman Environment Variables
// Name: Bubble - My App
//
// Variable         | Type    | Initial Value
// base_url         | default | https://yourapp.bubbleapps.io/api/1.1
// api_token        | secret  | your-bubble-api-token-here
//
// Usage in requests:
// URL: {{base_url}}/obj/user
// Header: Authorization: Bearer {{api_token}}
```

**Expected result:** A Postman environment named 'Bubble - [App Name]' exists with `base_url` and `api_token` variables configured. The environment is selected as active in the top-right dropdown. A Collection named 'Bubble API - [App Name]' is created and visible in the sidebar.

### 3. Test Bubble's Data CRUD Endpoints

With your environment set up, create your first Postman request to read data from Bubble. In your Collection, click the three dots and select 'Add request'. Name it 'List Users'.

Set the method to GET and the URL to `{{base_url}}/obj/user`. In the Headers tab, add a new header: Key = `Authorization`, Value = `Bearer {{api_token}}`. Click 'Send'.

If authentication is working, you'll see a JSON response with a `response` object containing `cursor`, `remaining`, `count`, and `results` (the array of User records). If you see a 401 Unauthorized response, verify the token is correct and the Bubble API is enabled.

Explore the full set of available operations:
- `GET /obj/{type}` — list records (add `?constraints=[...]` for filtering)
- `GET /obj/{type}/{id}` — get a single record by ID
- `POST /obj/{type}` — create a new record (JSON body with field values)
- `PATCH /obj/{type}/{id}` — update a record
- `DELETE /obj/{type}/{id}` — delete a record

For the `{type}` value, use the lowercase, hyphenated name of your Bubble data type (e.g., 'user', 'project', 'invoice'). Save each working request to your Collection so you can reuse and share them.

```
// GET — List User records
GET {{base_url}}/obj/user
Authorization: Bearer {{api_token}}

// GET — Single record by ID
GET {{base_url}}/obj/user/1234567890abcdef
Authorization: Bearer {{api_token}}

// POST — Create a new record
POST {{base_url}}/obj/project
Authorization: Bearer {{api_token}}
Content-Type: application/json

{
  "name": "Test Project",
  "status": "active",
  "owner": "1234567890abcdef"
}

// PATCH — Update a record
PATCH {{base_url}}/obj/project/9876543210fedcba
Authorization: Bearer {{api_token}}
Content-Type: application/json

{
  "status": "completed"
}

// DELETE — Delete a record
DELETE {{base_url}}/obj/project/9876543210fedcba
Authorization: Bearer {{api_token}}
```

**Expected result:** The GET `/obj/user` request returns a 200 OK response with a JSON body containing a `results` array. Each result contains the fields defined in your Bubble User data type. POST, PATCH, and DELETE requests return appropriate success responses (201 Created, 200 OK).

### 4. Test Backend Workflow (API Endpoint) Triggers

Backend Workflows in Bubble can be exposed as HTTP endpoints that external systems — and Postman — can trigger via POST requests. This requires a paid Bubble plan (Starter and above).

To check which Backend Workflows are exposed: in the Bubble editor, look at the Backend Workflows section (click the hamburger menu → Backend Workflows, or find it in the left panel depending on your Bubble editor version). For each workflow you want to expose via API, click on it and check the API settings — specifically 'Expose this workflow to be run via API (POST request)' and set any required parameters.

In Postman, create a new POST request. Set the URL to `{{base_url}}/wf/your-workflow-name` (replace `your-workflow-name` with the exact name of your Backend Workflow, lowercased and hyphenated). Set the method to POST.

In the Headers tab, add `Authorization: Bearer {{api_token}}` and `Content-Type: application/json`. In the Body tab, select 'raw' and 'JSON', then enter a JSON object with the parameters your workflow expects. If the workflow accepts a `user_email` and `order_id` parameter, the body should be `{"user_email": "test@example.com", "order_id": "order-123"}`.

Click Send. A successful trigger returns a 200 OK response. If the workflow has a Return Data action, the return values appear in the response body.

```
// POST — Trigger a Bubble Backend Workflow
POST {{base_url}}/wf/send-welcome-email
Authorization: Bearer {{api_token}}
Content-Type: application/json

{
  "user_email": "newuser@example.com",
  "user_name": "Jane Smith",
  "plan_type": "pro"
}

// Successful response (200 OK):
{
  "status": "success",
  "response": {
    "body": {}
  }
}

// Response with return data:
{
  "status": "success",
  "response": {
    "body": {
      "confirmation_id": "conf-abc123",
      "sent_at": "2026-07-10T14:30:00Z"
    }
  }
}
```

**Expected result:** The POST request to the workflow endpoint returns 200 OK. If the workflow sends an email or creates a record, verify the action occurred in your Bubble app's Logs tab (available in the editor). Workflow trigger errors appear in Bubble's Logs → API logs.

### 5. Prototype a Third-Party API Call in Postman Before Adding to Bubble's API Connector

Before configuring a new third-party API in Bubble's API Connector, test it thoroughly in Postman. This is the most reliable way to avoid the frustrating 'There was an issue setting up your call' error — which occurs when Bubble's Initialize call hits an authentication failure, wrong endpoint, or malformed response.

In Postman, create a new request in a separate collection (or folder) for the third-party service. Configure the auth header exactly as the API's documentation specifies. Try the request with your real credentials and a real endpoint. Inspect the response carefully — look at the JSON structure, note which fields you need, and confirm the response is non-empty.

Once the request works in Postman, translate it to Bubble's API Connector with these mappings:
- Postman URL → Bubble API Connector root URL + call path
- Postman Authorization header → Bubble shared header, marked 'Private'
- Postman response fields → Bubble auto-detected types after 'Initialize call'

RapidDev's team has built hundreds of Bubble integrations this way — if the API has complex OAuth flows or multi-step authentication, a free scoping call at rapidevelopers.com/contact can save you significant time.

The Initialize call in Bubble needs a real, non-empty response to auto-detect field types. This is why testing in Postman first matters: you can verify the response contains data before attempting initialization in Bubble.

```
// Example: Prototyping a CRM API call in Postman
// Step 1: Test in Postman
GET https://api.example-crm.com/v1/contacts
Authorization: Bearer YOUR_CRM_API_KEY
Content-Type: application/json

// Step 2: Verify response (non-empty results required for Bubble initialization)
{
  "data": [
    {
      "id": "contact-001",
      "name": "Jane Smith",
      "email": "jane@example.com",
      "company": "Acme Corp"
    }
  ],
  "total": 1,
  "page": 1
}

// Step 3: Translate to Bubble API Connector
// Root URL: https://api.example-crm.com/v1
// Shared header: Authorization = Bearer YOUR_CRM_API_KEY [Private checkbox: ON]
// Call name: List Contacts
// Method: GET
// Path: /contacts
// Use as: Data
// Then click Initialize call → Bubble auto-detects fields from the response
```

**Expected result:** The third-party API request returns a 200 OK in Postman with a valid JSON response containing at least one result. The Bubble API Connector's Initialize call succeeds and auto-detects the response fields, which then appear as selectable fields in Bubble's workflow editor.

### 6. Write Postman Tests and Share the Collection

Postman's built-in test scripts let you automate validation of your Bubble API responses — checking that status codes are correct, that required fields are present, and that data types are as expected. This is especially useful when sharing your Bubble API with external developers.

In any request, click the 'Tests' tab below the request URL. Postman tests are written in JavaScript using Postman's built-in `pm` API. Common tests to add:

After writing tests, run your entire Collection via the 'Run Collection' button (the right-arrow icon next to the collection name). This executes all requests in sequence and shows pass/fail status for each test — a quick health check for your entire Bubble API.

To share the collection with external developers: click the three dots on your Collection → Share → Copy link (for workspace sharing) or Export → Collection v2.1 (for a shareable JSON file). Include the environment file (without the actual token) so recipients can plug in their own credentials.

```
// Postman Test Scripts (Tests tab for each request)

// Test 1: Verify 200 OK status
pm.test('Status is 200', function() {
  pm.response.to.have.status(200);
});

// Test 2: Response has expected structure
pm.test('Response has results array', function() {
  const body = pm.response.json();
  pm.expect(body).to.have.property('response');
  pm.expect(body.response).to.have.property('results');
  pm.expect(body.response.results).to.be.an('array');
});

// Test 3: At least one result returned
pm.test('Results array is not empty', function() {
  const body = pm.response.json();
  pm.expect(body.response.results.length).to.be.greaterThan(0);
});

// Test 4: Required fields present on first record
pm.test('User record has required fields', function() {
  const body = pm.response.json();
  const firstUser = body.response.results[0];
  pm.expect(firstUser).to.have.property('_id');
  pm.expect(firstUser).to.have.property('Created Date');
  pm.expect(firstUser).to.have.property('email');
});

// Save last created record ID for use in subsequent requests
pm.test('Save user ID to environment', function() {
  const body = pm.response.json();
  if (body.id) {
    pm.environment.set('last_created_id', body.id);
  }
});
```

**Expected result:** Running the Collection via 'Run Collection' shows all tests passing with green checkmarks. The Collection is exportable as a v2.1 JSON file that external developers can import into their Postman and immediately start testing your Bubble API after inserting their own token.

## Best practices

- Store your Bubble API token in Postman's Vault (or as a 'secret' environment variable) — never hardcode it in request URLs or request bodies. Postman collections can be accidentally shared publicly; a secret variable ensures the token isn't exposed even if the collection is.
- Create one Postman environment per Bubble app version: 'Bubble Dev' pointing to your development version's URL and 'Bubble Prod' pointing to the live app URL. Switch between them to test changes in development before verifying on production.
- Write Postman tests for every Bubble API request and run the full Collection as a regression suite before major app updates. This catches Privacy Rule changes or data type modifications that break external integrations before they affect production systems.
- When testing Backend Workflow endpoints that create data (orders, notifications, user accounts), use Postman's pre-request scripts to flag test records with a `is_test: true` field, and set up a Bubble workflow to auto-delete records where `is_test = yes` to keep your database clean during development.
- Export your Postman Collection as a v2.1 JSON file and commit it to your project's GitHub repository (without the token). This creates living documentation of your Bubble app's API that new team members can import immediately.
- Use Postman's 'Constraints' feature when testing Bubble's `/obj/` endpoints with filters — the Bubble API accepts `constraints` as a JSON-encoded array in the query string. Test complex constraint combinations in Postman before building them into Bubble workflows.
- When collaborating with external developers who need to call your Bubble API, create a dedicated API token for them (Settings → API → Generate new token). This allows you to revoke their access without affecting other integrations if the relationship ends or security requires a token rotation.

## Use cases

### Test and Document Bubble's REST API for External Integrations

Your Bubble app is the backend for a mobile app or third-party system that needs to read and write data. Use Postman to test all Bubble's auto-generated CRUD endpoints, verify the token authentication works, check that Privacy Rules return the correct fields, and export a Postman Collection to share with the development team building the external integration.

Prompt example:

```
How do I use Postman to test my Bubble app's REST API and share the endpoint documentation with a mobile developer integrating with my app?
```

### Trigger and Debug Bubble Backend Workflows via API

You have a Backend Workflow in Bubble (a 'Send Welcome Email' or 'Process Payment' automation) that needs to be triggered by an external system on demand. Use Postman to test the workflow endpoint, verify it accepts the correct parameters, and confirm it runs successfully before setting up the external system to call it in production.

Prompt example:

```
I have a Bubble Backend Workflow called 'process-order'. How do I trigger it from Postman with the right Bearer token and JSON body parameters?
```

### Prototype Third-Party API Calls Before Adding to Bubble's API Connector

You want to connect Bubble to a new payment processor or CRM with a complex API. Test the API in Postman first — verify the auth header format, find the right endpoint, inspect the response structure, and identify which fields you need. Once it works in Postman, translating the configuration to Bubble's API Connector is straightforward.

Prompt example:

```
I want to connect Bubble to a third-party CRM. Can I test the CRM API in Postman first and then copy the configuration to Bubble's API Connector?
```

## Troubleshooting

### Postman returns 401 Unauthorized when calling Bubble's API endpoints

Cause: The API token is either missing from the request, entered incorrectly, or the Bubble API hasn't been enabled in Settings → API. The most common mistake is sending the token as a query parameter in one request and as a Bearer header in another, causing inconsistency.

Solution: Verify in Bubble's Settings → API that the API is enabled and the token is listed. In Postman, confirm the Authorization header is set to `Bearer YOUR_TOKEN_HERE` (with 'Bearer ' followed by a space and then the token). Check that the Postman environment variable `api_token` is set to the token value and the environment is selected (shown in the top-right dropdown). Try sending the token as a query parameter `?api_token=YOUR_TOKEN` to isolate whether the header format is the issue.

```
// Correct Authorization header format:
Authorization: Bearer 1a2b3c4d5e6f7890abcdef1234567890

// NOT:
Authorization: 1a2b3c4d5e6f7890abcdef1234567890
Authorization: Token 1a2b3c4d5e6f7890abcdef1234567890
```

### Bubble's API returns records but some fields are missing from the response

Cause: Bubble's Privacy Rules restrict which fields are visible based on the requester's role. The API token inherits 'no-role' access by default, meaning it can only see fields that are marked visible to users with no role in your Privacy Rules configuration.

Solution: Go to Bubble's Data tab → Privacy. Find the data type returning incomplete records. Click on its privacy rules. Check whether fields you expect to see are restricted to specific roles (e.g., 'Current User is This User'). For admin API access, you can create a special 'Admin' role in Bubble and configure the API to use it, or temporarily relax Privacy Rules for specific fields during development. Be careful — Privacy Rules protect sensitive user data from being exposed via the API.

### Bubble Backend Workflow endpoint returns 404 Not Found

Cause: One of three issues: (1) Workflow API not enabled in Settings → API, (2) the Backend Workflow doesn't have 'Expose as API endpoint' checked, or (3) the URL slug in Postman doesn't match the Backend Workflow name exactly.

Solution: In Bubble editor, go to Settings → API and confirm 'Enable Workflow API' is toggled on (requires a paid plan). Next, open your Backend Workflows, find the specific workflow, click its API settings, and confirm the 'This workflow can be run without authentication' or API exposure setting is enabled. Finally, compare the workflow name in Bubble to the URL path in Postman — the slug must match exactly, using hyphens not spaces, and is case-sensitive.

```
// Correct URL format:
https://yourapp.bubbleapps.io/api/1.1/wf/send-welcome-email

// Common mistakes:
https://yourapp.bubbleapps.io/api/1.1/wf/Send Welcome Email  // spaces, wrong case
https://yourapp.bubbleapps.io/api/1.1/wf/sendWelcomeEmail    // camelCase
https://yourapp.bubbleapps.io/api/1.1/wf/send_welcome_email  // underscores
```

### A third-party API call works in Postman but fails with 'There was an issue setting up your call' in Bubble's API Connector

Cause: Three most common causes: (1) the Initialize call returned an empty response — Bubble needs real data to detect field types; (2) the endpoint uses plain HTTP instead of HTTPS; (3) the auth header format was entered differently in Bubble's API Connector than in Postman.

Solution: Compare the Postman request exactly against the Bubble API Connector configuration — method, full URL, headers (including capitalization), and body format. Ensure the header marked 'Private' in Bubble matches the exact header name from Postman. For the empty-response issue, test the endpoint with parameters that guarantee a non-empty response (e.g., search with a term that returns results). For HTTPS issues, check that the root URL in Bubble's API Connector starts with `https://`.

### Bubble API Workflow returns 'Workflow API is not enabled'

Cause: The Workflow API feature is only available on paid Bubble plans (Starter and above). Free plan apps cannot expose Backend Workflows as API endpoints.

Solution: Upgrade your Bubble app to the Starter plan (or higher) to enable Backend Workflow API endpoints. If upgrading isn't an option, use Bubble's data CRUD API (`/obj/`) as an alternative for triggering logic — create a new record of a special 'Trigger' data type, and use a Bubble workflow that runs when a new Trigger record is created. This is a workaround that uses data creation as a workflow trigger, avoiding the Backend Workflow API requirement.

## Frequently asked questions

### Does Postman connect to Bubble in real-time during production, or is it just for testing?

Postman is a development and testing tool, not a production integration. You use it during development to test Bubble's API endpoints and debug issues — not as a runtime integration. In production, external systems call Bubble's API directly using the same endpoint URLs and tokens you tested in Postman. Postman's role ends when development and testing are complete.

### Do I need a paid Bubble plan to use Postman with my Bubble app?

For data CRUD endpoints (`/obj/`) — no. The Bubble API for data access is available on all plans, including Free, when you enable it in Settings → API. For Backend Workflow endpoints (`/wf/`) — yes, a paid Bubble Starter plan or above is required. Free-plan apps cannot expose Backend Workflows as API endpoints.

### How do I limit what the Postman API token can access in my Bubble app?

Bubble's API token system doesn't support granular scopes — all tokens have full access to all data types. The primary access control mechanism is Bubble's Privacy Rules: fields and records are only visible via the API if the Privacy Rules allow access for users with 'no role'. Configure Privacy Rules carefully to restrict which data fields are exposed through the API, and treat the API token as a full-admin credential to be protected accordingly.

### Can Postman be set up to automatically test my Bubble API on a schedule?

Yes, using Postman Monitors (available on paid Postman plans). A Monitor runs your Collection on a schedule and alerts you if any test fails. This is useful for monitoring your Bubble API's health — testing that critical endpoints return the expected responses. Free Postman accounts can use the Postman CLI (`newman`) to run collections on a schedule via any CI/CD system.

### Why does my Bubble API return a different structure than what Postman shows when I initialize in Bubble's API Connector?

Bubble's API Connector runs the Initialize call from Bubble's servers, not your browser. If the third-party API has IP restrictions or returns different data based on the requester's location, the response Bubble gets may differ from what Postman shows on your local machine. Check the API's documentation for IP whitelisting requirements. Also, Postman may be using cached cookies or session data — Bubble's server-side call starts fresh with no session state.

---

Source: https://www.rapidevelopers.com/bubble-integrations/postman
© RapidDev — https://www.rapidevelopers.com/bubble-integrations/postman