Lead Price Reject

Introduction#

The Lead Price Reject API allows a lead provider to submit borrower lead information to Lokyata for real-time evaluation. Lokyata evaluates the lead and determines whether the lender is willing to purchase it at the submitted price.

If the submitted lead price is acceptable, the API returns an approved response. If the submitted lead price is higher than the price Lokyata is willing to pay, the API returns a denied response and includes the maximum acceptable price.

How Lead Price Reject Works#

The request includes the submitted lead price in lead_price.

Lokyata evaluates the lead and calculates the maximum acceptable price.

If lead_price is less than or equal to the calculated price, the lead can be accepted.

If lead_price is greater than the calculated price, the lead is rejected.

A price rejection includes max_acceptable_price, which is the price the lender is willing to pay for the lead.

The lead provider may submit the same request_id again with a price at or below max_acceptable_price.

Endpoint#

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

Authentication#

Each request must include a valid client-specific API key in the x-api-key request header. Lokyata provides the API hostname and API key for each environment and client integration.

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

Processing Behavior#

The endpoint reads the request body as JSON. Malformed JSON returns a denial-shaped response with the comment Invalid JSON.
The x-api-key and lead_provider_id are used to resolve the client's Lead Buy portfolio.
A normal submission must use a unique request_id. A duplicate request ID is denied unless the request is fulfilling an active lead-price suggestion.
The workflow is selected using the configured campaign and workflow load-balancing configuration.
Campaign status and throttle capacity are checked before full evaluation.
If the workflow calculates a maximum acceptable price and the submitted lead_price is higher, the response is denied and includes max_acceptable_price.
If the lead provider resubmits the same request_id at or below the suggested price before expiration, the duplicate check is bypassed and the lead can continue through evaluation.

Request#

