Helio Genie API

v1.0

The Helio Genie Partner API allows inverter brands, distributors and service platforms to embed technician dispatch directly into their own applications. When a fault is detected in your system, a single API call connects your user with the nearest verified solar technician.

Base URL
https://heliogenie-backend.rotimiolowofela.workers.dev

Submit your details via the register endpoint or the partners page to get your API key

Test in sandbox

Use your sandbox key to test the integration safely before going live

Go live

Swap to your live key and your users can book technicians in seconds

Authentication

All API requests must include your API key. Pass it either in the request body as api_key or in the request header as X-API-Key.

Header authentication (recommended)

// Include in your HTTP headers
X-API-Key: hg_live_your_key_here

Body authentication

{
  "api_key": "hg_live_your_key_here",
  // ... rest of your request
}

Keep your API key secret. Never expose your live key in client-side code, mobile app source, or public repositories. Always call the API from your backend server.

Sandbox Environment

The sandbox environment lets you test your integration safely without dispatching real technicians. Sandbox requests are identified by API keys beginning with hg_test_.

Sandbox key format

hg_test_sandbox123   // Use this for all sandbox testing

Sandbox responses return a fake technician with realistic data so you can build and test your UI without affecting the live technician network. Sandbox requests are logged separately and do not count toward your production usage.

POST /api/v1/request-technician

Dispatches a technician booking request on behalf of one of your users. Returns a matched technician and booking reference immediately.

POST /api/v1/request-technician

Request Parameters

Parameter	Type	Required	Description
api_key	string	Required	Your partner API key. Can also pass in X-API-Key header.
brand	string	Required	Inverter brand name e.g. "Luminous", "Victron", "Growatt"
user_location	object	Required	Object with `lat` and `lng` coordinates
model	string	Optional	Inverter model e.g. "NXG 1400", "MultiPlus 3000"
fault_code	string	Optional	Active fault code from the inverter e.g. "E05", "F03"
battery_pct	number	Optional	Current battery percentage 0-100
system_type	string	Optional	One of: hybrid, separate, basic. See system types reference.
user_phone	string	Optional	User's phone number for technician to contact directly
additional_data	object	Optional	Any additional readings from your monitoring system

Example Request

// JavaScript / fetch
const response = await fetch('https://heliogenie-backend.rotimiolowofela.workers.dev/api/v1/request-technician', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'hg_test_sandbox123'
  },
  body: JSON.stringify({
    brand: 'Luminous',
    model: 'NXG 1400',
    fault_code: 'E05',
    battery_pct: 12,
    system_type: 'hybrid',
    user_location: { lat: 6.5244, lng: 3.3792 },
    user_phone: '08012345678'
  })
});

const data = await response.json();
console.log(data.booking_id); // HG-2026-00847

Example Response

{
  "status": "sandbox_matched",
  "booking_id": "HG-2026-00847",
  "timestamp": "2026-04-20T10:30:00.000Z",
  "technician": {
    "name": "Test Technician (Sandbox)",
    "distance_km": 2.1,
    "rating": 4.8,
    "eta_minutes": 30,
    "phone": "+234 800 000 0000"
  },
  "fault_summary": {
    "severity": "critical",
    "summary": "Battery critically low at 12%. E05 indicates deep discharge protection activated.",
    "recommended_action": "Check battery bank and solar charge input immediately."
  },
  "next_steps": [
    "This is a sandbox response — no real technician was dispatched",
    "Use hg_live_* key for production"
  ]
}

POST /api/v1/partner/register

Registers a new partner and immediately issues a sandbox API key for testing. A live key is issued after manual review by the Helio Genie team.

POST /api/v1/partner/register

Parameter	Type	Required	Description
company_name	string	Required	Your company or brand name
email	string	Required	Work email for API key delivery and support
contact_name	string	Required	Name of the technical or business contact
use_case	string	Required	Brief description of how you plan to use the API
expected_monthly_bookings	number	Optional	Estimated monthly booking volume for revenue share discussion

GET /

Returns the current API status. Use this to confirm connectivity before making requests.

GET /

{
  "status": "ok",
  "service": "Helio Genie API",
  "version": "1.0.0"
}

System Types Reference

Value	Description	Common Brands
hybrid	All-in-one unit combining inverter, MPPT and battery management	Victron MultiPlus, Growatt SPF, Voltronic Axpert, Luminous
separate	Standalone inverter with separate MPPT charge controller	Luminous, Su-Kam, Felicity + EPSolar, Renogy
basic	LED indicator only — no digital display	Generic Chinese brands, basic Luminous/Su-Kam

Error Codes

HTTP Status	Code	Description
401	AUTH_REQUIRED	No API key provided
401	INVALID_KEY	API key not recognised or revoked
400	MISSING_FIELD	A required field is absent from the request
400	INVALID_LOCATION	user_location must include both lat and lng
500	SERVER_ERROR	Unexpected server error — contact support

Webhooks

Webhooks allow Helio Genie to push booking status updates to your server in real time — when a technician accepts, completes or cancels a job.

Coming soon. Webhook support is on the roadmap for API v1.1. For now, use the booking_id returned from the request-technician endpoint to poll for status updates.

Planned webhook events

Event	Triggered when
booking.accepted	A technician accepts the booking request
booking.completed	Technician marks the job as complete
booking.cancelled	Booking is cancelled by either party
booking.expired	No technician accepted within 20 minutes

Questions about the API? Email hello@heliogenie.com.ng or visit the partners page.