API Overview

Gaining Access to the API

To gain access to the API you are going to need to get a key... However if you are here, most of the hard work is done. If you have not created a broker, go to the dashboard and do that now. Once this is done you will have a key generated for you.

If you are reading this guide offline, go online and sign up. Alternatively, get in touch and we can do this part for you.

REST Endpoints

We have built the RESTful service using the standard HTTP request protocols. As such HTTP Verbs are used instead of explicit endpoints for service interaction.

Tools to help with integrations

Here are some tools that our tech team use to speed up integrations and to ensure that data is formatted correctly

Send a Lead

Please choose any one of the following method.

  1. Direct Post
  2. Post a lead and poll for status
  3. WCF
1. Direct Post - No Polling Required

Single step process

Direct Post URL: https://api.leadtreeglobal.com/leaddirect/<YOUR API KEY>/
Find out more

If you wish to post a lead and wait for a response, rather then poll. Post the lead to this address using the appropriate Content-Type and Accept headers.

2. Post a lead and poll for status

Step-1: Post Lead

Post URL : https://api.leadtreeglobal.com/<YOUR API KEY>/
Find out more

To submit a lead, create your request as either XML or JSON and POST it to the API remembering to set the content type to either application/xml or application/json. If your lead is submitted successfully you will receive a GUID. Once your lead has been submitted you can start to poll the status check, this will tell you when your lead has been accepted and can be redirected.

XML response

<LeadSubmissionResponse> <LeadId>LD866df8-ge21-4f7e-b178-caf3896b2d44</LeadId> <Errors></Errors> <StatusUrl>/AP866df8-8050-4d5f-ba11-9b53d0fe3547/LD866df8-ge21-4f7e-b178-caf3896b2d44</StatusUrl> </LeadSubmissionResponse>

Json response

{ "leadId": LD866df8-ge21-4f7e-b178-caf3896b2d44, "errors": [], "statusUrl": /AP866df8-8050-4d5f-ba11-9b53d0fe3547/LD866df8-ge21-4f7e-b178-caf3896b2d44 }

Step-2: Get Poll Status

Status check URL :https://api.leadtreeglobal.com/<YOUR API KEY>/<Application GUID>
Find out more

When checking the status of a lead simply perform a GET request on the API, passing your API key followed by the application id (GUID) that you received when you submitted the lead as illustrated above. This part of the API should be polled periodically to get the URL to redirect the customer to.

3. Wcf Post
Service URL: https://api.leadtreeglobal.com/LeadSubmissionService.svc?wsdl

If you are using Microsoft.Net or are more comfortable with WCF services, you can simply use the WSDL to create a service reference.

Get Commission
Commission URL :https://api.leadtreeglobal.com/commission/<YOUR API KEY>/<Application GUID>

You can use this part of the API to integrate what your data is being sold for. We added this for those of you who have accounts teams as diligent as ours is. To get your lead value use the URL structure above. N.B. Some values can be added later so where you may receive 0 initially this may not be the case.

Find out more

Mark CPF Lead As Funded

You can let the API know that you have funded a CPF lead via API call or tracking pixel.

UK API Guide - Leadtree Global Integration Guide

Sending a Lead

This is the meat of the API. This is where you send your data to turn it into money (hopefully). Detailed below are the different sections of the data set, the fields required and the data restrictions.

Headers

Name Value
content-type application/xml
[or]
application/json

Affiliate Details

Field Name Description Type Formats Required Example
AffiliateAPIKey This is the id provided to you when you signed up. Send this to get paid. String (Guid) Required 3899000e-35d8-4995-af4a-431340776557
AffiliateReference This is how you identify leads on your systems String 50 Character limit Required 1000
AffiliateSubReference Id for the SubAffiliate you need to credit with this lead String 50 Character limit Not Required Big Loans
CreationUrl The URL of the website that created the application String 255 Character Limit Not Required
ReferringUrl The URL of the website that referred the application String 255 Character Limit Not Required www.refurl.com/?ref=1234
AffiliateCampaign Defines the campaign that generated the lead for the affiliate to track. String 50 Character limit Not Required WEB

Testing Details

Field Name Description Type Formats Required Example
IsTestLead This should be set to true until the integration has been verified Boolean true | false Not Required false
TestResponseType Passing one of these values will define the API response after data validation has been passed. String (Enum) RejectedByLenders | AcceptedByLender | AcceptedByLenderWithCommission Not Required false

Software Details

Field Name Description Type Formats Required Example
UserAgent The user agent information from the client device String Required Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.1; WOW64; Trident/6.0)
IpAddress IPv4/IPV6 address of the client machine String IPv4/IPV6 Required 255.255.255.0 (OR) 2001:0db8:85a3:0000:0000:8a2e:0370:7334

Customer Details

Field Name Description Type Formats Required Example
Salutation String (Enum) Mr | Mrs | Miss | Ms Required Mr
FirstName String Maximum of 50 chars Required Test
LastName String Maximum of 50 chars Required Lead
DateOfBirthDay String The day part of the date of birth with leading 0 Required 01
DateOfBirthMonth String The month part of the date of birth with leading 0 Required 01
DateOfBirthYear String The year part of the date of birth YYYY Required 1970
MaritalStatus String (Enum) Single | Married | Partner | Divorced | LivingTogether | Separated | Other | Widowed Required Single
IsCarOwner Boolean true | false Not Required true
HasGuarantor Boolean true | false Not Required true
ConsentToCreditSearch Boolean true | false Required true
ConsentToMarketingEmails Boolean true | false Required true
ConsentToMarketingSMS Boolean true | false Required true
MarketingPreferenceConsent Consent from Applicant String Required true
ConsentToTerms Consent from Applicant Boolean true | false Not Required true
ResidentialCostPerMonth Integer Required 50
ResidentialStatus String (Enum) HomeOwner | PrivateTenant | TenantFurnished | TenantUnfurnished | CouncilTenant | LivingWithParents | LivingWithFriends | Other | Unknown Required Other
TypeOfHousing String (Enum) None | Room | Studio | OneBedroom | TwoBedroom | ThreeBedroom | FourPlusBedroom Not Required Other
NumberOfDependants Integer Not Required 0