Name	Type	Required	Constraints	Description
`request_id`	`string`	Yes	1-64 chars	Unique ID for the API request. Can be any unique ID generated by the lead provider.
`lead_provider_id`	`string`	Yes	1-30 chars	Unique ID for lead provider or submitter. Values are provided by Lokyata.
`campaign_id`	`string`	Yes	1-64 chars	Campaign configured by lender in the lead provider system. Values are provided by Lokyata.
`affiliate_id`	`string`	Yes	1-64 chars	Unique ID for affiliate provider. Can be any ID from the submitter's system.
`affiliate_sub_id`	`string`	No	max 64 chars	Unique ID for sub-affiliates.
`lead_price`	`number`	Yes		Lender's cost to purchase the lead.
`application_website`	`string`	Yes	1-300 chars	Website used by the customer during application.
`ip_address`	`string`	Yes	max 39 chars	Customer's IP address. Accepts both IPv4 and IPv6 format.
`requested_amount`	`integer`	Yes		Requested loan amount in USD, including dollars and cents.
`ssn`	`string`	Yes	exactly 9 chars	Customer's social security number. Format: all digits; no dashes.
`dob`	`string`	Yes	`yyyy-mm-dd`	Customer's date of birth.
`gender`	`string`	No	max 7 chars	Customer's gender.
`first_name`	`string`	Yes	1-50 chars	Customer's first name.
`middle_initial`	`string`	No	max 1 char	Customer's middle initial.
`last_name`	`string`	Yes	1-50 chars	Customer's last name.
`address`	`string`	Yes	max 300 chars	Customer's home street address.
`address2`	`string`	No	max 100 chars	Customer's home address line 2 - apartment or suite number.
`city`	`string`	Yes	max 100 chars	City of customer's home street address.
`state`	`string`	Yes	exactly 2 chars	State where the customer resides. Format is state two-letter abbreviation.
`zip_code`	`string`	Yes	max 10 chars	Customer's home address zip code. Format is either `nnnnn` or `nnnnn-nnnn`.
`home_phone`	`string`	Yes	numeric, max 50 chars	Customer's home phone number. Format: all numeric digits; no special characters.
`mobile_phone`	`string`	Yes	numeric, max 50 chars	Customer's mobile phone number. Format: all numeric digits; no special characters.
`work_phone`	`string`	Yes	numeric, max 50 chars	Customer's work phone number. Format: all numeric digits; no special characters.
`drivers_license_state`	`string`	Yes	exactly 2 chars	State where customer's driver's license was issued. Format is state two-letter abbreviation.
`drivers_license_number`	`string`	Yes	1-20 chars	Customer's driver's license number. Format: no special characters.
`contact_time`	`string`	No	max 9 chars	Best time to contact the customer.
`is_military`	`boolean`	Yes	`true` or `false`	`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	max 10 chars	Whether the customer owns or rents the residence.
`email`	`string`	Yes	max 300 chars	Customer's email address. Format is `abcd@abcd.abc`.
`residence_months`	`integer`	Yes		Number of months the customer is living in the current residence.
`is_citizen`	`boolean`	Yes	`true` or `false`	`true` = customer is a US citizen and at least 18 years old; `false` = customer is not a US citizen or not at least 18 years old.
`is_subscribed_future_offers`	`boolean`	No	`true` or `false`	`true` = customer subscribed to future offers; `false` = customer did not subscribe to future offers.
`num_installments`	`integer`	No		Number of installments for the loan schedule.
`interest_rate`	`integer`	No		Interest rate to be charged on the loan.
`language`	`string`	No	max 300 chars	Language which customer speaks. If no value is specified, English is used by default.
`income_type`	`string`	Yes	max 20 chars	Customer's income type.
`payment_type`	`string`	Yes	max 20 chars	Customer's payment type.
`employment_type`	`string`	Yes	max 20 chars	Does the customer work full or part-time.
`employment_months`	`integer`	Yes		Number of months the customer has been working with the current employer.
`employer_name`	`string`	Yes	1-100 chars	Name of customer's current employer.
`employment_address`	`string`	Yes	1-300 chars	Street address of the customer's current employer.
`employment_address2`	`string`	No	max 100 chars	Suite or apartment address of the customer's current employer.
`employment_city`	`string`	No	max 50 chars	City where the customer's employer is located.
`employment_state`	`string`	No	exactly 2 chars	State where the customer's employer is located. Format is state two-letter abbreviation.
`employment_zip_code`	`string`	No	max 10 chars	Employer's zip code. Format is either `nnnnn` or `nnnnn-nnnn`.
`employer_phone`	`string`	Yes	numeric, max 13 chars	Phone number of the customer's employer. Format: all numeric digits; no special characters.
`employment_phone_ext`	`string`	No	max 6 chars	Phone number extension of the customer's employer.
`employment_fax`	`string`	No	numeric, max 13 chars	Fax number of the customer's employer. Format: all numeric digits; no special characters.
`supervisor_name`	`string`	Yes	1-100 chars	Name of the customer's supervisor.
`supervisor_phone`	`string`	No	numeric, max 13 chars	Work phone number of the customer's supervisor. Format: all numeric digits; no special characters.
`supervisor_phone_ext`	`string`	No	max 6 chars	Work phone number extension for the customer's supervisor.
`job_title`	`string`	No	max 100 chars	Customer's job title.
`work_shift`	`string`	No	max 15 chars	Customer's work shift.
`pay_frequency`	`string`	Yes	max 15 chars	Customer's pay schedule.
`last_paydate`	`string`	Yes	`yyyy-mm-dd`	Customer's most recent pay date.
`next_paydate`	`string`	Yes	`yyyy-mm-dd`	Customer's next pay date.
`second_next_paydate`	`string`	No	`yyyy-mm-dd`	Customer second pay date after the loan.
`net_monthly_income`	`integer`	Yes		Customer's net monthly income after taxes and other withholding.
`gross_monthly_income`	`integer`	No		Customer's gross monthly income before withholding.
`bank_account_holder`	`string`	No	max 100 chars	Name of the holder of the bank account.
`bank_name`	`string`	Yes	1-50 chars	Customer's bank name.
`bank_phone`	`string`	No	numeric, max 13 chars	Phone number of the customer's bank. Format: all numeric digits; no special characters.
`bank_account_type`	`string`	Yes	max 10 chars	Customer's type of bank account.
`bank_routing_number`	`string`	Yes	exactly 9 chars	American Bankers Association (ABA) routing number for the customer's bank. Format: all digits; no dashes (`nnnnnnnnn`).
`bank_account_number`	`string`	Yes	1-17 chars	Customer's bank account number.
`bank_months`	`integer`	Yes		Number of months the customer has had the bank account.
`is_direct_deposit`	`boolean`	Yes	`true` or `false`	Customer has direct deposit (`true` or `false`).
`outstanding_amt`	`number`	No		Outstanding balance of the customer on other loans.
`reference_first_name`	`string`	No	max 30 chars	Reference's first name.
`reference_last_name`	`string`	No	max 30 chars	Reference's last name.
`reference_phone`	`string`	No	numeric, max 10 chars	Reference's phone number. Format: all numeric digits; no special characters.
`reference_relationship`	`string`	No	max 15 chars	Customer's relationship with the reference.
`user_string`	`string`	Yes		User agent from the loan application.
`sms_opt_in`	`boolean`	No	`true` or `false`	If the customer has opted in for SMS notifications.

Example Request#

curl --location "https://api.xrv3.lokyata.com/process-lp-lr-lead" \  --header "x-api-key: <provided-by-lokyata>" \  --header "Content-Type: application/json" \  --data-raw '{    "request_id": "AKLJOIUWF-956888340",    "bank_name": "ABCD bank",    "lead_provider_id": "LP",    "campaign_id": "lead_price_reject",    "affiliate_id": "342256601",    "affiliate_sub_id": "54321",    "lead_price": 4,    "application_website": "abcd.com",    "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_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  }'

Response Structure#

Business accept, reject, and price decisions are returned in the response body. Normal business denials are not necessarily HTTP transport errors.

Name	Type	Description
`request_id`	`string` or `null`	Request ID submitted by the lead provider.
`decision`	`string`	`Approved` when the lead can be purchased, or `Denied` when the lead is rejected.
`comment`	`string` or `null`	Additional status or denial information.
`redirect_url`	`string` or `null`	Redirect URL when one is available for an approved lead.
`lead_provider_id`	`string`	Lead provider ID from the request.
`campaign_id`	`string`	Campaign ID from the request.
`requested_price`	`number` or `null`	Lead price submitted in the request.
`max_acceptable_price`	`number` or `null`	Maximum price Lokyata is willing to pay when a lower price is suggested.
`reject_reason`	`string` or `null`	Machine-readable rejection reason when available.
`timestamp`	`string`	Response timestamp in ISO 8601 format when available.

Sample Responses#

Accepted Lead#

{  "request_id": "AKLJOIUWF-956888340",  "decision": "Approved",  "comment": null,  "redirect_url": null,  "lead_provider_id": "LP",  "campaign_id": "lead_price_reject",  "requested_price": 5,  "max_acceptable_price": null,  "reject_reason": null,  "timestamp": "2026-06-01T00:00:00+00:00"}

Rejected Lead With Suggested Price#

{  "request_id": "AKLJOIUWF-956888340",  "decision": "Denied",  "comment": "Lead price (25.0) is higher than suggested max price (5.0)",  "redirect_url": null,  "lead_provider_id": "LP",  "campaign_id": "lead_price_reject",  "requested_price": 25,  "max_acceptable_price": 5,  "reject_reason": "Lead price exceeds threshold",  "timestamp": "2026-06-01T00:00:00+00:00"}

Accepted Lead After Suggested Price#

If the lead provider submits the same request_id again with lead_price at or below max_acceptable_price, the lead can be accepted. The response is the same shape as an accepted lead on the first try.

{  "request_id": "AKLJOIUWF-956888340",  "decision": "Approved",  "comment": null,  "redirect_url": null,  "lead_provider_id": "LP",  "campaign_id": "lead_price_reject",  "requested_price": 5,  "max_acceptable_price": null,  "reject_reason": null,  "timestamp": "2026-06-01T00:01:00+00:00"}

Denied Lead#

{  "request_id": "AKLJOIUWF-956888340",  "decision": "Denied",  "comment": "This request_id is already present in Lokyata system. Please provide a unique request_id.",  "redirect_url": null,  "lead_provider_id": "LP",  "campaign_id": "lead_price_reject",  "requested_price": 5,  "max_acceptable_price": null,  "reject_reason": null,  "timestamp": "2026-06-01T00:00:00+00:00"}

Invalid JSON#

{  "request_id": null,  "decision": "Denied",  "comment": "Invalid JSON",  "redirect_url": null}

Missing API Key#

{  "decision": "DENY",  "comment": "Input Validation Failed",  "validation_errors": [    {      "field": "x-api-key",      "reason": "Field required"    }  ]}

Comments - Additional Messages#

Based on the request, campaign, workflow, and price-suggestion 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 unless it is fulfilling an active lead-price suggestion.
Invalid Campaign Id: `<campaign_id>`	The submitted `campaign_id` did not resolve to an active workflow for the portfolio.
Lead price (`<lead_price>`) is higher than suggested max price (`<suggested_price>`)	The workflow calculated a maximum acceptable price and the submitted price was higher. The response includes `max_acceptable_price`.
Lead price (`<lead_price>`) is higher than last suggested price (`<suggested_price>`)	The lead provider resubmitted the same `request_id`, but the new `lead_price` was still above the stored suggested price.

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.