API 4.1 took effect on Wednesday, November 18, 2026. What's new in API 4.1 lists every change.
The LendingWise v4 API is a JSON REST API for reading and managing loan files. Every call is
authenticated with a tenant API key, and every response comes back in the same envelope.
The reference is described with OpenAPI 3.1, so you can generate a client from it with the
tooling you already use.
This page takes you from nothing to a working call. API 4.1 keeps the base path /api/v4, and your API
key keeps working.
1. Get your API key
Your LendingWise administrator creates the API key for your company and gives you the value.
A few things follow from how keys work, and they matter:
- The key belongs to your company, not to a person. If the administrator who created it leaves,
the key keeps working. - It is shown once, when it is created. LendingWise stores only a hash of it and cannot show it
to you again. Put it straight into your secret store. - There is no self-service endpoint. Keys are not issued through the public API; ask your
LendingWise administrator or your LendingWise contact. - Its access to personal data is fixed when it is created. Once LendingWise's Integration Hub offers
the choice, shortly after the release, your administrator chooses Masked, No or Yes for
what the key may read of SSNs, driver's licences, dates of birth and the entity's EIN (the broker
directory'seinNumberreads as stored for every key). Until then every key is
Masked, as in 4.0. To change a key's setting, generate a new key. See PII access for API keys
in What's new in API 4.1.
A key looks like this — a number, a pipe, then a long random string:
42|xJ3kQ9mPvR2sT7wY4bN6hL8dF1gC5aZ0eU3iO9pK7c4a8d09
Treat it exactly as you would a password.
2. Base URL
Every v4 call goes to the same host:
https://api.lendingwise.com
Paths on this page are relative to it — for example GET /api/v4/loans is
https://api.lendingwise.com/api/v4/loans.
3. Send the key
Put the key in the Authorization header of every request, after the word Bearer:
Authorization: Bearer 42|xJ3kQ9mPvR2sT7wY4bN6hL8dF1gC5aZ0eU3iO9pK7c4a8d09
That header is the only place a credential is accepted. The API does not read credentials from
the query string, so never put a key in a URL — URLs end up in server logs, proxy logs, browser
history, and the Referer header of onward requests, none of which you can clear.
4. Make your first call
Check that the key works by asking who it is:
curl -sS "https://api.lendingwise.com/api/v4/me" \
-H "Authorization: Bearer $LENDINGWISE_API_KEY" \
-H "Accept: application/json"For an API key, principalType is api-key, companyId and companyName name the company your calls
act for, and accessScope is company: the key reaches every loan file in that company.
Then read a loan file:
curl -sS "https://api.lendingwise.com/api/v4/loans?per_page=1" \
-H "Authorization: Bearer $LENDINGWISE_API_KEY" \
-H "Accept: application/json"A 200 comes back shaped like this. The row is shortened; the reference lists every field.
{
"data": [
{
"id": 123456,
"branchId": 12,
"branchID": 12,
"brokerId": 3407,
"loanBrokerID": 3407,
"loanOfficerId": null,
"loanOfficerID": null,
"borrowerId": 654321,
"borrowerName": "Jane Example",
"borrowerEmail": "[email protected]",
"loanNumber": "LN-000123",
"primaryStatusId": 4,
"primaryStatusLabel": "Lead",
"active": true,
"activeStatus": 1,
"createdDate": "2026-08-01",
"createdAt": "2026-08-01"
}
],
"meta": {
"requestId": "01M0FS5FF3G8RQ2W6H4YKD7XZP",
"timestamp": "2026-11-18T09:29:36-05:00",
"pagination": {
"page": 1,
"perPage": 1,
"total": 4566,
"totalPages": 4566,
"hasMore": true
}
}
}The field values above are illustrative. Some fields carry a new name beside the old one, such as
branchId beside branchID: both are sent until the old name is removed on a date announced in the API
changelog, 90 days after the announcement. New code should read the new names; the full list is under
New names for existing fields in What's new in API 4.1.
An API key pages GET /api/v4/loans with per_page (25 rows unless it says otherwise). It ignores
perPage, as 4.0 did. That reply carries a Deprecation header, because per_page is an old name
on other lists: on this route, for an API key, ignore it for now. No removal date is announced.
If you would rather start with something smaller, GET /api/v4/loan-types returns your tenant's
configured loan types and needs no parameters.
5. Read the envelope
Every v4 response uses the same two-part shape, so you can write one handler for all of them.
Success
{ "data": <the result>, "meta": { "requestId": "…", "timestamp": "…" } }meta also carries pagination on paginated lists and count on unpaginated ones. Two more entries
appear only when they have something to say:
warnings: on a loan write,FIELD_IGNOREDnames some fields you sent that were accepted and not
stored (listed under Writes in What's new in API 4.1); other ignored keys
get no warning. On anyGET,UNKNOWN_PARAMETERnames a query parameter the endpoint does not read, so the
answer is not narrowed by it.dryRunandeffects: on a dry run (step 9).
Error
{
"error": { "code": "…", "message": "…" },
"meta": { "requestId": "…", "timestamp": "…" }
}Some errors add details, and validation errors add fields with a message per field. A refused call
also still carries error.requestId and error.timestamp. They are deprecated in favour of meta and
will be removed on a date announced in the API changelog.
requestId is a 26-character ULID present on every response, success or failure, and repeated in the
X-Request-Id response header. Log it. Quoting it to support identifies the exact call.
timestamp is the server's response time, ISO 8601 with the US Eastern offset (-05:00 in winter,
-04:00 in summer), like every date-time the API returns. If your code compares times, parse the
offset; do not assume Z.
6. Know what failure looks like
Authentication failures are always 401 with code: "UNAUTHENTICATED":
{
"error": {
"code": "UNAUTHENTICATED",
"message": "invalid token",
"requestId": "01M0FRRY3DZ9429JVZY070AJ3F",
"timestamp": "2026-11-18T09:21:34-05:00"
},
"meta": {
"requestId": "01M0FRRY3DZ9429JVZY070AJ3F",
"timestamp": "2026-11-18T09:21:34-05:00"
}
}Two messages are worth telling apart:
message | What happened |
|---|---|
unauthorized | No Authorization header, or an empty one. |
invalid token | A token arrived and was not accepted — unknown, revoked, rotated, or expired. |
invalid token is deliberately the same for every rejected credential. It does not tell you which
part failed, because that would help someone guessing.
The other codes the API uses, all in the same envelope: VALIDATION_FAILED (422), FORBIDDEN (403),
RESOURCE_NOT_FOUND (404), RESOURCE_CONFLICT (409), RESOURCE_GONE (410), BAD_REQUEST (400),
METHOD_NOT_ALLOWED (405, with an Allow header naming the methods the path accepts),
UNSUPPORTED_MEDIA_TYPE (415), RATE_LIMITED (429), DEPENDENCY_FAILED (502), INTERNAL_ERROR (500).
7. How fast you can call
Each API key may make 120 calls a minute. The allowance is counted against your key, not the
machine the call came from, so all your servers share one allowance, and two companies calling from the
same address each get their own. A minute starts with your first call and lasts 60 seconds. Signing in
with POST /api/v4/authenticate is limited separately and more tightly: 30 a minute for each
client_id from each address.
Every reply to a call made with your API key tells you where you stand:
| Header | What it means |
|---|---|
X-RateLimit-Limit | How many calls you may make in the current minute. |
X-RateLimit-Remaining | How many of those you have left. |
Go over and the call is refused with 429 and an error.code of RATE_LIMITED. Nothing you sent is
saved. The reply tells you how long to wait:
{
"error": {
"code": "RATE_LIMITED",
"message": "Too Many Attempts.",
"details": { "retryAfterSeconds": 41 }
},
"meta": {
"requestId": "01K2Z9V8QK7YB3M4N5P6R7S8T9",
"timestamp": "2026-11-18T09:21:34-05:00"
}
}Retry-After carries the same number of seconds as a header, and X-RateLimit-Reset gives the same
moment as a Unix time in seconds (UTC).
What to do when you see one. Wait for Retry-After seconds, then send the same request again —
it is safe to repeat, because a refused call changes nothing. Do not retry straight away in a loop:
that spends your next allowance the moment it arrives and keeps you locked out. If you are running a
batch, watch X-RateLimit-Remaining and ease off before it reaches 0. If you run a large sync that
needs more than 120 calls a minute, ask support: a higher allowance can be set for your key alone.
8. Retry a create safely
If a call times out, you cannot tell whether it landed. These calls accept an Idempotency-Key header
so that a retry does not create a second record: POST /api/v4/loans,
POST /api/v4/loans/{id}/properties, POST /api/v4/loans/{id}/members, POST /api/v4/document-types,
POST /api/v4/loans/{id}/document-checklist/{slot}/files and POST /api/v4/tasks.
- Send a key you generate, such as a UUID, at most 64 characters.
- The same key with the same body returns the original result, plus
Idempotency-Replayed: true, and
creates nothing. - The same key with a different body answers
409. That is a bug in your code, not a safe retry. - Without the header, the call behaves as it always has.
A replay shows the record as it is now, not a copy of the first reply. A key is kept for at
least 24 hours; after that, a reused key may replay or may create a new record, so use a new key for each
new request. "The same" means the same path, query string and body.
9. Preview a loan write
Add ?dryRun=true to POST /api/v4/loans or PATCH /api/v4/loans/{id} to see what the write would
do. The request runs and is then undone, so nothing is kept. The answer carries meta.dryRun: true and
meta.effects.
- Send it in the query string, spelled exactly
dryRun, astrue/false,1/0oryes/no. Another
spelling in the query string, ordryRunon any other route, is refused with422rather than ignored,
and so is adryRunin the body of a loan, property or member write. - ⚠️ Send it only to a server whose replies carry
X-LW-Capabilities: loan-dry-run. A server without the
dry run, including/api/v4before the release date, ignores the parameter and makes the change. - A change that cannot be previewed safely answers
409 RESOURCE_CONFLICTwith
error.details.reasonDRY_RUN_UNSAFE.
10. Lifetime, rotation and revocation
Your key does not expire. There is no refresh cycle to build and no expiry to schedule around —
this is the main practical difference from the older token flow. A key stops working only when
someone stops it:
- Revoked — an administrator turns it off. The very next request returns
401 invalid token;
there is no grace period. - Rotated — a new value is issued and the old one is destroyed at the same moment. Deploy the new
value before rotating, because the old one stops working immediately.
Both take effect on the next request, not when some timer runs out. Plan for a key change to be a
deploy, not a background refresh.
11. Reads and writes
Your key carries both read and write permission. Reads are GET, HEAD and OPTIONS; everything
else counts as a write. A key without the permission a call needs gets 403 FORBIDDEN with a message
naming what was missing.
Legacy authentication — deprecated, and not for new integrations
Before tenant API keys, v4 callers exchanged a client_id and client_secret at
POST /api/v4/authenticate for a JWT, kept it alive with POST /api/v4/refresh, and checked it with
POST /api/v4/validate. Those tokens last 72 hours (expires_in: 259200).
That flow still works and is deprecated. Build new integrations on a tenant API key: one
non-expiring string, one header, no refresh loop.
Four practical notes if you are already on it:
- All three endpoints are
POSTonly. AGETreturns405 METHOD_NOT_ALLOWEDwith
details.allowed: ["POST"]. - Credentials go in the request body, never the URL. Sending
client_idandclient_secretas
query parameters returns400 BAD_REQUESTand explains why. There is likewise no query-string way
to present a token on any v4 route: theAuthorizationheader is the only accepted transport, and
a token supplied any other way is ignored and the request rejected401 UNAUTHENTICATED. - Signing in is limited to 30 a minute for each
client_idfrom each address (step 7). - Depending on the environment, responses to a legacy-authenticated v4 request may carry RFC 8594
Deprecation,WarningandLinkheaders. Where they are enabled, treat them as the signal to
migrate.
No retirement date has been set. Legacy authentication is not scheduled to stop working, and
nothing on this page implies a deadline. If that changes, it will be announced.
Where to go next
The API Reference in the sidebar covers the whole v4 surface: health checks, sign-in, your own
credential (GET /api/v4/me), loans and the pipeline summary, loan assignments, loan reference data,
document reference data, loan documents, custom fields, tasks and user profiles. Each endpoint has its
parameters, response schema and error codes. Bring the key from step 1 and the Authorization header
from step 3, and every one of them will answer.
What's new in API 4.1 lists everything that changes from 4.0.