Bank Details

Field Name Description Type Formats Required Example
BankAccountNumber Applicants bank account number String Required 12345678
BankSortCode Applicants bank sort code String Required 012345
BankCardType String (Enum) Unknown | Unknown | SwitchMaestro | VisaDebit | VisaElectron | MasterCard | MasterCardDebit | None Required VisaDebit
BankName String 50 Character limit Not Required Santander
MonthsAtBank Integer Not Required

Address Details

Field Name Description Type Formats Required Example
HouseName The house name for the applicants address. Either name or number are required. String Required*
HouseNumber The House Number for the applicants address. Either name or number are required. String Required* 01
Street1 String Required A Road
Street2 String Not Required
TownCity String Required A Town
CountyState String Required Dorset
PostCode String Required SO14 1PW
CountryCode String ISO 3166-1 alpha-2 for details see Wikipedia Required GB
MonthsAtAddress Total time in months an applicant has lived at this address String Required 12

Contact Details

Field Name Description Type Formats Required Example
MobilePhoneNumber The mobile number captured for the applicant String Required 07123456789
HomePhoneNumber The landline number for the applicant String Although this is required, if you do not capture landline pass the mobile number to this field Required 01234567890
WorkPhoneNumber The landline number for the applicants place of work. String Not Required, But nice to have. Some lenders will not look at traffic if there is no work number 02234567890
EmailAddress The email address supplied by the applicant String Required tester@tester.com
BestTimeToCall Best time for the customer to be contacted by the lender. String Morning | Afternoon | Evening | Anytime Not Required Afternoon

Loan Details

Field Name Description Type Formats Required Example
LoanAmount Integer Required 500
LoanPurposeType The reason the applicant is requesting a loan String (Enum) Business | CarLease | CarPurchase | DebtConsolidation | EmergencyCash | GuarantorLoan | Holiday | HomeImprovements | LivingExpenses | MedicalBills | Mortgage | OneOffPurchase | Other | Purchase | Unsecured | UtilityBills Required Other
LoanTerm The duration of the loan. String Whole numbers only Required 30
LoanTermType The period type for the loan. String (Enum) Days | Months | Years Required Days

Income and Employment Details

Field Name Description Type Formats Required Example
EmploymentStatus String (Enum) FullTime | PartTime | Temporary | SelfEmployed | Retired | Benefits | ArmedForces | Unemployed | DisabilityBenefits | Student Required FullTime
Occupation String Required Other
EmployerPosition String (Enum) NotApplicable | Administration | Actor | BusinessDevelopment | BusinessOwner | Consultancy | Doctor | Engineering | Firefighter | Management | Marketing | MiniCabDriver | Musician | Nurse | Sales | SeniorManagerDirector | Services | Teacher | TruckDriver | Other Required BusinessDevelopment
EmployerName String Required Some Employer
EmployerPostCode String Required AA01 0AA
MonthsWithEmployer Total time in months an applicant has worked for their current employer String Required 06
EmployerIndustry String (Enum) Accountancy | AdvertisingMedia | BusinessConsultancy | CallcentreOperations | SupermarketRetail | CleaningServices | ComputerServices | Education | Finance | Health | HotelsRestaurantsLeisure | Insurance | Legal | ConstructionManufacturing | CivilService | Publishing | RealEstateProperty | ResearchDevelopment | Retail | Transportation | Military | OtherOfficeBased | OtherNotOfficeBased Required Finance
Income Integer Required 1000
IncomeFrequency String (Enum) Weekly | BiWeekly | Fortnightly | LastDayMonth | LastWorkingDayMonth | SpecificDayOfMonth | TwiceMonthly | FourWeekly | LastFriday | LastThursday | LastWednesday | LastTuesday | LastMonday | Other | Unknown Required LastDayMonth
IncomePaymentType String (Enum) Unknown | None | Cheque | Cash | BankTransfer Required BankTransfer
NextPayDateDay String The day part of the next pay date with leading 0 Required 03
NextPayDateMonth String The month part of the next pay date with leading 0 Required 08
NextPayDateYear String The year part of the next pay date YYYY Required 2019
FollowingPayDateDay String The day part of the following pay date with leading 0 Required 01
FollowingPayDateMonth String The month part of the following pay date with leading 0 Required 09
FollowingPayDateYear String The year part of the following pay date YYYY Required 2019
MonthlyCreditCommitments What the customer is paying for their credit commitments on a monthly basis Integer Not Required 310
MonthlyUtilityExpenses What the customer is paying for their utility bills Integer Required 13
MonthlyTransportExpenses What the customer is paying for their transport bills Integer Required 12
MonthlyFoodExpenses What the customer is paying for their food expenses Integer Required 10
ExpenditureConfirmed The customer has confirmed that they have provided accurate financial information and considered potential future income and outgoings in determining your ability to repay. Boolean Required true
OtherMonthlyOutgoings Other expenses paid by the customer Integer Required 15
CombinedHouseholdIncome The combined household income including the customer's Integer Not Required 1234
AdultsAtAddress The number of adults living at the address Integer Not Required 1, 2, 3
RentSplitWith The number of people rental payments are split between String Not Required 0, 1, 2, 3, 4, 5+
MonthlySecondaryIncome Integer Not Required 1234
MonthlyBenefits Integer Not Required 1234
MonthlyPension Integer Not Required 1234
LoansInLastThreeMonths Integer Not Required 1234
CouncilTax Integer Not Required 1234
HouseholdGoods Integer Not Required 1234
ClothingAndFootwear Integer Not Required 1234
Education Integer Not Required 1234
AlcoholicDrinksAndTobacco Integer Not Required 1234
HealthAndBeauty Integer Not Required 1234
Restaurants Integer Not Required 1234
Recreation Integer Not Required 1234
CommsAndEntertainment Integer Not Required 1234

