How to connect an API to Adalo
Adalo connects to a REST API in two ways: a custom action for one-off requests triggered by a button, and an external collection for data users browse, filter and paginate. Send authentication as a header, return a flat JSON array for list endpoints, and honour the offset and limit parameters Adalo sends.
Choosing the wrong one of those two is why API work in Adalo drags on. This guide covers both, plus the response format that decides whether your data appears at all.
Custom action or external collection?
A custom action fires one request when a user taps something, good for writes, payments, emails and one-shot lookups. An external collection is a data source Adalo reads continuously to fill lists and detail screens.
- Users browse, filter or paginate the data → external collection.
- One request, one response, triggered by a button → custom action.
- Both are fine on the same API; they are different tools for different jobs.
The response shape Adalo can read
For list endpoints, return a flat JSON array of objects with identical keys. Adalo infers properties from the first object it sees.
- No envelope: return [...] rather than { "data": [...] } unless you configure the path.
- Flatten nested objects into top-level keys.
- Include optional properties as null instead of omitting them.
- Keep each property a consistent type across every record.
Authentication
Set your API key or bearer token as a header, on the collection or the custom action, so every request carries it.
- Never put keys in the query string; they leak into logs and browser history.
- Anyone can read a query-string key out of a published app.
- Match the header name and prefix exactly as the API documents it.
Pagination and counts
Adalo asks for pages and displays counts based on what your API reports.
- Honour the offset and limit parameters Adalo sends.
- Return an accurate, stable total on every page.
- A shifting total makes lists stop early or show the wrong count.
What is actually happening
Adalo is not a general HTTP client with a scripting layer, it maps the JSON keys it finds straight onto properties.
- There is no place inside Adalo to reshape a response after it arrives.
- Every fix happens on the API side, or in a small layer in front of it.
If you do not have an API yet
External Collections gives you a hosted database whose endpoints already return the shape Adalo expects.
- Flat records, correct pagination and exact counts out of the box.
- Skip building and hosting your own translation layer.
Common mistakes and how to diagnose them
Custom action returns success but nothing changes.
- Likely cause:
- The API accepted the request but the body did not match what it expects.
- Fix:
- Test the exact same body in an API client, then match the key names and types in the action.
401 or 403 from the API.
- Likely cause:
- The key is in the query string, misspelled, or missing the "Bearer " prefix.
- Fix:
- Send it as a header exactly as the API documents it, including capitalisation.
Custom action output cannot be used on the next screen.
- Likely cause:
- The response is nested, so Adalo did not expose the property as an output.
- Fix:
- Return the values you need at the top level of the response object.
Real example: a delivery app with two very different API needs
The same app needed live courier tracking and one-off shipment creation. Tracking became an external collection, a flat list the app polls and filters. Creating a shipment became a custom action on the "Confirm order" button, returning the tracking number as an output that the next screen displayed.
Trying to do the creation through the collection is where builds stall: collections are for reading, actions are for doing.
When you need an Adalo expert
Plenty of Adalo issues are straightforward to fix yourself with the steps above. It usually pays to bring in an experienced Adalo developer when the problem sits deeper in the build:
- The API you need uses OAuth, signed requests or refresh tokens that Adalo cannot handle directly.
- You need to transform or combine responses before Adalo sees them.
- Webhooks have to push data back into your app.
- Requests must be authorised per logged-in user rather than with one shared key.
Related guides
How to set up a custom action in Adalo
Create an Adalo custom action step by step: method, URL, headers, body with magic text, and how to use the response on the next screen.
Adalo external collection not working: common causes and fixes
Missing properties, wrong item counts, empty lists and pagination problems in Adalo external collections, the symptom, the cause and the fix for each.
How to connect an external collection to Adalo
Step-by-step: get a REST endpoint Adalo accepts, add it under Database → External Collection, and bind the properties to your lists and forms.
How to use a WebView component in Adalo
What the Adalo WebView component does, how to pass data in with URL parameters, sizing it correctly, and the limits to design around.
Frequently asked questions
Why does my Adalo external collection show no properties?
The response is almost certainly not a flat JSON array, or the first object omits the properties you expect.
Can I use any REST API with Adalo?
Most, as long as it authenticates with a header you can configure and returns JSON Adalo can read.
Does Adalo support GraphQL?
Not for external collections. Put a small REST wrapper in front of the GraphQL endpoint.
Where do I put my API key?
In a header on the collection or custom action, never in the URL.
Can a custom action run without a user tapping something?
It runs as part of an action chain, so something in the app must trigger it. Scheduled work belongs on your server.
How do I pass the logged-in user to my API?
Use magic text in the action body or URL to send the user's ID, and verify it server-side rather than trusting it.
Webnux Tools is an independent product by Webnux Ltd. It is not affiliated with, endorsed by, or sponsored by Adalo, Inc. Adalo is a trademark of Adalo, Inc.