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, get in touch with you account manager to arrange. Once this is done you will have a key generated 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.

Send a Lead

Please choose any one of the following methods.

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

Single step process

Direct Post URL: https://us-api.leadtreeglobal.com/leaddirect/<YOUR API KEY>/
e.g. https://us-api.leadtreeglobal.com/leaddirect/CCC14DB4-13D0-4CC2-AA4B-046B74ACC7F3/

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.

Post a lead and poll for status

Step-1: Post Lead

Post URL : https://us-api.leadtreeglobal.com/<YOUR API KEY>/
e.g. https://us-api.leadtreeglobal.com/leaddirect/CCC14DB4-13D0-4CC2-AA4B-046B74ACC7F3/

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

Sample JSON submission

{ "affiliateReference":"test", "affiliateSubReference": "", "affiliateCampaign": "10", "referringUrl": "https://www.thisisatest.com", "userAgent": "Mozilla/5.0 (Windows; U; MSIE 9.0; Windows NT 9.0; en-US)", "ipAddress": "194.75.52.98", "salutation": "Mr", "firstName": "Steve", "surname": "Tester", "emailAddress": "steve.tester@gmail.com", "dateOfBirthDay": 24, "dateOfBirthMonth": 10, "dateOfBirthYear": 1981, "maritalStatus": "married", "cellPhoneNumber": "7967568889", "homePhoneNumber": "7967568889", "residentialStatus": "HomeOwner", "isCarOwner": false, "consentToCreditSearch": true, "consentToMarketingEmails": false, "consentToMarketingSMS": false, "abaRoutingTransitNumber": "122105155", "bankAccountNumber": "41130835", "bankCardType": "Visa", "houseNumber": "99", "street1": "East Pawnee Street", "street2": "", "townCity": "58 Cedar Falls", "state": "IA", "zipCode": "50613", "monthsAtAddress": 60, "loanAmount": 500, "employmentStatus": "FullTime", "employerName": "Testing Inc.", "income": 1000, "incomeFrequency": "LastFriday", "nextPayDateDay": 13, "nextPayDateMonth": 1, "nextPayDateYear": 2020, "followingPayDateDay": 13, "followingPayDateMonth": 2, "followingPayDateYear": 2020, "otherMonthlyOutgoings": 0, "MonthsWithEmployer": 1, "drivingLicenseIssuingState": "IA", "drivingLicenseNumber": "l1311977", "socialSecurityNumber": "522662633", "bankName": "Bank Of America", "bankAccountType":"checking", "workPhoneNumber": "5559865874", "monthsWithBank": 12, "jobTitle": "Tester", "consentToTerms": true }

JSON Response Details

Following a successful call to the API you will receive data formatted as JSON. The data will contain these details:

Field Name Description Type
leadId This is the application id/key for the submitted lead. String
errors A JSON array that shows any validation errors encountered with the submission. If there are no issues, the array will be empty. String
statusUrl The URL returned to enable you to start polling. String

Sample response

{ "leadId":"0217440b-ac93-4177-9683-1dc772eec060", "errors":[], "statusUrl":"https://us-api.leadtreeglobal.com/322b9ee8-1f95-41d5-d049-2364c441890c/e31d731a-63f0-465b-cc92-58844db8eecb" }

Step-2: Get Status

not required IF YOU ARE USING THE POLLING METHOD, YOU MUST SEND PERIODIC REQUESTS TO THE STATUS CHECK URL. IF THIS IS NOT DONE, YOU WILL NOT GET THE RESULTING REDIRECT URL.
When checking the status of a lead simply perform a GET request on the API to the status check url provided in the submission response. This part of the API should be polled periodically to get the URL to redirect the customer to.

Validating your leads

Post URL :https://us-api.leadtreeglobal.com/<YOUR API KEY>/validate

There is not test enpoint on the Api, instead, POST your lead to the above URL and the Api will return the same response as the full POST. This allows you to determine if the lead is valid. Once you are confident the data is valid, you can start sending data fully.


Data Format

The following is the information that will be supplied with the post to the api when submitting a lead

  • The field names are not case sensitive
  • Boolean field are either true for yes or false for no.
  • If the field is not required (See table below) you do not need to supply it, but the lead may convert better with more data.
Field Name Data Type Max Length Range Select Values Required
AbaRoutingTransitNumber String
required
AffiliateReference String
required
BankAccountNumber String
required
BankAccountType String
  • checking
  • saving
required
BankName String
required
DateOfBirthDay Int32 From 1 to 31
required
DateOfBirthMonth Int32 From 1 to 12
required
DateOfBirthYear Int32
required
DrivingLicenseIssuingState String 256
required
DrivingLicenseNumber String 20
required
EmailAddress String 256
required
EmployerName String 128
required
EmploymentStatus String
  • ArmedForces
  • Benefits
  • DisabilityBenefits
  • FullTime
  • NotSet
  • PartTime
  • Retired
  • SelfEmployed
  • Student
  • Temporary
  • Unemployed