XML Data Structure

<?xml version="1.0" encoding="utf-8" ?> <LeadSubmission xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <AffiliateApiKey>00000000-0000-0000-0000-000000000001</AffiliateApiKey> <AffiliateReference>2605</AffiliateReference> <AffiliateSubReference>Big Loans</AffiliateSubReference> <AffiliateCampaign>WEB</AffiliateCampaign> <ReferringUrl>www.refurl.com/?ref=1234</ReferringUrl> <CreationUrl>www.CreationUrl.com/?ref=1234</CreationUrl> <UserAgent>Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.1; WOW64; Trident/6.0)</UserAgent> <IpAddress>127.0.0.1</IpAddress> <Salutation>Mr</Salutation> <FirstName>Test</FirstName> <LastName>Lead</LastName> <DateOfBirthDay>1</DateOfBirthDay> <DateOfBirthMonth>1</DateOfBirthMonth> <DateOfBirthYear>1970</DateOfBirthYear> <MaritalStatus>Single</MaritalStatus> <IsCarOwner>true</IsCarOwner> <ConsentToCreditSearch>true</ConsentToCreditSearch> <ConsentToMarketingEmails>true</ConsentToMarketingEmails> <ConsentToMarketingSMS>false</ConsentToMarketingSMS> <MarketingPreferenceConsent>Consent</MarketingPreferenceConsent> <ConsentToTerms>true</ConsentToTerms> <ResidentialCostPerMonth>50</ResidentialCostPerMonth> <ResidentialStatus>Other</ResidentialStatus> <NumberOfDependants>0</NumberOfDependants> <BankAccountNumber>12345678</BankAccountNumber> <BankSortCode>012345</BankSortCode> <BankName>First Bank</BankName> <MonthsAtBank>13</MonthsAtBank> <BankCardType>VisaDebit</BankCardType> <HouseNumber>1</HouseNumber> <Street1>A Road</Street1> <Street2>A sub road</Street2> <TownCity>A Town</TownCity> <CountyState>Dorset</CountyState> <PostCode>SO14 1PW</PostCode> <CountryCode>GB</CountryCode> <MonthsAtAddress>12</MonthsAtAddress> <MobilePhoneNumber>07123456789</MobilePhoneNumber> <HomePhoneNumber>01234567890</HomePhoneNumber> <WorkPhoneNumber>02234567890</WorkPhoneNumber> <EmailAddress>tester@tester.com</EmailAddress> <BestTimeToCall>Afternoon</BestTimeToCall> <LoanAmount>500</LoanAmount> <LoanPurposeType>Other</LoanPurposeType> <LoanTerm>30</LoanTerm> <LoanTermType>Days</LoanTermType> <EmploymentStatus>FullTime</EmploymentStatus> <Occupation>Other</Occupation> <EmployerPosition>BusinessDevelopment</EmployerPosition> <EmployerName>Some Employer</EmployerName> <EmployerPostCode>AA01 0AA</EmployerPostCode> <MonthsWithEmployer>6</MonthsWithEmployer> <EmployerIndustry>Finance</EmployerIndustry> <Income>1000</Income> <IncomeFrequency>LastDayMonth</IncomeFrequency> <IncomePaymentType>BankTransfer</IncomePaymentType> <NextPayDateDay>3</NextPayDateDay> <NextPayDateMonth>8</NextPayDateMonth> <NextPayDateYear>2015</NextPayDateYear> <FollowingPayDateDay>1</FollowingPayDateDay> <FollowingPayDateMonth>9</FollowingPayDateMonth> <FollowingPayDateYear>2015</FollowingPayDateYear> <MonthlyCreditCommitments>310</MonthlyCreditCommitments> <MonthlyUtilityExpenses>13</MonthlyUtilityExpenses> <MonthlyTransportExpenses>12</MonthlyTransportExpenses> <MonthlyFoodExpenses>10</MonthlyFoodExpenses> <ExpenditureConfirmed>true</ExpenditureConfirmed> <OtherMonthlyOutgoings>15</OtherMonthlyOutgoings> <CombinedHouseholdIncome>1234</CombinedHouseholdIncome> <AdultsAtAddress>2</AdultsAtAddress> <MonthlySecondaryIncome>1234</MonthlySecondaryIncome> <MonthlyBenefits>1234</MonthlyBenefits> <MonthlyPension>1234</MonthlyPension> <LoansInLastThreeMonths>1234</LoansInLastThreeMonths> <CouncilTax>1234</CouncilTax> <HouseholdGoods>1234</HouseholdGoods> <ClothingAndFootwear>1234</ClothingAndFootwear> <Education>1234</Education> <AlcoholicDrinksAndTobacco>1234</AlcoholicDrinksAndTobacco> <HealthAndBeauty>1234</HealthAndBeauty> <Restaurants>1234</Restaurants> <Recreation>1234</Recreation> <CommsAndEntertainment>1234</CommsAndEntertainment> <IsTestLead>true</IsTestLead> <TestResponseType>AcceptedByLender</TestResponseType> <TypeOfHousing>TwoBedroom</TypeOfHousing> <RentSplitWith>1</RentSplitWith> </LeadSubmission>

