External Final Page

The External Final Page feature lets partners, or you yourself, replace the internal PalDock Final Page with their own page. Use it to keep control of the branding, to show PalDock results alongside your own offers, or to build the results into a comparison site.

It works with both API and iFrame submissions. Admins decide whether to enable it for API only, iFrame only, or both.

The flow, once

Whatever else you configure, this part never changes:

• A lead is created. The response contains process_id and url.
• url always points to the Internal Final Page, https://portal.paldock.com/{tenant}/processes/{process_id}. It never points at your page.
• The customer goes there. From an iframe this happens automatically, from the API your frontend does it.
• The Internal Final Page redirects onward to your external page.
• Your page reads the result and renders it.

Everything below only changes when step 4 happens and how you get the data in step 5.

What you configure

Six settings on the offer, plus three parameters on the request. They are independent, and confusing them is the usual reason an integration behaves unexpectedly.

On the offer:

• External Final Page – turns the feature on, and for which submission methods.
• Default External Final Page – the URL every partner is sent to, unless excluded.
• Skip internal loader and redirect immediately – whether PalDock’s loader waits for the pingtree or hands over straight away.
• Include results in redirect – whether the results travel in your page’s URL as query parameters.
• Partners with Override & Detailed Response – which partners may send their own URL and receive the detailed response immediately.
• Partners without Default External Final Page – which partners are excluded from the default URL.

On the request:

• sync=1 – the API call waits for the pingtree instead of answering immediately.
• external_redirect_url – your own URL, instead of the default. Requires the override permission.
• external_redirect_url_results – full channel detail, or just status and type. True by default.

Four of the six offer settings are outside the partner’s control, so a partner cannot fix a missing loader or missing query parameters on their own side.

Two setups that work

A. Let PalDock wait. Skip internal loader disabled, Include results in redirect enabled.

The Internal Final Page holds the customer on its loader until the pingtree finishes, then redirects to your page with the result already in the query string.

• Your page is static and renders once from the URL.
• No polling and no JavaScript needed for the data.
• The customer looks at a PalDock loader for as long as the pingtree takes.

B. Show your own loader. Skip internal loader enabled.

The Internal Final Page redirects to your page straight away, while the pingtree is still running. Your page shows its own loader and polls until the result is ready.

• The customer is in your branding the whole time.
• You have to handle the waiting state as well as the finished one.

Pick A when your page is rendered server-side. Pick B when the wait is long enough that the customer should spend it looking at your site.

Getting the data

From the query string. With Include results in redirect enabled, the results are appended to your URL as query parameters.

About the lead: process_id, origin_id, status, is_finished, items_total, successful_items. The url field itself is not appended.

About each channel, flattened with the item index in the name: item0_channel_id, item0_channel_name, item0_status and so on, then item1_ for the next channel. Empty values are dropped rather than sent as blanks, so do not rely on every key being present.

By polling the Process API.

GET https://api.paldock.com/api/{tenant}/processes/{process_id}

Watch the status code, because two different objects come back from this endpoint:

• 202 is the External Final Page response, the same object the redirect flattens. Here url holds the resolved external page URL.
• 200 is the internal Final Page response, which has a different shape and is not what you want.

Polling works in both setups, so even in setup A you can poll if Include results in redirect is off.

Knowing when it is finished

is_finished is the only reliable signal.

• false, the pingtree is still running. What you read is a snapshot and channels can still change.
• true, it has reached a terminal state and nothing more will change.

Do not infer this from the statuses. A channel sitting in waiting may still be answered.

If you send sync=1, the API call itself waits for the pingtree, so the response may already carry the finished result and there is nothing to poll for. url still points at the Internal Final Page even then. See API integration.

How much detail you get

external_redirect_url_results controls the shape of items. True by default.

• true, the full array: channel_id, channel_name, status, type, redirect_url, send_id and any exs_1 to exs_5.
• false, a basic array with only status and type.

The value is taken from the request that created the lead and is remembered for that lead. Polling later returns the shape chosen at submission, so you cannot switch it on afterwards.

