Connection Creator in Integration

An integration scenario sends a lead to an advertiser and processes the answer. It starts when a lead reaches an offer, either directly or through a pingtree.

Everything else on this page is a variation on the same three steps: put the data in the shape the advertiser wants, send it, and read the answer.

One integration is one advertiser and one channel

An integration covers a single advertiser through a single channel. That matters because the same advertiser usually appears in your pingtree more than once, and each of those channels is its own integration.

They are duplicates. The scenario, the nodes and the mapping are identical, and the only thing that differs is a value: a different token, and with it a different price for the lead. Buying at one price is one channel, buying at another is a second channel with a second token.

So build the integration once, get it working, then duplicate it per channel and change the credentials. Do not rebuild the logic each time, because then a fix has to be made in several places and eventually will not be.

In an auction, the integration must return {price}. The pingtree needs it to compare bids and decide who wins. Without it, the integration cannot take part in an auction at all. Store it from the ping response the same way you store anything else.

The two flows

A Start node has a flow. In integrations there are two, and each is a separate path with its own Start and its own End.

• Ping asks whether the advertiser wants the lead, and at what price. Nothing is created on their side.
• Post actually submits the lead.

Never connect them. They are two flows on one canvas, not two halves of one flow.

Not every advertiser needs both. If they only accept submissions, build the Post flow and leave it at that. If they support a pre-check, the ping usually calls a lighter endpoint and only needs to answer one question: yes or no.

Some advertisers add a third step, where the lead has to be confirmed by a code sent to the customer. That gets its own Start node too. See Verification below.

What the scenario has to give back

Sending the lead is half the job. The answer has to be stored, or the lead is delivered and then lost.

Two values matter almost every time:

• {external_id}, the advertiser’s own ID for the lead. Without it you cannot match a later postback, so the conversion never gets confirmed.
• {redirect_url}, where the customer goes next, if the advertiser hands back a link.

Store them with a Set node placed after the HTTP node, reading straight from the response, for example {external_id} = {parsedBody.leadId}.

The simplest integration

One flow, four nodes:

1. Start, flow Post.
2. Modify to put the data in the advertiser’s shape.
3. HTTP, a POST with the lead in the body.
4. Set to store the response, then End, success.

The condition sits on the connection leaving the HTTP node. It is what decides whether the lead was accepted, so make it specific:

{status}                        equals    201
{parsedBody.status.message}     contains  Created

All conditions on one connection must be true for it to be followed. Checking the status code alone is the single most common reason an integration reports accepted leads the advertiser never received.

Preparing the data

The Modify Field node before the request does the unglamorous work. Four things come up constantly.

Translating values. Your form stores full-time, the advertiser expects employed, or 1, or EMPLOYMENT. One Modify Field node holds all of these mappings, one section per field. This is why the node exists: keep the translation in one visible place instead of burying it in the request body.

Capping values. The advertiser accepts loans up to a maximum, and your form allows more. Replace anything above the limit with the limit, rather than sending a value that will be rejected.

Filling required fields that are empty. Some advertisers reject a request outright when a field is missing, even when the field is irrelevant. Replace the empty value with a placeholder.

Reformatting. Adding an international prefix to a phone number, changing a date format, splitting or joining values.

Authentication

Three patterns cover almost everything.

A static token goes straight in a header or a query parameter as {token}. Nothing to build.

Basic auth needs the credentials joined and encoded first. A Set node builds the string, then a Modify Field node applies to-base64, and the result goes into the header as Basic {auth}.

A token you have to fetch needs its own request before the real one. The Post flow starts with an HTTP node calling the auth endpoint, a Set node stores {token} from the response, and only then does the flow continue to the actual submission. Put a condition on the connection so the flow only continues when a token actually came back.

If the advertiser requires signed requests, use the Signature setting on the HTTP node rather than building the signature yourself.

When the advertiser does not answer immediately

Plenty of advertisers accept the lead, then take a few seconds to decide anything useful. There are two ways to handle it.

Poll them. Add a Wait node, then an HTTP node that asks for the status, then conditions on the outgoing connections:

• A final positive state continues to the Set node and the End.
• A final negative state goes to an End marked failed.
• Anything else loops back through a Breaker and another Wait.

The Breaker caps the number of attempts, so the flow cannot poll forever. Match the “still waiting” branch with does not match against the known final states, so a state you have never seen lands in the retry loop instead of falling through.

Let them call you. If the advertiser sends a callback, use a Webhook node. The flow pauses there and continues when the call arrives, which is cheaper than polling and usually faster.

A webhook can deliver several kinds of event, so branch on what arrived. Conditions on the connections leaving the node read the values from the callback, and each kind of event goes its own way. Give the webhook its own retry path as well, through a Wait and a Breaker, so a callback that never comes does not leave the flow hanging until the timeout.

Remember that the customer is often sitting on a loading screen while all of this happens. See Limits and timeouts.

More than one request

Some advertisers need a sequence: submit the lead, ask for the offer, accept the offer, then ask again to confirm it was accepted. Each of those is another HTTP node, chained with conditions between them.

Two things keep this manageable:

• Store the ID from the first response into {external_id} immediately, because every later request needs it in the URL.
• Give each step its own condition. If you only check the last response, you will not know which step actually failed.

Once the sequence is more than three requests long, it is worth asking the advertiser whether there is a simpler endpoint. Often there is.

Verification

Some advertisers confirm the lead with a code sent to the customer by SMS. This runs as its own flow with its own Start node.

The pattern is:

1. In the Post flow, store whatever identifies the pending verification, for example the token ID and the token code returned by the advertiser.
2. In the verification flow, send those back together with the code the customer typed, available as {code}.
3. On success, store {redirect_url} and end.

The two flows are connected by the values stored in the first one, not by a line on the canvas.

Ending the flow

Every path should reach an End node, and the End node decides how the lead is recorded.

• Success means the advertiser took the lead.
• Failed means they did not.

A rejection is a normal outcome, not an error. Give it a reason so it shows up usefully in reporting, rather than landing in Error along with genuine breakages. See Reject reason.

Common mistakes

• Treating any 2xx status as acceptance.
• Not storing {external_id}, so postbacks can never be matched.
• Not storing {price} in an integration meant for an auction, so it cannot bid.
• Rebuilding the logic for each channel instead of duplicating the integration and changing the credentials.
• Translating values inside the HTTP body instead of in Modify Field, which makes a wrong value impossible to trace.
• Connecting the Ping and Post flows.
• A polling loop with no Breaker.
• Leaving a branch without an End node, so the lead ends up in neither result.