JSON Data Structure

{ "AffiliateApiKey": "00000000-0000-0000-0000-000000000001", "AffiliateReference": "2605", "AffiliateSubReference": "Big Loans", "AffiliateCampaign": "WEB", "ReferringUrl": "www.refurl.com/?ref=1234", "CreationUrl": "www.CreationUrl.com/?ref=1234", "UserAgent": "Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.1; WOW64; Trident/6.0)", "IpAddress": "127.0.0.1", "Salutation": "Mr", "FirstName": "Test", "LastName": "Lead", "DateOfBirthDay": "1", "DateOfBirthMonth": "1", "DateOfBirthYear": "1970", "MaritalStatus": "Single", "IsCarOwner": "true", "ConsentToCreditSearch": "true", "ConsentToMarketingEmails": "true", "ConsentToMarketingSMS": "false", "MarketingPreferenceConsent": "Consent", "ConsentToTerms": "true", "ResidentialCostPerMonth": "50", "ResidentialStatus": "Other", "NumberOfDependants": "0", "BankAccountNumber": "12345678", "BankSortCode": "012345", "BankName": "First Bank", "BankCardType": "Visa", "MonthsAtBank" : "13", "HouseNumber": "1", "Street1": "A Road", "Street2": "A Sub Road", "TownCity": "A Town", "CountyState": "Dorset", "PostCode": "SO14 1PW", "CountryCode": "GB", "MonthsAtAddress": "12", "MobilePhoneNumber": "07123456789", "HomePhoneNumber": "01234567890", "WorkPhoneNumber": "02234567890", "EmailAddress": "tester@tester.com", "BestTimeToCall": "Afternoon", "LoanAmount": "500", "LoanPurposeType": "Other", "LoanTerm": "30", "LoanTermType": "Days", "EmploymentStatus": "FullTime", "Occupation": "Other", "EmployerPosition": "BusinessDevelopment", "EmployerName": "Some Employer", "EmployerPostCode": "AA01 0AA", "MonthsWithEmployer": "6", "EmployerIndustry": "Finance", "Income": "1000", "IncomeFrequency": "LastDayMonth", "IncomePaymentType": "BankTransfer", "NextPayDateDay": "3", "NextPayDateMonth": "8", "NextPayDateYear": "2015", "FollowingPayDateDay": "1", "FollowingPayDateMonth": "9", "FollowingPayDateYear": "2015", "MonthlyCreditCommitments": "310", "MonthlyUtilityExpenses": "13", "MonthlyTransportExpenses": "12", "MonthlyFoodExpenses": "10", "ExpenditureConfirmed": "true", "OtherMonthlyOutgoings": "15", "CombinedHouseholdIncome": "1234", "AdultsAtAddress": "2", "MonthlySecondaryIncome": "1234", "MonthlyBenefits": "1234", "MonthlyPension": "1234", "LoansInLastThreeMonths": "1234", "CouncilTax": "1234", "HouseholdGoods": "1234", "ClothingAndFootwear": "1234", "Education": "1234", "AlcoholicDrinksAndTobacco": "1234", "HealthAndBeauty": "1234", "Restaurants": "1234", "Recreation": "1234", "CommsAndEntertainment": "1234", "IsTestLead": "true", "TestResponseType":"AcceptedByLender", "TypeOfHousing": "TwoBedroom", "RentSplitWith": "1", "HasGuarantor" : "true" }

Sample Code

Here are some code samples built using common and contemporary techniques and languages.