Use false when your page only needs to know how it went, true whenever you render the channels themselves.

Who gets what

Two lists, and each does something different.

Partners without Default External Final Page decides who gets an external page at all. A partner on this list is not sent to the default page and stays on the internal Final Page. Everyone else goes to the default page.

Partners with Override & Detailed Response does two things:

• The partner may send external_redirect_url and be sent to their own page instead of the default. This is the only way to override the URL. A partner who is not on the list and sends the parameter has it ignored.
• The partner receives the detailed response immediately, in the API response that creates the lead. A partner who is not on the list gets the standard response instead, which carries no items.

The list controls when the detailed data arrives, not whether it can be reached. Any partner with an external page can poll the Process API and get the same items, because the shape there depends only on external_redirect_url_results, which is true by default. Treat the list as a convenience for trusted partners, not as a way to keep channel data private.

The three outcomes:

• On neither list. The partner goes to the Default External Final Page, gets the standard response on creation, and reads the results by polling.
• On the override list. The partner can send their own URL and gets the detailed response straight away.
• On the exclusion list. The partner has no external page and stays on the internal Final Page.

Both lists fail quietly. A partner sending external_redirect_url without the override permission lands on the default page and nothing tells them why, so check the list first when a partner reports the wrong page.

The two lists are independent, so a partner can be on both. Being on the override list does not exempt them from the exclusion list.

The URL and its placeholders

Both the default URL and external_redirect_url support placeholders that PalDock fills in:

• {process_id} – the process ID of this lead.
• {owner_id} – the affiliate the lead is attributed to.
• {data_<field_name>} – any submitted field value, for example {data_first_name}.

Values are URL-encoded when they are inserted. A placeholder that matches nothing is replaced with an empty string rather than left in the URL, so a typo produces a silently missing value instead of an error.

external_redirect_url must be fully URL-encoded, including &, ?, { and } inside the value, so the whole thing is read as one parameter rather than several.

What comes back

About the lead:

• process_id – identifies the lead. Use it for polling.
• url – the Internal Final Page when the lead is created, the resolved external page when polling.
• origin_id – the Origin ID of the click or lead this came from. See Conversion IDs explained.
• status – the overall state, using the same values as the channels below.
• is_finished – whether processing is complete.
• items_total – how many channels the lead reached.
• successful_items – how many accepted it.

About each channel, in items:

• channel_id – the channel’s ID, shown in the pingtree editor. Match on this.
• channel_name – the channel’s visible name.
• status – ok, fail, processing or waiting. See Pingtree Distribution.
• type – the channel’s distribution type: exclusive, non_exclusive, auction or choice.
• redirect_url – where the advertiser wants the customer sent. Empty when the channel did not accept.
• send_id – the Send ID for this one channel. One lead going to five channels produces five Send IDs. Use it to match a later postback to the right channel.
• exs_1 to exs_5 – extra values from the advertiser’s response, where the integration maps them. Only present when the advertiser returned them.

Channels set to Hidden never appear in items, so items_total can be higher than the number of entries you receive.

origin_id and send_id are not the same thing. The Origin ID belongs to the lead and there is one of them. A Send ID belongs to one attempt at one channel, and there is one per item.

Building the page

Match on channel_id. It is stable and visible in the pingtree editor. Names change, IDs do not.

The pattern that works on a comparison site is to prepare a hidden row for every channel in advance, each tagged with its channel ID, and reveal the rows that came back with ok. Your page then needs no logic beyond showing and hiding, and it already has the logos, names and copy, because it is the same data your comparison used before the form.

Alongside the successful channels you can show offers outside the pingtree and display ads. The page is yours.

When there is nothing to compare

If the result has a single item and that channel is Exclusive or uses Priority redirect, there is nothing to compare. Send the customer straight to redirect_url. The redirect flow already does this and skips the external page in that case.

Decide separately what to show when no channel accepted. That page will be seen, and an honest message is better than an empty comparison table.