required
FirstName String 128
required
FollowingPayDateDay Int32 From 1 to 31
required
FollowingPayDateMonth Int32 From 1 to 12
required
FollowingPayDateYear Int32
required
Income Int32 From 100 to 30000
required
IpAddress String
required
JobTitle String
required
LoanAmount Int32
required
MonthsAtAddress Int32 From 1 to 360
required
NextPayDateDay Int32 From 1 to 31
required
NextPayDateMonth Int32 From 1 to 12
required
NextPayDateYear Int32
required
ReferringUrl String
required
ResidentialStatus String
  • HomeOwner
  • Renting
required
Salutation String 5
  • Mr
  • Mrs
  • Miss
  • Ms
required
State String
required
Street1 String
required
Surname String 128
required
TownCity String
required
UserAgent String
required
ZipCode String
required
AffiliateCampaign String
not required
AffiliateSubReference String
not required
BankCardType String
not required
CellPhoneNumber String
not required
ConsentToCreditSearch True/False
not required
ConsentToMarketingEmails True/False
not required
ConsentToMarketingSMS True/False
not required
ConsentToTerms True/False
not required
EmployerIndustry String
not required
EmployerZipCode String
not required
FollowingPayDate DateTime
not required
HomePhoneNumber String
not required
HouseNumber String
not required
IncomeFrequency String
  • Weekly
  • BiWeekly
  • Fortnightly
  • FourWeekly
  • LastDayMonth
  • LastFriday
  • LastMonday
  • LastThursday
  • LastTuesday
  • LastWednesday
  • LastWorkingDayMonth
  • NotSet
  • SpecificDayOfMonth
  • TwiceMonthly
not required
IncomePaymentType String
not required
IsCarOwner True/False
not required
LoanPurpose String
not required
LoanTerm Int32
not required
LoanTermType Int32
not required
MaritalStatus String
not required
Military True/False
not required
MonthlyFoodExpenses Int32
not required
MonthlyTransportExpenses Int32
not required
MonthlyUtilityExpenses Int32
not required
MonthsWithBank Int32
not required
MonthsWithEmployer Int32 From 1 to 500
not required
NextPayDate DateTime
not required
NumberOfDependants Int32 From 0 to 10
not required
OtherMonthlyOutgoings Int32
not required
ResidentialCostPerMonth Int32
not required
SocialSecurityNumber String
not required
Street2 String
not required
TimeAtAddressMonths Int32
not required
TimeAtAddressYears Int32
not required
TimeAtEmployerMonths Int32
not required
TimeAtEmployerYears Int32
not required
WorkPhoneNumber String
not required

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 the URL supplied in the initial response

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 JSON. The data will contain these details:

Field Name Description Type
journeyCompleted Indicates if the lead has completed processing. Bool
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
Commission Type The commission type of the lead purchaser. This can be one of CPAFlat, CPAPercentage, CPFFlat, CPFPercentage and NotSet. String

JSON Data Structure

Lead Processing

{ "status":"Processing", "redirectUrl":null, "commissionType":0, "journeyCompleted":false, "commission":0.0 }

Accepted Lead

{ "Status":"MatchFound", "RedirectUrl":"https://leads.somelender.com/redirect?id=0b69541212be442c0b5695c9ae2180c1", "CommissionType":1, "JourneyCompleted":true, "Commission":0.24000 }

Invalid Lead

{ "leadId":"0217440b-ac93-4177-9683-1dc772eec060", "errors":[ { "error": "Next paydate cannot be set in the past", "fieldName": "NextPayDate" }, { "error": "Following paydate cannot be set in the past", "fieldName": "FollowingPayDate" }], "statusUrl":"" }

No Match Found

{ "status":"NoMatchFound", "redirectUrl":null, "commissionType":1, "journeyCompleted":true, "commission":0.0 }

Using the iFrame Code

Here is an example Url that shows the parameters in use within the IFrame code.

<iframe id="appForm" onload="scroll(0,0);" scrolling="auto" height="1600" width="100%" frameborder="0" src="https://us-api.leadtreeglobal.com/iframe?affiliateApiKey=00000000-0000-0000-0000-000000000000"></iframe>

Once you have changed the affiliateApiKey of your iFrame, simply take that code and pop it on your site.

Height Discrepancies

Although every effort has been made to provide the correct height information, you may find due to variances in browser behaviour or design rules implemented on your site that you need to manually adjust the height yourself.

Don't worry as this is a very straight forward process! All you need to do is find the height="value" in the iFrame code you copied in the above step and increase the number until all parts of the form are visible.

<iframe id="appForm" onload="scroll(0,0);" scrolling="auto" height="2100" width="100%" frameborder="0" src="https://us-api.leadtreeglobal.com/iframe?affiliateApiKey=00000000-0000-0000-0000-000000000000"></iframe>