Submit Loan Offers

post

https://{your-totality-url}.com/api/loans/offers

Submit a batch of loan offers from an external decisioning provider (e.g., Lokyata) for a specific loan, identified by loanUuid in the request body. Each offer becomes a row in the loan_offers table; selection of a winning offer happens later via the in-app UI (no API endpoint exposes selection). All offers in a single request share a server-generated requestUuid that identifies the batch. The entire batch is wrapped in a database transaction — if any offer fails validation, none persist. Monetary fields (amount, paymentAmount) are integers in cents. numberOfPayments is the installment count; combined with paymentFrequency it defines the schedule (e.g., 12 monthly, 52 weekly, 26 bi-weekly). originationFeePercentage (optional) is the percentage applied to the loan when the offer is selected. downPayment (optional, integer cents) is the down payment the customer is expected to bring; when present, accepting the offer overwrites the loan's recorded down payment.

Note: when a customer accepts an offer, the offer's terms become the loan's authoritative terms. Any CSO Target APR or per-payment CSO fee configured on the loan is cleared so the resulting amortization schedule matches the offer exactly. To ingest offers on a CSO-configured product without losing CSO fee structure, the offer payload must be extended (planned in a future enhancement).

Permission: Submit Loan Offers (loans.offers.post).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

loanUuid

uuid

required

UUID of the loan to attach the offers to.

offers

array of objects

required

length ≥ 1

Batch of loan offers. At least one offer is required.

offers*

amount

integer

required

≥ 1

Offered principal amount, in cents.

apr

number

required

≥ 0

Annual percentage rate as a percentage (e.g., 12.5 for 12.5%).

daysInPeriod

integer | null

≥ 1

Number of days between scheduled payments. Required when paymentFrequency is days; ignored otherwise. For example, send paymentFrequency=days, daysInPeriod=10 for a payment every 10 days.

downPayment

integer | null

≥ 0

Optional down payment amount the customer is expected to bring at origination, in cents. When the customer accepts the offer, this value overwrites the loan's down payment. When omitted or null, the loan's down payment is set to 0.

externalId

string | null

Optional provider-side identifier for this offer (e.g., the decisioner's offer ID). Useful for cross-referencing back to the provider's system; not enforced as unique.

numberOfPayments

integer

required

≥ 1

Number of payment installments over the life of the loan. Combined with paymentFrequency to define the schedule (e.g., 12 with frequency monthly = 12 monthly payments; 52 with frequency weekly = a year of weekly payments).

originationFeePercentage

number | null

0 to 100

Optional origination fee as a percentage of the loan amount (e.g., 5 for 5%). When the customer accepts the offer, this value is applied to the loan and factored into the amortization schedule. When omitted or null, no origination fee is applied.

paymentAmount

integer

required

≥ 1

Amount of each scheduled payment installment, in cents.

paymentFrequency

string

enum

required

Cadence at which scheduled payments occur. Must match one of the allowed values.

Allowed:

productType

string | null

Optional product label (e.g., "Personal").

tier

string | null

Optional decisioning tier label.

source

string | null

Optional name of the decisioning provider that produced the offers (e.g., "Lokyata").

201Offers persisted

403Forbidden - invalid scope

422Validation error