API Overview
How the Lumanu Partner API works: base URLs, authentication, versioning, request and response conventions, rate limits, error codes and webhooks
The Lumanu Partner API is a REST API for platforms that pay creators, talent managers, agencies and other vendors through Lumanu. With it you can create and manage Buyer workspaces, invite vendors, create and approve payables, fund and pay them, and reconcile wallet activity. Core Concepts lists every endpoint, grouped by entity. To get access and make your first request, see the Quickstart Guide.
At a glance
| Topic | Sandbox | Production |
|---|---|---|
| API base URL | https://api.demo.lumanu.link/api/rest | https://api.lumanu.com/api/rest |
| Token endpoint | https://auth-staging.lumanu.com/oauth/token | https://auth.lumanu.com/oauth/token |
| Token audience | https://lumanu-demo.hasura.app/v1/graphql | https://lumanu-prod.hasura.app/v1/graphql |
| Moves real money | No. Create test deposits instead | Yes |
| Convention | How it works |
|---|---|
| Auth | Authorization: Bearer {access_token} on every request. Tokens last 24 hours. |
| Versioning | Lumanu-Version header. Current version: 2026-11-04. |
| Format | JSON request and response bodies. Send Content-Type: application/json with a body. |
| IDs | UUIDs |
| Money | Integers in the smallest currency unit, with a denomination: 150000 + us_cents is $1,500.00. |
| Timestamps | ISO 8601, for example 2026-04-01T00:00:00Z |
| Pagination | limit (default 25) and offset (default 0). Lists return data and total. |
| Rate limit | 2,000 requests every 5 minutes from each IP address, then 429. See Rate limits. |
| Errors | JSON body with message, code and, for validation errors, errors. See Errors. |
Explore the docs
Authentication
Every request needs an access token in the Authorization header:
Authorization: Bearer {access_token}You get a token from the auth domain with either the client credentials flow, for server-to-server integrations, or the OAuth authorization code flow, to act on behalf of a Lumanu user. Access tokens are valid for 24 hours. See Authentication.
Versioning
The API is versioned by date. The current version is 2026-11-04.
- To choose a version for a request, send the
Lumanu-Versionheader, for exampleLumanu-Version: 2026-11-04. - Without the header, the request uses the version your application is pinned to.
- Every response includes a
Lumanu-Versionheader with the version that served it. - When a version is deprecated, responses at that version include a
Deprecationheader, and aSunsetheader with the date from which it will be rejected.
Adding new fields, endpoints or optional parameters doesn't create a new version, so make sure your code ignores fields it doesn't recognize.
Requests and responses
List endpoints are paginated with limit and offset, and return the records in data with the total count:
{
"data": [],
"total": 0,
"limit": 25,
"offset": 0
}Rate limits
| Limit | Window | Counted per | Applies to | Over the limit |
|---|---|---|---|---|
| 2,000 requests | 5 minutes | IP address | Every endpoint, in both sandbox and production | 429 response |
A 429 response will be returned after the limit has been hit. Requests succeed again once your request count for the last 5 minutes drops back under the limit.
Handling 429 responses
- Retry with exponential backoff, for example after 1, 2, 4 and 8 seconds, up to a few minutes.
- Spread bulk work, such as creating many payables or backfilling records, over time instead of sending it in one burst.
- Use webhooks to learn about changes instead of polling list endpoints.
- Raise
limiton list endpoints (the default is 25) to fetch more records per request.
async function lumanuRequest(url, options, attempt = 0) {
const response = await fetch(url, options);
if (response.status === 429 && attempt < 5) {
const delayMs = 1000 * 2 ** attempt; // 1s, 2s, 4s, 8s, 16s
await new Promise((resolve) => setTimeout(resolve, delayMs));
return lumanuRequest(url, options, attempt + 1);
}
return response;
}
Need a higher limit?If your integration needs more than 2,000 requests every 5 minutes, contact Lumanu.
Errors
The API uses standard HTTP status codes. A 2xx code means the request succeeded, a 4xx code means there is a problem with the request, and a 5xx code means something went wrong on Lumanu's side.
Error response body
Every error response has the same JSON shape:
{
"message": "Validation failed",
"code": "VALIDATION_ERROR",
"errors": [
{
"field": "amount",
"message": "amount is a required field"
}
]
}messagedescribes the error in plain language.codeis a stable, uppercase identifier you can match on in your code.errorsis only present when specific fields failed validation. Each item names thefieldand the problem with it.
Status codes
| Status | Code | Meaning |
|---|---|---|
400 | VALIDATION_ERROR | The request body or query parameters are invalid. Check errors for the fields. |
400 | Endpoint-specific code | The request was valid but the action can't be done, for example NOT_ENOUGH_FUNDS or AMOUNTS_DO_NOT_MATCH. Check message. |
400 | INVALID_API_VERSION | The Lumanu-Version header names a version that doesn't exist. message lists the supported versions. |
400 | UNSUPPORTED_API_VERSION | The version has passed its sunset date. Move to a supported version. See Versioning. |
401 | UNAUTHORIZED | The Authorization header is missing. |
401 | INVALID_JWT | The access token is invalid or has expired. Request a new token. See Authentication. |
403 | FORBIDDEN or an endpoint-specific code | Your application isn't allowed to do this. Most access problems return 400 instead, with a specific code such as MISSING_PERMISSION or INVALID_ORGANIZATION_ID. Some endpoints return 403 with their own code, such as TAX_NOT_ENABLED on Create Funding. |
404 | NOT_FOUND | The resource doesn't exist, or your application can't see it. |
405 | METHOD_NOT_ALLOWED | The endpoint doesn't support this HTTP method. |
429 | You've hit the rate limit. See Rate limits. | |
500 | INTERNAL_ERROR | Something went wrong on Lumanu's side. Retry later, and contact Lumanu if it continues. |
Webhooks
Lumanu sends signed webhook events when workspaces, payables, transfers and partners change. Set your webhook URL in the developer portal, then verify each event's X-Signature header. See Webhooks.
Docs for AI tools
Every page on this site is also available as Markdown: add .md to its URL, for example https://developers.lumanu.com/docs/core-concepts.md. llms.txt lists every page.
Updated about 4 hours ago