Build on Jualink

• 400 invalid_json the body isn't JSON
• 401 unauthenticated no or invalid credentials
• 403 forbidden wrong account type, missing scope or cross-site request
• 404 not_found doesn't exist, or isn't yours
• 409 conflict the record's state doesn't allow it
• 422 validation_failed see error.fields
• 429 rate_limited wait for Retry-After seconds
• 500 internal_error quote the X-Request-Id to support

Limits: 600 requests a minute per person or key, 120 per address for public endpoints, 20 estimates a minute per address and 120 monitoring pushes a minute per device. Bodies up to 1 MB. Lists return everything that belongs to you, except financing applications (the 200 most recently updated).

Service health

Checks the API and its database. Returns 503 when the database is unavailable.

OpenAPI 3.1 document

This API described as OpenAPI 3.1 (JSON Schema 2020-12). The document itself is returned, not wrapped in `data`.

Who am I

The user (or API key) the request is authenticated as. Any valid API key may call it.

Active countries and regions

Countries where the service is live or piloting, with region codes and sun-hour assumptions.

Appliance catalogue

Typical wattages and daily hours. With propertyType, appliances relevant to it come first.

Estimate a solar system

Runs the sizing engine with the country's configured prices and the region's sun hours. Nothing is stored. Mix catalogue items ({ key, quantity }) and custom ones ({ name, watts, quantity, hoursDay, hoursNight }).

Start an assessment

Get an assessment

Replace the appliance list

Save backup and usage answers

Run the sizing engine and store the three options

Choose Essential, Recommended or Maximum

Verified products

Only products whose documentation the platform team reviewed (verificationStatus VERIFIED).

A verified product with supplier offers

Verified installers

A verified installer's public profile

Ask matched installers for proposals

Needs a completed assessment with a chosen option. consentToShare must be true: it records the customer's consent to share the assessment with matched installers.

My quote requests

Compare proposals for a request

Accept a proposal and start the project

My projects

A project I'm part of

For the customer, the awarded installer (session or projects:read key) and staff. Customer contact details are shown to the installer; financing details only to the customer and staff.

My payments

Warranties on my systems

Claim under a warranty

My maintenance requests

Request a maintenance visit

My notifications

Available to every signed-in user, newest first.

Mark notifications read

Quote-request leads for my company

A lead with the customer's assessment

Opening a lead marks it viewed. The customer is identified by first name until they accept a proposal.

Send or revise a proposal

Only verified installers. Totals and tax are computed server-side from the items.

Projects awarded to my company

Mark equipment ordered

Mark equipment delivered

Record installed equipment serial numbers

After installation has started. A serial already recorded on another system is refused.

Applications sent to my organisation

At most 200, most recently updated first. meta.counts has the pipeline counts per status.

One application

Identity and bank numbers are masked unless ?reveal=true, which decrypts them while the customer's consent is active and writes an audit entry.

Review, request information, decline or make an offer

Body by action: {action:"start_review"} | {action:"request_info", message} | {action:"reject", reason} | {action:"offer", amount, termMonths, annualRatePct, interestMethod, upfrontFees?, monthlyFee?, conditions?, expiresInDays?}.

Mark an accepted offer funded

The disbursed amount must match the accepted offer. Records the disbursement against the project's payment schedule.

Report repayment status

Register a monitoring device on a Solar Passport

For the system's owner, its installer (session or monitoring:write key) or staff. Returns the device token once; registering the same provider and externalId again rotates it.

Push readings from a device

Authenticate with `Authorization: Device <token>`. Up to 500 readings per call; a reading for a time already stored is counted as a duplicate, so retries are safe. Power in W (gridPowerW + import / − export; batteryPowerW + charging / − discharging), batterySocPct 0–100.

Marketplace KPIs

Payment providers

Configure these URLs in each provider's dashboard. A webhook that fails verification gets 401 and nothing is recorded. Verified events settle the payment once, however many times they arrive.

