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.
Prerequisites
- 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
Open the API Connector and create a new API
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.
Add a POST call with headers and body
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].
1POST https://api.example.com/v1/messages23Headers:4 Content-Type: application/json5 Authorization: Bearer [api_key]67Body (JSON):8{9 "to": "[recipient_email]",10 "subject": "[email_subject]",11 "body": "[message_body]"12}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.
Set the call to Action type and initialize
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.
Trigger the POST request from a workflow
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.
Handle the response in your workflow
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 working example
1{2 "api_name": "Custom Backend",3 "call_name": "Create Record",4 "method": "POST",5 "url": "https://api.example.com/v1/records",6 "headers": {7 "Content-Type": "application/json",8 "Authorization": "Bearer [api_key]"9 },10 "body": {11 "name": "[record_name]",12 "email": "[record_email]",13 "status": "active",14 "metadata": {15 "source": "bubble_app",16 "created_at": "[current_date]"17 }18 },19 "use_as": "Action",20 "parameter_notes": {21 "api_key": "Private, server-side only",22 "record_name": "Dynamic from workflow",23 "record_email": "Dynamic from workflow",24 "current_date": "Dynamic: Current date/time formatted as ISO"25 }26}Common mistakes when setting up POST requests within Bubble.io: Step-by-Step Guide
Why it's a problem: Setting 'Use as' to Data instead of Action for POST requests
How to avoid: Set 'Use as' to Action for POST, PUT, PATCH, and DELETE calls.
Why it's a problem: Forgetting the Content-Type header
How to avoid: Always add Content-Type: application/json as a header for JSON POST requests.
Why it's a problem: Not marking API keys as Private
How to avoid: 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
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I need to set up a POST request in Bubble.io's API Connector to send form data to an external API. The API requires Bearer token auth and a JSON body. Can you walk me through the configuration?
Set up a POST request in the API Connector to send data to https://api.example.com/v1/records. Configure Bearer token authentication, a JSON body with dynamic parameters, and trigger it from a form submission workflow.
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.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation