# How to set up POST requests within Bubble.io: Step-by-Step Guide

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

## TL;DR

Set up POST requests in Bubble using the API Connector plugin to send data to external APIs. This tutorial covers configuring the API Connector with headers, JSON body, authentication, initializing the call, and using it in workflows to send data from your app to any REST API endpoint.

## Overview: POST Requests in Bubble

POST requests send data from your Bubble app to external services — creating records in other systems, triggering webhooks, or submitting forms to APIs. The API Connector plugin handles all HTTP methods including POST, and this tutorial walks through the complete setup.

## Before you start

- A Bubble account with an app
- The API Connector plugin (built-in, just needs configuration)
- An API endpoint URL to send data to
- Any required API keys or authentication credentials

## Step-by-step guide

### 1. Open the API Connector and create a new API

Go to Plugins → API Connector → Add another API. Give it a descriptive name (e.g., 'SendGrid' or 'Custom Backend'). Set the authentication method — most APIs use 'Private key in header' with an Authorization header. Enter your API key in the key value field and check 'Private' to keep it server-side.

**Expected result:** A new API entry is created with authentication configured.

### 2. Add a POST call with headers and body

Click 'Add another call' under your API. Name it descriptively (e.g., 'Send Email'). Change the method dropdown from GET to POST. Enter the endpoint URL. Add a header: Content-Type = application/json. In the body section, select JSON and enter your payload structure with bracketed parameter names for dynamic values like [recipient_email] and [message_body].

```
POST https://api.example.com/v1/messages

Headers:
  Content-Type: application/json
  Authorization: Bearer [api_key]

Body (JSON):
{
  "to": "[recipient_email]",
  "subject": "[email_subject]",
  "body": "[message_body]"
}
```

> Pro tip: Parameters in square brackets [like_this] become dynamic fields you can fill from workflows.

**Expected result:** A POST call is configured with dynamic parameters in the URL, headers, or body.

### 3. Set the call to Action type and initialize

Under 'Use as,' select 'Action' (not Data). Action calls appear in workflow action lists under the Plugins section. Enter sample values for all parameters (use test data, not real credentials). Click 'Initialize call.' Bubble sends the request and shows the response. Verify the response looks correct.

**Expected result:** The call initializes successfully and the response structure is mapped.

### 4. Trigger the POST request from a workflow

Go to your page's Workflow tab. On a button click or other event, add an action: Plugins → your API name → your call name. Bubble shows input fields for each parameter you defined with brackets. Map them to dynamic data: [recipient_email] = Input Email's value, [email_subject] = 'Welcome!', [message_body] = Multiline Input's value. The POST request fires when the workflow runs.

**Expected result:** Clicking the button sends a POST request with dynamic data from the page.

### 5. Handle the response in your workflow

After the API call action, you can reference 'Result of step X' to access the response data. If the API returns a JSON object with an 'id' field, access it as Result of step X's id. Use this to store the external ID in your database or display a success message. Add error handling with an 'An unhandled error occurs' event.

**Expected result:** The workflow processes the API response and uses returned data in subsequent actions.

## Complete code example

File: `API Connector payload`

```json
{
  "api_name": "Custom Backend",
  "call_name": "Create Record",
  "method": "POST",
  "url": "https://api.example.com/v1/records",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer [api_key]"
  },
  "body": {
    "name": "[record_name]",
    "email": "[record_email]",
    "status": "active",
    "metadata": {
      "source": "bubble_app",
      "created_at": "[current_date]"
    }
  },
  "use_as": "Action",
  "parameter_notes": {
    "api_key": "Private, server-side only",
    "record_name": "Dynamic from workflow",
    "record_email": "Dynamic from workflow",
    "current_date": "Dynamic: Current date/time formatted as ISO"
  }
}
```

## Common mistakes

- **Setting 'Use as' to Data instead of Action for POST requests** — Data calls are for GET requests that return data to display. POST calls that create or modify data should be Actions. Fix: Set 'Use as' to Action for POST, PUT, PATCH, and DELETE calls.
- **Forgetting the Content-Type header** — Without Content-Type: application/json, the API may not parse your JSON body correctly Fix: Always add Content-Type: application/json as a header for JSON POST requests.
- **Not marking API keys as Private** — Non-private parameters are sent from the browser, exposing your API key to users Fix: Check the 'Private' checkbox on any parameter containing API keys or secrets

## Best practices

- Always mark API keys and secrets as Private in the API Connector
- Use Action type for POST/PUT/DELETE calls and Data type for GET calls
- Test with sample data during initialization — do not use production credentials
- Add Content-Type: application/json header for all JSON body requests
- Handle errors with the 'An unhandled error occurs' workflow event
- Log API responses to a database for debugging and audit purposes

## Frequently asked questions

### Can I send form data instead of JSON?

Yes. Change the body format from JSON to form-data in the API Connector. This is needed for some legacy APIs and file upload endpoints.

### How do I send a list/array in the body?

Format the array as JSON in the body: {"items": ["[item1]", "[item2]"]}. Each bracketed value becomes a dynamic parameter.

### Can I chain multiple POST requests?

Yes. Add multiple API call actions in sequence in your workflow. Use 'Result of step X' to pass data from one call to the next.

### What if the API returns an error?

Check 'Include errors in response and allow workflow actions to continue' in the API Connector call settings. Then check the response status in your workflow.

### Is there a timeout for API calls?

Bubble times out API calls after 150 seconds and automatically retries. For long-running operations, use webhooks to receive the result asynchronously.

### Can RapidDev help set up complex API integrations?

Yes. RapidDev configures API integrations with error handling, retry logic, and complex data transformations.

---

Source: https://www.rapidevelopers.com/bubble-tutorial/setup-post-requests-bubble
© RapidDev — https://www.rapidevelopers.com/bubble-tutorial/setup-post-requests-bubble