Postman

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.

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

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.

1// Postman Environment Variables
2// Name: Bubble - My App
3//
4// Variable         | Type    | Initial Value
5// base_url         | default | https://yourapp.bubbleapps.io/api/1.1
6// api_token        | secret  | your-bubble-api-token-here
7//
8// Usage in requests:
9// URL: {{base_url}}/obj/user
10// Header: Authorization: Bearer {{api_token}}

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.

1// GET — List User records
2GET {{base_url}}/obj/user
3Authorization: Bearer {{api_token}}
4
5// GET — Single record by ID
6GET {{base_url}}/obj/user/1234567890abcdef
7Authorization: Bearer {{api_token}}
8
9// POST — Create a new record
10POST {{base_url}}/obj/project
11Authorization: Bearer {{api_token}}
12Content-Type: application/json
13
14{
15  "name": "Test Project",
16  "status": "active",
17  "owner": "1234567890abcdef"
18}
19
20// PATCH — Update a record
21PATCH {{base_url}}/obj/project/9876543210fedcba
22Authorization: Bearer {{api_token}}
23Content-Type: application/json
24
25{
26  "status": "completed"
27}
28
29// DELETE — Delete a record
30DELETE {{base_url}}/obj/project/9876543210fedcba
31Authorization: Bearer {{api_token}}

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.

1// POST — Trigger a Bubble Backend Workflow
2POST {{base_url}}/wf/send-welcome-email
3Authorization: Bearer {{api_token}}
4Content-Type: application/json
5
6{
7  "user_email": "newuser@example.com",
8  "user_name": "Jane Smith",
9  "plan_type": "pro"
10}
11
12// Successful response (200 OK):
13{
14  "status": "success",
15  "response": {
16    "body": {}
17  }
18}
19
20// Response with return data:
21{
22  "status": "success",
23  "response": {
24    "body": {
25      "confirmation_id": "conf-abc123",
26      "sent_at": "2026-07-10T14:30:00Z"
27    }
28  }
29}

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.

1// Example: Prototyping a CRM API call in Postman
2// Step 1: Test in Postman
3GET https://api.example-crm.com/v1/contacts
4Authorization: Bearer YOUR_CRM_API_KEY
5Content-Type: application/json
6
7// Step 2: Verify response (non-empty results required for Bubble initialization)
8{
9  "data": [
10    {
11      "id": "contact-001",
12      "name": "Jane Smith",
13      "email": "jane@example.com",
14      "company": "Acme Corp"
15    }
16  ],
17  "total": 1,
18  "page": 1
19}
20
21// Step 3: Translate to Bubble API Connector
22// Root URL: https://api.example-crm.com/v1
23// Shared header: Authorization = Bearer YOUR_CRM_API_KEY [Private checkbox: ON]
24// Call name: List Contacts
25// Method: GET
26// Path: /contacts
27// Use as: Data
28// Then click Initialize call → Bubble auto-detects fields from the response

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.

1// Postman Test Scripts (Tests tab for each request)
2
3// Test 1: Verify 200 OK status
4pm.test('Status is 200', function() {
5  pm.response.to.have.status(200);
6});
7
8// Test 2: Response has expected structure
9pm.test('Response has results array', function() {
10  const body = pm.response.json();
11  pm.expect(body).to.have.property('response');
12  pm.expect(body.response).to.have.property('results');
13  pm.expect(body.response.results).to.be.an('array');
14});
15
16// Test 3: At least one result returned
17pm.test('Results array is not empty', function() {
18  const body = pm.response.json();
19  pm.expect(body.response.results.length).to.be.greaterThan(0);
20});
21
22// Test 4: Required fields present on first record
23pm.test('User record has required fields', function() {
24  const body = pm.response.json();
25  const firstUser = body.response.results[0];
26  pm.expect(firstUser).to.have.property('_id');
27  pm.expect(firstUser).to.have.property('Created Date');
28  pm.expect(firstUser).to.have.property('email');
29});
30
31// Save last created record ID for use in subsequent requests
32pm.test('Save user ID to environment', function() {
33  const body = pm.response.json();
34  if (body.id) {
35    pm.environment.set('last_created_id', body.id);
36  }
37});