Backend API workflows in Bubble accept parameters that you define when creating the workflow. This tutorial covers defining parameter types, sending parameters from the frontend, passing JSON bodies from external apps, and accessing parameter values inside the workflow to create or modify data.
Overview: Passing Parameters in API Workflows
Backend API workflows are powerful server-side processes in Bubble that can accept data through parameters. Whether you are scheduling a workflow from the frontend, calling it from another Bubble app, or hitting the endpoint from an external service, you need to define and pass parameters correctly. This tutorial covers the complete parameter lifecycle.
Prerequisites
- A Bubble app on a Starter plan or above
- The Workflow API enabled in Settings → API tab
- Basic familiarity with Bubble workflows and the Data tab
- An understanding of what backend workflows are
Step-by-step guide
Create a backend workflow and define its parameters
Create a backend workflow and define its parameters
In the Workflow tab, open the Pages dropdown at the top and click Backend workflows at the bottom of the list. Click to add a new API workflow. Give it a descriptive name like process-order. In the workflow editor, you will see a section for Parameters. Click Add a new parameter. For each parameter, set a name (e.g., order_id, customer_email, total_amount) and a type (text, number, date, yes/no, or any Data Type). Add as many parameters as your workflow needs.
Pro tip: Use descriptive parameter names with underscores — they become part of the API endpoint's JSON body structure.
Expected result: Your backend workflow has named parameters with specified types ready to receive data.
Send parameters from a frontend workflow
Send parameters from a frontend workflow
On a page in your app, create a workflow (e.g., when a button is clicked). Add the action Schedule API Workflow. Select your backend workflow from the dropdown. You will see all the parameters you defined appear as fields. Fill each one with dynamic values — for example, set order_id to Result of Step 1's Unique ID, customer_email to Current User's email, and total_amount to a calculated value. Set the Scheduled date to Current date/time to run it immediately.
Expected result: The frontend workflow passes all required data to the backend workflow, which runs server-side.
Call the workflow from an external application
Call the workflow from an external application
If you checked Expose as a public API workflow on the backend workflow, it becomes callable via HTTP POST at: https://yourapp.bubbleapps.io/api/1.1/wf/process-order. Send a JSON body with keys matching your parameter names. Include your API token in the Authorization header as Bearer YOUR_TOKEN. The parameter names in the JSON body must match exactly what you defined in Bubble, using the same casing.
1POST https://yourapp.bubbleapps.io/api/1.1/wf/process-order2Content-Type: application/json3Authorization: Bearer YOUR_API_TOKEN45{6 "order_id": "1234567890x9876",7 "customer_email": "buyer@example.com",8 "total_amount": 49.999}Pro tip: Test your API endpoint with a tool like Postman before integrating it with an external service.
Expected result: External applications can trigger your backend workflow by sending a POST request with the correct parameters.
Access parameter values inside the workflow
Access parameter values inside the workflow
Inside your backend workflow, each parameter is available as a data source. When configuring actions, you will see your parameter names in the dynamic data dropdown. For example, in a Create a New Thing action, set a field to order_id (the parameter) or customer_email. Parameters behave exactly like any other data source in Bubble — you can use them in conditions, calculations, and as inputs to other actions.
Expected result: Your backend workflow actions can read and use all passed parameter values.
Return data from the workflow
Return data from the workflow
If your workflow needs to send data back to the caller (important for external API calls), add a Return data from API action as the last step. Configure the return keys and values — for example, return a status text and a created record's Unique ID. External callers receive this data as the JSON response body. Frontend callers using Schedule API Workflow cannot receive return data — use a regular API Workflow action for synchronous calls.
Expected result: External API callers receive a JSON response with the data you specified in the Return data action.
Complete working example
1{2 "_comment": "Example POST body for calling a Bubble backend API workflow",3 "endpoint": "POST https://yourapp.bubbleapps.io/api/1.1/wf/process-order",4 "headers": {5 "Content-Type": "application/json",6 "Authorization": "Bearer YOUR_API_TOKEN"7 },8 "body": {9 "order_id": "1234567890x9876",10 "customer_email": "buyer@example.com",11 "total_amount": 49.99,12 "items": ["item_id_1", "item_id_2"],13 "apply_discount": true14 },15 "expected_response": {16 "status": "success",17 "response": {18 "order_status": "processed",19 "confirmation_id": "conf_abc123"20 }21 }22}Common mistakes when passing parameters to API workflows in Bubble.io: Step-by-Step Guide
Why it's a problem: Mismatching parameter names between the caller and the workflow definition
How to avoid: Copy parameter names directly from the backend workflow definition into your API call body
Why it's a problem: Forgetting to expose the workflow as a public API
How to avoid: Open the backend workflow and check the Expose as a public API workflow checkbox
Why it's a problem: Using Schedule API Workflow and expecting return data
How to avoid: For synchronous calls that need return data, use the API Connector to call your own workflow, or restructure to use database polling
Best practices
- Use descriptive parameter names that clearly indicate the data type and purpose
- Always validate parameters inside the workflow before using them in database operations
- Keep API tokens secure — never expose them in frontend code or client-side workflows
- Test backend workflows with sample data in the editor before calling them from external apps
- Log parameter values to a Debug Data Type during development for troubleshooting
- Use Return data from API to send meaningful responses to external callers
- Document your API endpoint parameters for any external developers who will call them
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
I'm building a Bubble.io backend API workflow that needs to accept parameters from both the frontend and external apps. Can you explain how to define parameters, send them from a Schedule API Workflow action, and call the endpoint from Postman with a JSON body?
Create a backend API workflow called process-order that accepts order_id (text), customer_email (text), and total_amount (number) as parameters. Set it up so I can call it from both the frontend and external applications.
Frequently asked questions
What data types can I use for parameters?
Parameters can be text, number, date, yes/no, file, image, geographic address, any custom Data Type (passed as Unique ID), or Option Set values.
Can I pass a list as a parameter?
Yes. When defining the parameter, check the is a list option. In the JSON body, pass the list as a JSON array. From the frontend, pass a list of values.
How do I find my API token?
Go to Settings → API tab. Your API token is displayed there. Use it as a Bearer token in the Authorization header for external calls.
What happens if I send extra parameters not defined in the workflow?
Bubble ignores parameters that are not defined in the workflow. They do not cause errors but are not accessible inside the workflow.
Can I make parameters optional?
Yes. Parameters without values are treated as empty or null. Add conditions in your workflow to handle cases where a parameter might be empty.
Is there a limit on the number of parameters?
There is no documented hard limit, but keeping parameters under 20 per workflow is recommended for maintainability. For complex data, consider passing a single JSON text parameter and parsing it inside the workflow. RapidDev can help architect complex API workflows for enterprise integrations.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation