Lead Buy

This Lokyata developer documentation describes the Lead Buy API, a JSON POST API that uses API key header authorization. The API is used to help lenders make lead buy decisions.

Sandbox Credentials

Item	Value
Method	POST
URL	https://api.xrv3.lokyata.com/process-lp-lead
Content Type	application/json
Authentication	API key passed in the x-api-key request header
Sandbox API Key	0VIBkISQiaQS4z6iggxT11JKqvw0subW

Request

Name	Type	Required	Length	Description
test_type	string	No	64	For testing, Deny = Returns a test decline API response; Accept = Returns a test accept message API response; Review = Returns a review API response - ["Deny","Accept", "Review"]
request_id	string	Yes	64	Unique ID for API request. Can be any unique ID generated by you.
lead_provider_id	string	Yes	30	Unique ID for lead provider / submitter. Values provided by Lokyata.
campaign_id	string	Yes	64	Unique ID for campaign configured by lender in lead provider system. Values provided by Lokyata (separate for each lender)
affiliate_id	string	Yes	64	Unique ID for affiliate provider. Can be any ID from your system.
affiliate_sub_id	string	No	64	Unique ID for sub affiliates. Can be any ID from your system.
lead_price	float	Yes		Lender's cost to purchase lead
application_website	string	Yes	300	Website used by the customer during application
ip_address	string	Yes	39	Customer's IP address. Accepts both IPv4 & IPv6 Format.
requested_amount	int	Yes		Requested loan amount in USD, including dollars and cents.
ssn	string	Yes	9	Customer’s social security number. Format: all digits; no dashes.
dob	date	Yes		Customers date of birth. Format: yyyy-mm-dd.
gender	string	No	7	Customer’s gender - ["Male", "Female","Unknown", "Other"]
first_name	string	Yes	50	Customer’s first name
middle_initial	string	No	1	Customer’s middle initial
last_name	string	Yes	50	Customer’s last name
address	string	Yes	300	Customer’s home street address
address2	string	No	100	Customer’s home address line 2 - apartment or suite number
city	string	Yes	100	City of customer's home street address
state	string	Yes	2	State where the customer resides. Format is state two-letter abbreviation. Refer to the two- letter US Postal Service (USPS) abbreviation list given at the https://www.usps.com/ web site.
zip_code	string	Yes	10	Customer’s home address zip code. Format is either nnnnn or nnnnn-nnnn.
home_phone	string	Yes	50	Customer’s home phone number. Format: All numeric digits; no special characters
mobile_phone	string	Yes	50	Customer’s mobile phone number. Format: All numeric digits; no special characters
work_phone	string	Yes	50	Customer’s work phone number. Format: All numeric digits; no special characters
drivers_license_state	string	Yes	2	State where customer's driver’s license was issued. Format is state two-letter abbreviation. Refer to the two-letter US Postal Service https://www.usps.com/
drivers_license_number	string	Yes	20	Customer's driver’s license number. Format: No special characters
contact_time	string	No	9	Best time to contact the customer - ["Morning", "Afternoon", "Evening"]
is_military	bool	Yes		true = Customer is a member of the US military or dependent of someone in the US military; false = Customer is not in the US military and not dependent of someone in the US military.
residence_type	string	Yes	4	Whether the customer owns or rents the residence - ["Rent" ,"Own", "Family", "Friend", "Other"].
email	string	Yes	300	Customer’s email address. Format is abcd@abcd.abc
residence_months	int	Yes		Number of months the customer is living in the current residence
is_citizen	bool	Yes		true = Customer is a US citizen and at least 18 years old or false = Customer is not a US citizen or not at least 18 years old.
is_subscribed_future_offers	bool	No		true = Customer subscribed to future offers or false = Customer did not subscribe to future offers.
num_installments	int	No		Number of installments the system will create for the loan schedule
interest_rate	int	No		Interest rate to be charged on loan
language	string	No	300	Language which customer speaks. If no value is specified, English is used by default.
income_type	string	Yes	20	Customer's income type - ["Employed","Self Employed","Disability", "Social Security", "Unemployed", "Pension", "Retirement", "Other"]
payment_type	string	Yes	20	Customer's payment type - ["Direct Deposit", "Paper Check", "Cash"]
employment_type	string	Yes	20	Does the customer work full or part-time - ["Full Time", "Part Time", "Not Applicable"]
employment_months	int	Yes		Number of months the customer has been working with the current employer
employer_name	string	Yes	100	Name of customer’s current employer
employment_address	string	Yes	300	Street address of the customer’s current employer
employment_address2	string	No	100	Suite or Apartment address of the customer’s current employer
employment_city	string	No	50	City where the customer’s employer is located
employment_state	string	No	2	State where the customer’s employer is located. Format is state two-letter abbreviation. Refer to the two-letter US Postal Service (USPS) abbreviation list given at the https://www.usps.com/ web site.
employment_zip_code	string	No	10	Employer’s zip code. Format is either nnnnn or nnnnn-nnnn.
employer_phone	string	Yes	13	Phone number of the customer’s employer. Format: All numeric digits; no special characters
employment_phone_ext	string	No	6	Phone number extension of the customer’s employer
employment_fax	string	No	13	Fax number of the customers’ employer. Format: All numeric digits; no special characters
supervisor_name	string	Yes	100	Name of the customer’s supervisor
supervisor_phone	string	No	13	Work phone number of the customer’s supervisor. Format: All numeric digits; no special characters
supervisor_phone_ext	string	No	6	Work phone number extension for the customer’s supervisor.
job_title	string	No	100	Customer’s job title
work_shift	string	No	15	Customer’s work shift - ["First Shift", "Second Shift", "Third Shift", "Other"]
pay_frequency	string	Yes	15	Customer’s pay schedule - ["Daily", "Weekly", "Bi- Weekly", "Twice-Monthly", "Monthly"]
last_paydate	date	Yes		Customer’s most recent pay date. Format: yyyy-mm-dd.
next_paydate	date	Yes		Customer’s next pay date. Format: yyyy-mm-dd.
second_next_paydate	date	No		Customer second pay date after the loan. Format: yyyy-mm-dd.
net_monthly_income	int	Yes		Customer’s net monthly income (after taxes and other withholding).
gross_monthly_income	int	No		Customer’s gross monthly income (before withholdings)
bank_account_holder	string	No	100	Name of the holder of the bank account
bank_name	string	Yes	50	Customer’s bank name
bank_phone	string	No	13	Phone number of the customer’s bank. Format: All numeric digits; no special characters
bank_account_type	string	Yes	10	Customer’s type of bank account - ["Checking", "Savings"].
bank_routing_number	string	Yes	9	American Bankers Association (ABA) routing number for the customer’s bank. Format: All digits; no dashes (nnnnnnnnn).
bank_account_number	string	Yes	17	Customer’s bank account number
bank_months	int	Yes		Number of months the customer has had the bank account
is_direct_deposit	bool	Yes		Customer has direct deposit (true/false)
outstanding_amt	float	No		Outstanding balance of the customer on other loans
reference_first_name	string	No	30	Reference’s first name
reference_last_name	string	No	30	Reference’s last name
reference_phone	string	No	10	Reference’s phone number. Format: All numeric digits; no special characters
reference_relationship	string	No	15	Customer’s relationship with the reference - ["Spouse", "Sibling", "Parent", "Co-worker", "Friend", "Boyfriend", "Girlfriend", "Brother", "Sister", "Employer", "Neighbor", "Other"]
user_string	string	Yes		User Agent from the Loan Application. Example: Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0
sms_opt_in	bool	No		If the Customer has opted in for SMS Notifications

