External Data Flow

Type: Explanation | Audience: Interface builder user with backend curiosity | Goal: Understand how a view loads data from your endpoint, why some modes skip the fetch, and how Pipedrive data and your custom data are sequenced

Three modes, three behaviours

Where the view is opened decides whether the endpoint is called at all:

Mode	Custom URL triggered?	Custom data source comes from
Live rendering (what real Pipedrive users see)	Yes	The endpoint, called in real time.
Test mode (Test button in the builder)	Yes	The endpoint, called every time you click Load Data (or on view open if Autoload is on). The URL can be temporarily overridden in Test settings without saving.
Preview mode (Preview button in the builder)	No	The saved Sample data in the interface.

Test and live rendering share the same loading flow. Preview is intentionally separate so you can iterate on layout against a frozen JSON without spamming the endpoint.

What happens on view open (Test / live rendering)

When the view opens, two work streams run in parallel so total wait time is the slower of the two, not their sum.

Why parallel

If the URL is purely static — https://api.example.com/dashboard — the custom data fetch starts immediately and runs alongside the Pipedrive fetch. Total wait is the slower of the two.

If the URL contains a Pipedrive placeholder — https://api.example.com/orgs/{{organization.id}}/dashboard — the custom fetch can't start until the Pipedrive fetch has resolved the placeholder. The custom flow parks itself until Pipedrive is ready, then proceeds.

Why polling instead of a direct fetch

The browser doesn't call your endpoint. The Interface Builder server does — that's how the OneClick metadata and headers stay server-side. The flow:

1. Browser asks the Interface Builder server to call the endpoint.
2. The server calls your URL with the configured method, headers, and body.
3. Response body is written to a temporary store keyed by the event ID.
4. Browser polls the store every 1 second until the response is ready — or until ~20 seconds have passed.

The 20-second cap is a UI budget, not a server timeout. If your endpoint takes 60 seconds, the server still waits and writes the response — but the user has already seen the timeout toast and the view has rendered without custom data.

How the URL and headers are processed

Before the request goes out, the URL string passes through the full Data Picker substitution (client-side), with sources deal, organization, person, user (from the Pipedrive fetch), variables, searchparams (the browser's current URL), system (the four Context tab values), and view (a View reference, which resolves to the id of another view of the same button). After substitution, the search parameters from the browser URL are appended to the request URL so navigation context survives.

On a floating window button the deal, organization and person sources have nothing to substitute and system carries only company_id and user_id, because that button's views get no Pipedrive record.

Header values go through the same client-side substitution, so a header can carry any Data Picker source the URL can. The already-substituted headers are what reach the server. The server then fills in what is left, which is * and nothing else: a confidential variable never leaves the server in the first place, so it stays a placeholder until that point. Any other placeholder still unresolved when the server sees it becomes an empty string. The same is true of URL button POSTs and form submissions.

A view source is the one that does not resolve the same everywhere. The builder, the Preview and the Test view hold the button's view list, so a reference to a view that has since been deleted resolves to an empty string and the broken link is visible in a test run. The rendered view loads only itself, so it cannot tell a live reference from a stale one and resolves both to the stored id — a working link resolving to nothing would be the worse failure.

The builder warns with a toast in two cases:

• Whitespace in path — when the processed URL contains %20 in its path. Usually means a placeholder resolved to an empty value.
• Invalid URL — when the processed URL fails to parse.

The request is sent either way; the toast is just a hint.

Test-mode specifics

Test mode shares the loading flow with live rendering but adds these twists:

• Manual trigger. When Autoload is off, the view sits idle until you click Load Data.
• URL override. The Test settings sidebar lets you change the URL without saving the view. The override is applied just before the request goes out, so the URL stored on the view stays untouched.
• Live updates. Edit the override URL in the Test sidebar and the next load picks it up.
• Sample data is Preview-only. Test mode never renders against Sample data -- it always uses what the live data source actually returns. Test and Preview can therefore disagree in three cases: the View URL toggle is off, the URL is missing or broken, or the endpoint returns a payload whose shape differs from your saved Sample data. Switch to Preview when you want to see how Sample data renders against your current layout.

Live rendering has no manual trigger; loading starts immediately on view open.

Preview-mode specifics

Preview never calls your endpoint. Instead it:

1. Reads the saved Sample data for the view.
2. Fetches Pipedrive context the same way the other modes do.
3. Merges the two into the view and renders.

That means:

• A view with a configured URL but no Sample data shows empty * placeholders in Preview.
• Updating the saved Sample data is the only way to change what Preview renders for *.
• A request to your endpoint never leaves the builder while you're in Preview.

See the Saving page for why Sample data behaves like a frozen production response.

What ends up in the rendered view

After both fetches finish, the runtime assembles the data layer every block reads:

Source	Comes from	Placeholders
Pipedrive context	Pipedrive fetch	*, *, *, *
Custom data	Endpoint response (live / Test) or saved Sample data (Preview)	*
Variables	Interface variables	*
Search params	Current browser URL	*

When something goes wrong

Outcome	What the user sees
Endpoint returned oneclick_data.error_message or oneclick_data.message_view	Full-page message view with title + body, Go Back and Retry buttons. The body can be a bullet list, and variant sets the colours and icon of the card; see HTTP Response Format.
Endpoint returned oneclick_data.redirect_view to a valid view	Brief "Redirecting…" toast, then navigation.
Endpoint returned oneclick_data.redirect_view to a missing view	Full-page message view: View with ID … was not found.
Endpoint returned non-2xx HTTP status	Data loading failed (status N) toast plus whatever body came back.
Endpoint took longer than 20 s	Request timed out. No custom data received. toast, view renders without custom data.
Network error during the fetch itself	Full-page message view with the underlying error message.