• https://jualink.com/api/webhooks/payments/paystack: signed with HMAC-SHA512 of the body using your secret key (x-paystack-signature).
• https://jualink.com/api/webhooks/payments/flutterwave: verif-hash must equal FLUTTERWAVE_WEBHOOK_HASH; the transaction is then re-verified with Flutterwave.
• https://jualink.com/api/webhooks/payments/mpesa?token=…: set automatically as the STK Push callback. Daraja callbacks aren't signed, so each payment gets its own token, checked against the CheckoutRequestID. We answer {"ResultCode":0,"ResultDesc":"Accepted"}.

Events to financing partners

Set an HTTPS endpoint at /lender/api. We POST JSON with ids and statuses only; fetch details with your key. One attempt, 5 second timeout, any 2xx counts as delivered. Retries aren't built yet, so reconcile with GET /financing/applications.

• application.submitted A customer sent you a new financing application.
• application.withdrawn The customer withdrew an application (and its data-sharing consent).
• application.info_provided The customer answered your request for more information.
• offer.accepted The customer accepted your offer. Mark the loan funded once you disburse.
• offer.declined The customer declined your offer.
• ping A test event sent from the API & integrations page.

POST /your/endpoint
Content-Type: application/json
X-Jualink-Event: application.submitted
X-Jualink-Timestamp: 1790000000
X-Jualink-Signature: sha256=5d41…

{ "id": "0199…", "type": "application.submitted",
  "createdAt": "2026-09-26T10:00:00.000Z",
  "data": { "applicationId": "…", "reference": "FIN-2026-…",
            "status": "SUBMITTED", "amountRequested": 3200000,
            "depositAmount": 800000, "termMonths": 24,
            "currency": "NGN", "projectReference": "PRJ-2026-…" } }

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the exact request body, before JSON.parse
export function verify(rawBody, headers, secret) {
  const ts = headers["x-jualink-timestamp"];
  const sig = headers["x-jualink-signature"] ?? "";
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`).digest("hex");
  return sig.length === expected.length &&
    timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Your signing secret is shown at /lender/api. It is derived from a platform secret and your partner id, so it can't be rotated on its own yet; per-partner rotation is planned.

WhatsApp estimate assistant

Point the WhatsApp Cloud API webhook at https://jualink.com/api/webhooks/whatsapp. Meta's verification request is answered when hub.verify_token matches WHATSAPP_VERIFY_TOKEN; message deliveries must carry a valid X-Hub-Signature-256 (WHATSAPP_APP_SECRET). The assistant asks what the customer wants to power, the appliances, backup hours and location, shows the three options with prices, and hands over to the website with a private link. Numbers are never stored, only a keyed hash. Replies are sent when WHATSAPP_PROVIDER=meta, and messages are processed only while the whatsapp feature flag is on. Try it in the simulator.

Monitoring

Register a device on a Solar Passport with POST /monitoring/devices, then push readings to POST /monitoring/readings, or let the vendor push its own format to https://jualink.com/api/webhooks/monitoring/<adapter> with the same device token (header, or ?token= if the vendor can only store a URL). Readings are stored as sent and never estimated; a repeated timestamp is a duplicate, so retries are safe. Owners get a "Battery low" alert below 20% (at most daily). Offline alerts are sent by the background job markOfflineDevices() when the worker runs it; the energy view marks a device offline after 60 minutes without data either way. Production accepts readings only with MONITORING_INGEST_ENABLED=true.

{ "readings": [ {
    "recordedAt": "2026-09-26T12:00:00Z",
    "pvPowerW": 1850,        // solar output
    "loadPowerW": 640,       // consumption
    "gridPowerW": 0,         // + import, − export
    "batteryPowerW": 1150,   // + charging, − discharging
    "batterySocPct": 76.5,
    "pvEnergyTodayWh": 5400  // optional, device's own counter
} ] }