Response Structure

Name	Type	Length	Description
decision	string	30	Approved = purchase lead; Denied = decline to purchase lead - [“Approved”,”Denied”]
redirect_url	string	300	Loan application URL to redirect approved customer to. Avilable only when decision is “Approved”
request_id	string	300	The request ID of the Loan Application
comment	string	300	Additional information about the status of the loan application.

Example request (JSON)

Request header

{
  "x-api-key": "<your_api_key>",
  "Content-Type": "application/json"
}

Request payload

{
  "lead_provider_id": "LP",
  "campaign_id": "LEADPROVIDER25",
  "request_id": "64109500301",
  "affiliate_id": "342256601",
  "affiliate_sub_id": "54321",
  "lead_price": 25,
  "application_website": "abcd.com",
  "test_type": "Deny",
  "ip_address": "124.110.100.54",
  "requested_amount": 500,
  "ssn": "876543210",
  "dob": "1994-03-07",
  "gender": "Male",
  "first_name": "Charlie",
  "middle_initial": "A",
  "last_name": "Chaplin",
  "address": "123 Main Street",
  "address2": "Apt 301",
  "city": "Philadelphia",
  "state": "PA",
  "zip_code": "54465",
  "home_phone": "1234567890",
  "mobile_phone": "1357924680",
  "work_phone": "9998887770",
  "drivers_license_state": "PA",
  "drivers_license_number": "10637365",
  "contact_time": "Morning",
  "is_military": false,
  "residence_type": "Rent",
  "email": "charliechappie@gmail.com",
  "residence_months": 48,
  "is_citizen": true,
  "is_subscribed_future_offers": true,
  "num_installments": 20,
  "interest_rate": 60,
  "language": "English",
  "income_type": "Employed",
  "payment_type": "Direct Deposit",
  "employment_type": "Full Time",
  "employment_months": 15,
  "employer_name": "Anime Pub",
  "employment_address": "west block, Clinton Lane",
  "employment_address2": "1145, 8th floor, Empire Plaza",
  "employment_city": "Philadelphia",
  "employment_state": "PA",
  "employment_zip_code": "54465",
  "employer_phone": "9998887776",
  "employment_phone_ext": null,
  "employment_fax": null,
  "supervisor_name": "William Hill",
  "supervisor_phone": "1231231234",
  "supervisor_phone_ext": null,
  "job_title": "Bartender",
  "work_shift": "First Shift",
  "pay_frequency": "Twice-Monthly",
  "last_paydate": "2021-05-29",
  "next_paydate": "2021-06-14",
  "second_next_paydate": "2021-06-29",
  "net_monthly_income": 3500,
  "gross_monthly_income": 3800,
  "bank_account_holder": "Charlie Chaplin",
  "bank_name": "ABCD bank",
  "bank_phone": "1112223330",
  "bank_account_type": "Checking",
  "bank_routing_number": "123456789",
  "bank_account_number": "98765432",
  "bank_months": 36,
  "is_direct_deposit": true,
  "outstanding_amt": 500,
  "reference_first_name": "Jennifer",
  "reference_last_name": "Lawrence",
  "reference_phone": "1234567890",
  "reference_relationship": "Spouse",
  "user_string": "Mozilla/5.0 (Linux; Android 12; SM-S906N Build/QP1A.190711.020; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/80.0.3987.119 Mobile Safari/537.36",
  "sms_opt_in": true
}

