Getting Started

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.

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.

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

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:

{
  "data": [
    {
      "id": 123456,
      "branchID": 0,
      "loanBrokerID": 0,
      "loanOfficerID": 0,
      "borrowerId": 654321,
      "borrowerName": "Jane Example",
      "borrowerEmail": "[email protected]",
      "loanNumber": "LN-000123",
      "primaryStatusId": 4,
      "activeStatus": 1,
      "createdAt": "2026-08-01T12:34:56Z"
    }
  ],
  "meta": {
    "requestId": "01M0FS5FF3G8RQ2W6H4YKD7XZP",
    "timestamp": "2026-08-20T14:29:36Z",
    "pagination": {
      "page": 1,
      "perPage": 1,
      "total": 4566,
      "totalPages": 4566,
      "hasMore": true
    }
  }
}

The field values above are illustrative; the structure and the field names are exactly what the API
returns.

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.

Error

{ "error": { "code": "…", "message": "…", "requestId": "…", "timestamp": "…" } }

Some errors add details, and validation errors add fields with a message per field.

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 in UTC.

6. Know what failure looks like

Authentication failures are always 401 with code: "UNAUTHENTICATED":

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "invalid token",
    "requestId": "01M0FRRY3DZ9429JVZY070AJ3F",
    "timestamp": "2026-08-20T14:21:34Z"
  }
}

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), BAD_REQUEST (400), METHOD_NOT_ALLOWED (405),
UNSUPPORTED_MEDIA_TYPE (415), RATE_LIMITED (429), INTERNAL_ERROR (500).

7. 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.

8. 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.

Three practical notes if you are already on it:

All three endpoints are POST only. A GET returns 405 METHOD_NOT_ALLOWED with
details.allowed: ["POST"].
Credentials go in the request body, never the URL. Sending client_id and client_secret as
query parameters returns 400 BAD_REQUEST and explains why. There is likewise no query-string way
to present a token on any v4 route: the Authorization header is the only accepted transport, and
a token supplied any other way is ignored and the request rejected 401 UNAUTHENTICATED.
Depending on the environment, responses to a legacy-authenticated v4 request may carry RFC 8594
Deprecation, Warning and Link headers. 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 v4 surface — loans, loan assignments, loan reference
data and user profiles — each endpoint with 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.