How to Submit a Lead

TSL Ping Tree > How To

How to Submit a Lead

All form submissions must use System Parameter pt=PING_TREE_ID to specify a Ping Tree to run.  In addition, if our Get Click or Click Thru services were used to start a Click prior to the Submit (as is the case for a "Front Site" as documented in the How To Start a Click help article) then pass us c=CLICK_ID as well; you will have stored this in a session or a cookie or used some other state management technique to keep that value alive.  If on the other hand you do not have a Click ID handy then System Parameter p=PROMOTION_ID will be required.  There are other optional System Parameters that can be supplied for tracking or to override some ping tree configuration items; they will be described below.  Beyond this the Form Field parameters for the Form that you have tied to the Ping Tree are to be supplied.

Leads are posted to the following URL.  The HTTP POST method is suggested for all scenarios but GET is also supported unless you specifically configure your Ping Tree to ignore QueryString (i.e. the HTTP GET protocol).

When posting from a web site this URL will be the ACTION attribute of your FORM tag (and attribute METHOD is suggested to be set to POST).  Any System Parameters supplied from a FORM tag should be done via <INPUT TYPE='HIDDEN' ... > tags.

    http(s)://YOURSUBDOMAIN.tslpingtree.net/submit.ashx

Submit.ashx Parameters

Main parameters:

pt = Ping Tree ID – This is the required Ping Tree ID.

ip = Visitor IP Address – Capture the visitor's IP Address and pass it along to our network to avoid duplicate Click IDs when you are keeping track of our Click ID via your own session management techniques.  If you are using an HTML <form ...> tag to post directly to our network's submit.ashx handler then you may omit this parameter and we will default this value to the IP Address of the HTTP request itself.

c = Click ID – If you used either our Get Click or Click Thru service then supply the resulting ClickId to continue the visit.  Otherwise you must supply the p = Promotion ID parameter and any of the other following optional parameters.  Note that ClickId can be supplied via our VERY STICKY tracking cookies instead of being posted via the c= System Parameter.  Once a tracking cookie is set the site, promotion, affiliate, and other System Parameters that follow in the indented section below CAN'T BE CHANGED until the cookie is deleted or it expires.  This only applies to browser sessions; when you or your affiliates post directly to your TSL Ping Tree submit URL and receive XML responses no cookies are involved.  It is however possible to have multiple cookies for different sites at once which is why always setting a s=SITE_ID value is important when working with our tracking cookies; by posting the correct Site ID value in each submit you give our network a way to know which tracking cookie trumps all of the others.
    s = Site ID – A recommended but optional 36 character ID that distinguishes the source of the visitor.  Any alphanumeric value is valid but the recommendation is to use the domain name of a website without "http" such that if pasted into a web browser one would see the source website where the visitor completed the form.

    p = Promotion ID – A required 36 character ID that corresponds to a promotion that you have configured via the TSL Ping Tree website. Promotions determine landing pages and/or payout terms.

    a = Affiliate ID – An optional 36 character ID that distinguishes the party that is to be paid for any traffic conversions. Any alphanumeric value is valid and reports are available to determine payout amounts by Affiliate ID.

    s1, s2, & s3 = Sub IDs – Optional 36 character IDs that you or your affiliates can use to identify search keywords, IDs from third party tracking systems, e.g.

Optional parameters:
    w = Maximum Wait Seconds – Allows the caller to request that the Ping Tree runs at most this many seconds. A best effort is made to honor this request.

    m = Minimum PayoutONLY for a promotion that pays a percentage of revenue and a ping tree that allows at most 1 accept, allows the caller to require that at least this amount must be earned as a payout in order for the lead to get an overall Accept disposition. This allows you to implement a revenue share ping tree for an exclusive type of lead and have your affiliates decide their own tiers instead of you having to make multiple ping trees to implement tiers.

    k = Affiliate/Promotion Authentication Key – Will be made part of our internal affiliate module in a future release.  Today it can be used as just a regular parameter that you can use in filter rules, e.g.