Simple request (cURL)

curl -H "x-api-key: <your_key>" -H "Content-Type: application/json" --data "<your_payload>" https://api.xrv3.lokyata.com/process-lp-lead

Sample Responses

Accepted Lead Response - 200 OK

{
  "request_id": "64109500301",
  "decision": "Approved",
  "redirect_url": "https://www.lokyata.com",
  "comment": ""
}

Denied Lead Response - 200 OK

{
  "request_id": "64109500301",
  "decision": "Denied",
  "redirect_url": null,
  "comment": "Denial Reason"
}

Error Response - 500 Internal Server Error

{
  "request_id": "64109500301",
  "decision": "Denied",
  "redirect_url": null,
  "comment": "Failure Reason"
}

Comments - Additional Messages

Based on the request, campaign, and workflow configuration for the client, the API can return the following messages in the "comment" field. Workflow-level underwriting rules can also return client-specific denial reasons.

Status Message	Description/Notes
Invalid Lead Provider	The API key and lead_provider_id did not resolve to an active Lead Buy portfolio.
This request_id is already present in Lokyata system. Please provide a unique request_id.	The submitted request_id has already been evaluated and cannot be reused for a normal Lead Buy request.
Invalid Campaign Id: <campaign_id>	The submitted campaign_id did not resolve to an active workflow for the portfolio.

When Campaign Throttling Is Enabled

If campaign throttling is enabled for the client, the API can deny a lead when the portfolio or campaign is inactive, or when the configured campaign capacity has been reached.

Message Pattern	Description/Notes
Not Accepting Leads - Portfolio Not Active	The portfolio is not accepting leads.
Not Accepting Leads - Campaign Not Active	The campaign is not accepting leads.
Not Accepting Leads - Profile Not Active	The configured campaign profile is not accepting leads.
Not Accepting Leads - Profile Day Not Active Not Accepting Leads - Profile Out of Window Not Accepting Leads - No Active Group	The lead was submitted outside an active configured schedule window.
Not Accepting Leads - <Campaign/Profile/Group> Daily Cap Reached	A configured daily capacity limit has been reached.
Not Accepting Leads - <Profile/Group> Hourly Cap Reached (Resets in <n> mins)	A configured hourly capacity limit has been reached.
Not Accepting Leads - <Profile/Group> Hourly Deadzone (Ends in <n> mins)	A configured hourly pause window is active before hourly tracking resumes.