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

TopicSandboxProduction
API base URLhttps://api.demo.lumanu.link/api/resthttps://api.lumanu.com/api/rest
Token endpointhttps://auth-staging.lumanu.com/oauth/tokenhttps://auth.lumanu.com/oauth/token
Token audiencehttps://lumanu-demo.hasura.app/v1/graphqlhttps://lumanu-prod.hasura.app/v1/graphql
Moves real moneyNo. Create test deposits insteadYes
ConventionHow it works
AuthAuthorization: Bearer {access_token} on every request. Tokens last 24 hours.
VersioningLumanu-Version header. Current version: 2026-11-04.
FormatJSON request and response bodies. Send Content-Type: application/json with a body.
IDsUUIDs
MoneyIntegers in the smallest currency unit, with a denomination: 150000 + us_cents is $1,500.00.
TimestampsISO 8601, for example 2026-04-01T00:00:00Z
Paginationlimit (default 25) and offset (default 0). Lists return data and total.
Rate limit2,000 requests every 5 minutes from each IP address, then 429. See Rate limits.
ErrorsJSON 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-Version header, for example Lumanu-Version: 2026-11-04.
  • Without the header, the request uses the version your application is pinned to.
  • Every response includes a Lumanu-Version header with the version that served it.
  • When a version is deprecated, responses at that version include a Deprecation header, and a Sunset header 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

LimitWindowCounted perApplies toOver the limit
2,000 requests5 minutesIP addressEvery endpoint, in both sandbox and production429 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 limit on 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"
    }
  ]
}
  • message describes the error in plain language.
  • code is a stable, uppercase identifier you can match on in your code.
  • errors is only present when specific fields failed validation. Each item names the field and the problem with it.

Status codes

StatusCodeMeaning
400VALIDATION_ERRORThe request body or query parameters are invalid. Check errors for the fields.
400Endpoint-specific codeThe request was valid but the action can't be done, for example NOT_ENOUGH_FUNDS or AMOUNTS_DO_NOT_MATCH. Check message.
400INVALID_API_VERSIONThe Lumanu-Version header names a version that doesn't exist. message lists the supported versions.
400UNSUPPORTED_API_VERSIONThe version has passed its sunset date. Move to a supported version. See Versioning.
401UNAUTHORIZEDThe Authorization header is missing.
401INVALID_JWTThe access token is invalid or has expired. Request a new token. See Authentication.
403FORBIDDEN or an endpoint-specific codeYour 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.
404NOT_FOUNDThe resource doesn't exist, or your application can't see it.
405METHOD_NOT_ALLOWEDThe endpoint doesn't support this HTTP method.
429You've hit the rate limit. See Rate limits.
500INTERNAL_ERRORSomething 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.


Did this page help you?