using System; using System.Linq; using System.Text; using Your.Company.Namespace.LTGServiceReference; using DJS.PTG.API.WcfTestConsole.LTGServiceReference; namespace Your.Company.Namespace { public class LTGWCFSample { //As this is a sample the API key has been set as a Const. Ideally this would be a configuration item. private const string apiKey = "00000000-0000-0000-0000-000000000001"; //The return type for the example is an Guid but you do what you need here //The WCF service will give you the lead ID as a Guid so Guid makes sense public Guid SendApplicationToLeadTreeGlobal() { // Create the response object to be filled by the service call. LeadSubmissionResponse response = null; // Using the service reference added to you project create a client. LeadSubmissionServiceClient client = new LeadSubmissionServiceClient(); // Call the SubmitLead method on the service and pass it the // To keep the code cleaner the request is built in a separate method response = client.SubmitLead(apiKey, BuildSubmission()); // Always close the client. client.Close(); // Check the response object has information in it if (response == null) throw new Exception("No response received from LeadTreeGlobal.com"); // This bit is a little contrived so you handle errors however you usually do! // This is just to illustrate that you can receive multiple errors is the data is missing lots or loads of validation fires off var sb = new StringBuilder(); // Are the any errors if (response.Errors.Any()) { //Dissect the list sb.Append("Errors have been encountered submitting leads to LTG"); foreach (var error in response.Errors) { sb.Append("Field: " + error.FieldName + " has errored with message: " + error.Error); } //Throw the errors out in an exception for dealing with throw new Exception(sb.ToString()); } //Awesome! We got no errors return the Guid lead Id so we can use it to check status, cancel etc... return response.LeadId; } private LeadSubmission BuildSubmission() { var submission = new LeadSubmission { AffiliateApiKey = "00000000-0000-0000-0000-000000000001", AffiliateReference = "2605", AffiliateSubReference = "Big Loans", AffiliateCampaign = "WEB", ReferringUrl = "www.refurl.com/?ref=1234", UserAgent = "Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.1; WOW64; Trident/6.0)", IpAddress = "127.0.0.1", Salutation = Titles.Mr, FirstName = "Test", LastName = "Lead", DateOfBirthDay = 1, DateOfBirthMonth = 1, DateOfBirthYear = 1970, MaritalStatus = MaritalStatus.Single, IsCarOwner = true, ConsentToCreditSearch = true, ConsentToMarketingEmails = true, ConsentToMarketingSMS = false, MarketingPreferenceConsent = "Consent", ResidentialCostPerMonth = 50, ResidentialStatus = ResidentialStatus.HomeOwner, NumberOfDependants = 0, BankAccountNumber = "12345678", BankSortCode = "012345", BankCardType = BankCardType.Visa, HouseNumber = "1", Street1 = "A Road", TownCity = "A Town", CountyState = "Dorset", PostCode = "SO14 1PW", CountryCode = "GB", MonthsAtAddress = 12, MobilePhoneNumber = "07123456789", HomePhoneNumber = "01234567890", WorkPhoneNumber = "02234567890", EmailAddress = "tester@tester.com", BestTimeToCall = BestTimeToCall.Morning, LoanAmount = 500, LoanPurposeType = LoanPurposeType.Business, LoanTerm = 30, LoanTermType = TermType.Days, EmploymentStatus = EmploymentStatus.FullTime, Occupation = "Other", EmployerPosition = "BusinessDevelopment", EmployerName = "Some Employer", EmployerPostCode = "AA01 0AA", MonthsWithEmployer = 6, EmployerIndustry = EmployerIndustry.Accountancy, Income = 1000, IncomeFrequency = IncomeFrequency.Weekly, IncomePaymentType = IncomePaymentType.None, NextPayDateDay = 3, NextPayDateMonth = 8, NextPayDateYear = 2015, FollowingPayDateDay = 1, FollowingPayDateMonth = 9, FollowingPayDateYear = 2015, MonthlyUtilityExpenses = 13, MonthlyTransportExpenses = 12, MonthlyFoodExpenses = 10, ExpenditureConfirmed = true, OtherMonthlyOutgoings = 15, CombinedHouseholdIncome = 1234, IsTestLead = true, TestResponseType = TestResponseType.AcceptedByLender }; return submission; } } }
using System; using System.Collections.Generic; using System.IO; using System.Net; using System.Web.Script.Serialization; namespace DJS.PTG.API.RestTestConsole { public class LGTProviderRestSample { //This is here for the example only. private const string apiKey = "00000000-0000-0000-0000-000000000001"; //All operations of the API start with the base URL. private const string baseLGTUrl = "https://api.leadtreeglobal.com/"; //Here is a sample class that could be used to deserialise the JSON private class LGTLeadResponse { public string LeadId { get; set; } public List<string> Errors { get; set; } } /// <summary> /// This helper method takes the JSON returned from the LeadTreeGlobal API and converts /// it into an object. The object is included in the sample /// </summary> /// <param name="jsonResponse"></param> /// <returns>LGTLeadResponse</returns> private static LGTLeadResponse GetResponseFromJSON(string jsonResponse) { JavaScriptSerializer serializer = new JavaScriptSerializer(); return serializer.Deserialize<LGTLeadResponse>(jsonResponse); } /// <summary> /// This method takes and object and converts in to JSON. /// We are using an object that matches the LeadTreeGlobal.com submission object /// as it means the JSON created will be a direct match. /// The "Lead" object is included in the samples. /// </summary> /// <param name="obj"></param> /// <returns></returns> public static string ToJSON(object obj) { JavaScriptSerializer serializer = new JavaScriptSerializer(); return serializer.Serialize(obj); } /// <summary> /// This sample method will check the status of the LeadTreeGlobal API, create the submission JSON, /// Call the API using the PostLead Method and check the result for a lead Id or errors /// </summary> /// <returns>API </returns> public Guid SendApplicationToProvider() { //It is always go practice to see if the service is alive by checking the status proir to submitting a lead. if (string.IsNullOrEmpty(SystemStatusGet(baseLGTUrl))) return Guid.Empty; //create the message body LeadSubmission req = BuildSubmission(); //Call the post lead method with the JSON for the submission var result = PostLead(req); //A little simple but... Check to see if there are any errors //If not return the Guid that represents the LeadTreeGlobal application Id if (result.Errors.Count < 1) { return new Guid(result.LeadId); } else { throw new Exception("Did not receive a lead Id errors encountered"); } } /// <summary> /// Send the lead to the LeadTree Global API. This is a HTTP POST operation /// and the content type is passed as text/json /// </summary> /// <param name="lead"></param> /// <returns>Lead response object holding the results from the call</returns> static LGTLeadResponse PostLead(LeadSubmission lead) { //Create a http web request using the base URL and your API key var httpWebRequest = (HttpWebRequest)WebRequest.Create(baseLGTUrl + apiKey); var result = string.Empty; //Set the content type httpWebRequest.ContentType = "application/json"; //Set the HTTP Verb to POST httpWebRequest.Method = "POST"; //Convert the lead to JSON for submission string json = ToJSON(lead); //Write the json to the HTTP request stream using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream())) { streamWriter.Write(json); streamWriter.Flush(); streamWriter.Close(); } //Create an HTTP web response var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse(); //Read the stream using (var streamReader = new StreamReader(httpResponse.GetResponseStream())) { result = streamReader.ReadToEnd(); } return GetResponseFromJSON(result); } /// <summary> /// Performs an HTTP GET request on the base URL of the LeadTreeGlobal API. /// </summary> /// <param name="url"></param> /// <returns></returns> static string SystemStatusGet(string url) { HttpWebRequest req = WebRequest.Create(url) as HttpWebRequest; string result = null; using (HttpWebResponse resp = req.GetResponse() as HttpWebResponse) { StreamReader reader = new StreamReader(resp.GetResponseStream()); result = reader.ReadToEnd(); } return result; } /// <summary> /// Build the Lead object so that the javascriptserializer can convert to JSON /// </summary> /// <returns>Populated Lead object</returns> private LeadSubmission BuildSubmission() { var submission = new LeadSubmission { AffiliateApiKey = "00000000-0000-0000-0000-000000000001", AffiliateReference = "2605", AffiliateSubReference = "Big Loans", AffiliateCampaign = "WEB", ReferringUrl = "www.refurl.com/?ref=1234", UserAgent = "Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.1; WOW64; Trident/6.0)", IpAddress = "127.0.0.1", Salutation = 1, FirstName = "Test", LastName = "Lead", DateOfBirthDay = 1, DateOfBirthMonth = 1, DateOfBirthYear = 1970, MaritalStatus = 1, IsCarOwner = true, ConsentToCreditSearch = true, ConsentToMarketingEmails = true, ConsentToMarketingSMS = false, ResidentialCostPerMonth = 50, ResidentialStatus = 1, NumberOfDependants = 0, BankAccountNumber = "12345678", BankSortCode = "012345", BankCardType = 1, HouseNumber = "1", Street1 = "A Road", TownCity = "A Town", CountyState = "Dorset", PostCode = "SO14 1PW", CountryCode = "GB", MonthsAtAddress = 12, MobilePhoneNumber = "07123456789", HomePhoneNumber = "01234567890", WorkPhoneNumber = "02234567890", EmailAddress = "tester@tester.com", BestTimeToCall = 1, LoanAmount = 500, LoanPurposeType = 1, LoanTerm = 30, LoanTermType = 1, EmploymentStatus = 1, Occupation = "Other", EmployerPosition = "BusinessDevelopment", EmployerName = "Some Employer", EmployerPostCode = "AA01 0AA", MonthsWithEmployer = 6, EmployerIndustry = 1, Income = 1000, IncomeFrequency = 1, IncomePaymentType = 1, NextPayDateDay = 3, NextPayDateMonth = 8, NextPayDateYear = 2015, FollowingPayDateDay = 1, FollowingPayDateMonth = 9, FollowingPayDateYear = 2015, MonthlyUtilityExpenses = 13, MonthlyTransportExpenses = 12, MonthlyFoodExpenses = 10, ExpenditureConfirmed = true, OtherMonthlyOutgoings = 15, CombinedHouseholdIncome = 1234, IsTestLead = true, TestResponseType = 2 }; return submission; } public class LeadSubmission { public string AffiliateApiKey { get; set; } public string AffiliateReference { get; set; } public string AffiliateSubReference { get; set; } public string AffiliateCampaign { get; set; } public string ReferringUrl { get; set; } public string UserAgent { get; set; } public string IpAddress { get; set; } public int Salutation { get; set; } public string FirstName { get; set; } public string LastName { get; set; } public int DateOfBirthDay { get; set; } public int DateOfBirthMonth { get; set; } public int DateOfBirthYear { get; set; } public int MaritalStatus { get; set; } public bool IsCarOwner { get; set; } public bool ConsentToCreditSearch { get; set; } public bool ConsentToMarketingEmails { get; set; } public bool ConsentToMarketingSMS { get; set; } public int ResidentialCostPerMonth { get; set; } public int ResidentialStatus { get; set; } public int NumberOfDependants { get; set; } public string BankAccountNumber { get; set; } public string BankSortCode { get; set; } public int BankCardType { get; set; } public string HouseNumber { get; set; } public string Street1 { get; set; } public string TownCity { get; set; } public string CountyState { get; set; } public string PostCode { get; set; } public string CountryCode { get; set; } public int MonthsAtAddress { get; set; } public string MobilePhoneNumber { get; set; } public string HomePhoneNumber { get; set; } public string WorkPhoneNumber { get; set; } public string EmailAddress { get; set; } public int BestTimeToCall { get; set; } public int LoanAmount { get; set; } public string LoanPurpose { get; set; } public int LoanPurposeType { get; set; } public int LoanTerm { get; set; } public int LoanTermType { get; set; } public int EmploymentStatus { get; set; } public string Occupation { get; set; } public string EmployerPosition { get; set; } public string EmployerName { get; set; } public string EmployerPostCode { get; set; } public int MonthsWithEmployer { get; set; } public int EmployerIndustry { get; set; } public int Income { get; set; } public int IncomeFrequency { get; set; } public int IncomePaymentType { get; set; } public int NextPayDateDay { get; set; } public int NextPayDateMonth { get; set; } public int NextPayDateYear { get; set; } public int FollowingPayDateDay { get; set; } public int FollowingPayDateMonth { get; set; } public int FollowingPayDateYear { get; set; } public int MonthlyUtilityExpenses { get; set; } public int MonthlyTransportExpenses { get; set; } public int MonthlyFoodExpenses { get; set; } public bool ExpenditureConfirmed { get; set; } public int OtherMonthlyOutgoings { get; set; } public int CombinedHouseholdIncome { get; set; } public bool IsTestLead { get; set; } public int TestResponseType { get; set; } } } }
$data = array( "AffiliateApiKey" => "00000000-0000-0000-0000-000000000001", "AffiliateReference" => "2605", "AffiliateSubReference" => "Big Loans", "AffiliateCampaign" => "WEB", "ReferringUrl" => "www.refurl.com/?ref=1234", "UserAgent" => "Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.1; WOW64; Trident/6.0)", "IpAddress" => "127.0.0.1", "Salutation" => "Mr", "FirstName" => "Test", "LastName" => "Lead", "DateOfBirthDay" => "1", "DateOfBirthMonth" => "1", "DateOfBirthYear" => "1970", "MaritalStatus" => "Single", "IsCarOwner" => "true", "ConsentToCreditSearch" => "true", "ConsentToMarketingEmails" => "true", "ConsentToMarketingSMS" => "false", "ResidentialCostPerMonth" => "50", "ResidentialStatus" => "Other", "NumberOfDependants" => "0", "BankAccountNumber" => "12345678", "BankSortCode" => "012345", "BankName" => "First Bank", "BankPhoneNumber" => "01234567890", "BankCardType" => "Visa", "HouseNumber" => "1", "Street1" => "A Road", "TownCity" => "A Town", "CountyState" => "Dorset", "PostCode" => "SO14 1PW", "CountryCode" => "GB", "MonthsAtAddress" => "12", "MobilePhoneNumber" => "07123456789", "HomePhoneNumber" => "01234567890", "WorkPhoneNumber" => "02234567890", "EmailAddress" => "tester@tester.com", "BestTimeToCall" => "Afternoon", "LoanAmount" => "500", "LoanPurposeType" => "Other", "LoanTerm" => "30", "LoanTermType" => "Days", "EmploymentStatus" => "FullTime", "Occupation" => "Other", "EmployerPosition" => "BusinessDevelopment", "EmployerName" => "Some Employer", "EmployerPostCode" => "AA01 0AA", "MonthsWithEmployer" => "6", "EmployerIndustry" => "Finance", "Income" => "1000", "IncomeFrequency" => "LastDayMonth", "IncomePaymentType" => "BankTransfer", "NextPayDateDay" => "3", "NextPayDateMonth" => "8", "NextPayDateYear" => "2015", "FollowingPayDateDay" => "1", "FollowingPayDateMonth" => "9", "FollowingPayDateYear" => "2015", "MonthlyUtilityExpenses" => "13", "MonthlyTransportExpenses" => "12", "MonthlyFoodExpenses" => "10", "ExpenditureConfirmed" => "true", "OtherMonthlyOutgoings" => "15", "CombinedHouseholdIncome" => "1234", "IsTestLead" => "true", "TestResponseType" => "AcceptedByLender"); $data_string = json_encode($data); $ch = curl_init('https://api.leadtreeglobal.com/00000000-0000-0000-0000-000000000001'); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, array( 'Content-Type: application/json', 'Content-Length: ' . strlen($data_string))); $result = curl_exec($ch); print_r($result);

Response Content Type

If an 'Accept' header is not specified, the response will be in JSON. To receive a response in XML specify an 'Accept' header of 'application/xml'.

Checking the Lead Status

Once you have submitted a lead to the API you can check the status by performing an HTTP GET request on api.leadtreeglobal.com passing your API key and the GUID of the application that has been submitted.

URL needs to be : https://api.leadtreeglobal.com/<YOUR API KEY>/<APPLICATION GUID>

Please note it is important that the you periodically poll the application status check to get the URL to redirect your customers to.

Response Details

Following a successful call to the API you will receive data formatted as either JSON or XML. This will depend on how you have chosen to integrate. The data will contain these details:

Field Name Description Type
PercentComplete Shows how far through the ping tree your lead is. Integer
RedirectUrl When the lead is processed successfully you will be given the URL of the lender accepting the lead. String
Status This will indicate the status of the lead. String
Commission If the lead is accepted by a CPA lender, the commission amount will be reported. String

XML Data Structure

Accepted Lead

<LeadStatus> <PercentComplete>100</PercentComplete> <RedirectUrl> http://leadtreeglobal.com/leadsubmission/RedirectApplication/NDQZZDQAAAA0AAAAMgAAADkAAAA1 </RedirectUrl> <Status>MatchFound</Status> <Commission>5</Commission> </LeadStatus>

Invalid Lead

<LeadStatus> <PercentComplete>100</PercentComplete> <RedirectUrl i:nil="true"/> <Status>Invalid Lead Id</Status> <Commission>0</Commission> </LeadStatus>

No Match Found

<LeadStatus> <PercentComplete>100</PercentComplete> <RedirectUrl i:nil="true"/> <Status>NoMatchFound</Status> <Commission>0</Commission> </LeadStatus>

Errors for Invalid data

<LeadSubmissionResponse> <LeadId>66905f7f-47fd-4a19-81f4-aa6f7e201a69</LeadId> <Errors> <LeadSubmissionError> <Error>Next paydate cannot be set in the past </Error> <FieldName>NextPayDate</FieldName> </LeadSubmissionError> <LeadSubmissionError> <Error>Following paydate cannot be set in the past</Error> <FieldName>FollowingPayDate</FieldName> </LeadSubmissionError> </Errors> </LeadSubmissionResponse>

JSON Data Structure

Accepted Lead

{ "status": "MatchFound", "redirectUrl": "http://leadtreeglobal.com/leadsubmission/RedirectApplication/NDQZZDQAAAA0AAAAMgAAADkAAAA1", "percentComplete": 100, "commission" : 5 }

Invalid Lead

{ "status": "Invalid Lead Id", "redirectUrl": null, "percentComplete": 100, "commission" : 0 }

No Match Found

{ "status": "NoMatchFound", "redirectUrl": null, "percentComplete": 100, "commission" : 0 }

Errors for Invalid data

{ "leadId": "9f694c9e-e674-4f9a-b2d7-aa08c3ac78bb", "errors": [ { "error": "Next paydate cannot be set in the past", "fieldName": "NextPayDate" }, { "error": "Following paydate cannot be set in the past", "fieldName": "FollowingPayDate" } ], }

Sample code

public ProviderLeadResponse GetApplicaitonStatus(Guid applicaitonReference) { /* In this example we are using an object to return data to the calling system. You can use this or build your own. public class ProviderLeadResponse { [DataMember] public string LeadStatus { get; set; } [DataMember] public string RedirectionUrl { get; set; } } */ var leadResponse = new ProviderLeadResponse(); //Using the service reference added to you project create a client. LeadSubmissionServiceClient client = new LeadSubmissionServiceClient(); LeadStatus response = client.Status(APIKey, applicaitonReference.ToString()); //Ensure that the response from the web service has data. if (response != null) { //Check if the response returned from the service is invalid or not matched to a lender. if (response.Status.ToLower() == "nomatchfound" || response.Status.ToLower() == "invalid lead id") { leadResponse.LeadStatus = "Failed"; leadResponse.RedirectionUrl = string.Empty; } else { //Has the process on Leadtreeglobal reached the end. This is denoted by a percentage value allowing for progress indicators to be //shown to your customers. //Also check that a redirect URL has been received. if (response.PercentComplete == 100 && (!string.IsNullOrEmpty(response.RedirectUrl) || !string.IsNullOrWhiteSpace(response.RedirectUrl))) { leadResponse.LeadStatus = "Accepted"; leadResponse.RedirectionUrl = response.RedirectUrl; } else { leadResponse.LeadStatus = "Running"; leadResponse.RedirectionUrl = string.Empty; } } } else { leadResponse.LeadStatus = "Failed"; leadResponse.RedirectionUrl = string.Empty; } //Once we have processed the response return this for action. return leadResponse; }
try { //This example uses the HttpClient available in .net 4.5 http://msdn.microsoft.com/query/dev11.query?appId=Dev11IDEF1&l=EN-US&k=k%28System.Net.Http.HttpClient.%23ctor%29;k%28TargetFrameworkMoniker-.NETFramework //Setup the HttpClient var client = new HttpClient(); // Send the request. Remember that the url is composed of api.leadtreeglobal.com, your API key and the lead id you //received from posting the lead. var resp = client.GetAsync(url); //Handle the response var ms = new MemoryStream(); resp.Result.Content.CopyToAsync(ms).Wait(); ms.Position = 0; var sr = new StreamReader(ms); var result = sr.ReadToEnd(); //Check that a HTTP success code was returned. Then return the result for parsing. return resp.Result.IsSuccessStatusCode ? result : string.Empty; } catch (Exception) { return string.Empty; }
$ch = curl_init('https://api.leadtreeglobal.com/9486F30A-CA04-43D9-8C95-790FC1C3FC29/7986F40C-CA11-49E9-8C47-079GC1D4FC30'); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $result = curl_exec($ch);

Testing Your Integration

Testing is simple. Change your submission data and set the IsTestLead value to True! If your broker has not completed compliance with Leadtree staff, all leads passed to the API will be treated as test by default.

Then send your request across as described in the sections outline above. Your leads will be taken through the full journey but never presented to anyone on any of our trees.

To force the API to return an Accepted/Rejected/Commission response set the TestResponseType.

Checking your Commission

When you check a lead's status as outlined below, the commission will be reported if it is an accepted CPA lead. In the case of CPF leads or if you wish to collect the commission later you need to do another call to the API.

Once you have redirected your customer to the lender you can check to see how much that lead has earned. To do this perform a GET request against the API.

The format of the URL needs to be api.leadtreeglobal.com/commission/<YOUR API KEY>APPLICATION GUID

You can request your response as either XML or JSON by specifying the format in the request header. Use application/json or application/xml. If you don't specify you will receive XML.

The commission will also be shown in the check status response from the API.

XML Data Structure

Accepted Request

<CommissionResponse> <AffiliateSubId>ABC123<AffiliateSubId> <Commission>0.00<Commission> <ErrorMessage/> <Status>Ok</Status> <CommissionResponse>

Erroneous Request

<CommissionResponse> <AffiliateSubId>ABC123</AffiliateSubId> <Commission/> <ErrorMessage>Could not find commission for details provided.</ErrorMessage> <Status>Error</Status> </CommissionResponse>

JSON Data Structure

Accepted Request

{ "status": "Ok", "commission": 0.00, "affiliateSubId": "ABC123", "errorMessage": "" }

Erroneous Request

{ "status": "Error", "commission": 0.00, "affiliateSubId": "ABC123", "errorMessage": "Could not find commission for details provided." }