If you like the following settings per the specified Ping Tree configuration then you need not change them here but you may if you wish.  The reason that these overrides are available is mainly so that you can use one Ping Tree for multiple Promotions instead of having to make a copy of a Ping Tree just to change these settings; that would give you a dual maintenance problem which would be unproductive to maintain.
    rfmt = Response Format – Use X for XML and R for Redirect.

    AcceptRedirectUrl – If your lead buyer does not supply a redirect URL then this URL will be used. Token Substitution may be used in the URL.

    DeclineRedirectUrl – only applies to the Redirect response format. This URL will be the supplied redirect URL if there are no error but no lead buyers accept. Token Substitution may be used in the URL.

    ErrorPostErrors – T/F: Do you want to communicate errors when not accepted (versus a decline)? Applies to the Redirect response format only.

    ErrorRedirectUrl – Only applies to the Redirect response format when ErrorPostErrors=T. This URL will be the supplied redirect URL if the form submission has errors. Token Substitution may be used in the URL. If you do not supply a URL here then a default error page will be generated for you which discloses the errors and instructs the user to hit the back button to make corrections.

    ErrorListParameter – Only applies to the Redirect response format when ErrorPostErrors=T. This parameter will be added to the ErrorRedirectUrl URL to communicate any form submission errors; its value will be the errors in the format specified by ErrorListType.

    ErrorPostFormFields – Only applies to the Redirect response format when ErrorPostErrors=T and ErrorListParameter is set. T/F: Do you want both the error messages and the form field names that caused the errors to be returned as part of the value for the ErrorListParameter?

    ErrorListType – Only applies to the Redirect response format when ErrorPostErrors=T and ErrorListParameter is set. This setting determines the format of form submission errors that are supplied to the ErrorRedirectUrl for a form submission that has errors.

      H = HTML List Items – e.g. <LI>first_error</LI><LI>second_error</LI> Note that the content is doubly URL encoded.

      T = Tab Delimited – e.g. first_error{tab}second_error   Note that the content is doubly URL encoded.

      N = None (default)

Submit.ashx XML Responses

The XML responses will be structured as follows and no cookies will be returned.

Accept

You will get all of the tags shown below 100% of the time for an accept except for...

... Redirect which only returns if the ping tree accept returns a redirect URL.  Notice that it passes through TSL Ping Tree for tracking purposes.

... PayoutId and PayoutAmount which only occur if the conditions defined for the promotion to trigger a payout are met.

... Pixel which only occurs if a payout occurs and if the promotion also defines a pixel.  It is the responsibility of the caller to fire this pixel.  TSL Ping Tree will not have done so.  If you have a Thank You page then simply place the XML-decoded contents of this pixel on that page.  If you are doing a redirect to an external website then you will need to do something else with the pixel before the redirect.  If you need help with ways to do so please contact us.

<Response>

    <Id>b0040d4b-1bc3-4151-8b3f-a6e971336959</Id>

    <Disposition>Accept</Disposition>

    <Redirect>http(s)://YOURSUBDOMAIN.tslpingtree.net/redirect.ashx?url=1.9z9wEz060ihwjoucwZhwrNaTJ1EYXXAZyMZ9hb-lxjY7hKaMJMcnYkU-Zy0ijhba3XtugwxBlj9IioyBSHufp_xg4AEMTARabY1B7ztMB_BA-Xao0UsmAoaOeDCgY0COOXTSqPNCzpnR1Lx4PCJFyCGrSaRwX9Xs2OLBNkMGz_FA5pjzuO2reLIqxSCTAuiU</Redirect>

    <PayoutId>CA0AD53C-E330-4066-996B-884A94A1754B</PayoutId>

    <Payout>0.40</Payout>

    <Pixel>&lt;img src=blah&gt;</Pixel>

</Response>


Decline

You will get all of the tags shown below 100% of the time for a decline.

<Response>

    <Id>b0040d4b-1bc3-4151-8b3f-a6e971336959</Id>

    <Disposition>Decline</Disposition>

</Response>


Error

You will get General Errors and/or Field Errors for every error response however the number of errors and the messages returned will vary based on your field validations, filters, etc.

<Response>

    <Id>b0040d4b-1bc3-4151-8b3f-a6e971336959</Id>

    <Disposition>Error</Disposition>

    <GeneralErrors>

        <GeneralError>PromotionId is required</GeneralError>

    </GeneralErrors>

    <FieldErrors>

        <FieldError>
            <Field>FirstName</Field>
            <Message>First Name is required</Message>
        </FieldError>

        <FieldError>
            <Field>LastName</Field>
            <Message>Last Name is required</Message>
        </FieldError>

    </FieldErrors>

</Response>


See also: