API integration

Users with access to a specific Offer can view its details together with allowed propagation options (Link, iFrame, API).

For each Offer with API propagation enabled, PalDock automatically generates API documentation for affiliates (in Offer preview → API). The documentation is derived directly from the Form Structure where input fields are defined. This makes it possible to generate and maintain API specs automatically, so partners can both read and test the integration before development.

PalDock uses a single endpoint for all requests and workspaces. The offer and the structure are given as query parameters, so you do not need different endpoints for different tenants or offers. With the Global Fields feature, the payload format stays almost the same across all offers, except when you add custom fields.

This setup makes things much easier. Affiliates can run many Offers, even from different workspaces, using just one endpoint. There is no need to handle lots of different URLs and integrations. The PalDock API works the same way everywhere, so integrations are simple and consistent. Thanks to this, integrations are quick and affiliates can start sending their first leads on the very same day they are onboarded.

The endpoint

POST https://api.paldock.com/api/{tenant}/conversions/api?o={offer_id}&structure={structure_id}

• o – the offer the lead belongs to.
• structure – the form structure the payload follows.

Both values, along with the affiliate’s API token, are in Offer preview → API, where the affiliate can also read the generated documentation and test a request before writing any code.

Response codes

• 200 – the lead was created. See the response fields below.
• 202 – the lead was created and the detailed breakdown is included. See External Final Page.
• 403 – the API token is not valid.
• 404 – no pingtree was found for the given offer and structure.
• 406 – the lead was rejected. See Refuse leads.
• 422 – the payload or the query parameters did not validate.

Process after Lead Submission

When a lead is submitted, the response includes url. The affiliate’s frontend should send the customer there right away.

That URL is the Internal Final Page, https://portal.paldock.com/{tenant}/processes/{process_id}. The page waits for the lead to finish processing and then shows the internal screens (verification, thank-you page, final page) or redirects onward, depending on how the Offer is configured.

Depending on the Admin configuration, PalDock supports two response modes:

Basic Response – status and URL only.

{
  "process_id": "a1feecc3-dcaf-470b-9b54-f1bdbdeff9dc",
  "url": "https://portal.paldock.com/tenant/processes/a1feecc3-dcaf-470b-9b54-f1bdbdeff9dc",
  "origin_id": "1234",
  "status": "pending"
}

Detailed Response – full breakdown of how the lead was processed across pingtree channels. See External Final Page.

Response fields

• process_id – identifies the lead in PalDock. Use it when you ask for the status later, and in the Internal Final Page URL.
• url – where to send the customer next.
• eid and origin_id – the tracking identifier for this lead. It is the same value the affiliate link carries as pcid. See Conversion IDs explained.
• status – pending, approved or rejected.

Three older field names are still returned and mean exactly the same as their replacements: id for process_id, external_id for eid, and redirect_url for url. They are kept so existing integrations keep working and will be removed in a future version. Build new integrations on process_id, eid and url.

API Parameters

The most common parameters used in PalDock are:

• affcid – a custom click identifier provided by the affiliate.
• affs1 to affs10 – custom fields where affiliates can pass their own IDs or values for tracking and reporting.
• external_redirect_url – an alternative URL where the user should be sent after submission. Must be URL-encoded. The External Final Page feature must be enabled.
• external_redirect_url_results – whether that page receives the full breakdown or only the basic result. True by default.
• test – marks the lead as a test so it will not be processed as a standard lead.
• sync – holds the response until the lead has been evaluated. The Refuse leads feature must be enabled. See below.
• status_url – a URL PalDock calls when the lead status changes. See below.

external_redirect_url can carry placeholders that PalDock fills in: {process_id}, {affiliate_id}, and {data_<field_name>} for any field in the structure. So https://yourdomain.com/result?pid={process_id} arrives at your page with the identifier already in it.

Tracking Lead Status (Approved or Rejected)

When an affiliate sends a lead into PalDock, they may want to know whether it was approved or rejected. PalDock provides three ways to find out.

Enable the Refuse leads feature in Offer settings to use any of them.

1. Synchronous response, recommended

If the affiliate includes sync=1, PalDock holds the response until the offer evaluation is complete, instead of answering straight away with pending.

• This can take several minutes, depending on the offer logic.
• Affiliates must configure a sufficiently long timeout on their side.

Although simple, it is the most effective solution.

2. Automatic S2S postback

Include status_url in the request. PalDock then calls that URL whenever the lead status changes, with the same payload as the standard response.

Request:

{
  "first_name": "John",
  "last_name": "Doe",
  "status_url": "https://affiliate.com/postback/lead-status"
}

Postback sent by PalDock:

{
  "process_id": "9e886baa-6804-4dfe-baf9-a065b66d7f87",
  "status": "approved",
  "url": "https://portal.paldock.com/tenant/processes/9e886baa-6804-4dfe-baf9-a065b66d7f87"
}

No repeated polling, minimal delay, automatic updates.

3. Polling endpoint, not recommended

The affiliate can repeatedly ask for the current state using the process_id from the initial response.

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

The response has the same shape as the one above.

⚠️ This means calling the endpoint every few seconds until the status changes, which creates unnecessary load on both sides. We do not recommend it in production.

API Features

• Data feeds – responses can include a feed_id to match against external data feeds, for example logos, names, or additional attributes. The response may also override certain fields from the data feed for a specific lead. This is useful in cases such as mortgages, where an individual customer might receive a dedicated interest rate. For full details, see Data feeds.