Saudi Energy data API: bills, kWh and outages

Saudi Energy · Utilities

Saudi Energy is the official self-care app of Saudi Energy, the consumer brand of the Saudi Electricity Company (SEC), for residential, commercial and industrial electricity account holders across Saudi Arabia. After Rayah OTP sign-in with a national ID or iqama — Face ID or fingerprint can unlock later sessions — the home lists every contract account on the partner, then the customer pays a postpaid bill with PayFort or Apple Pay, recharges a prepaid meter, runs a Hasibati mid-cycle estimate, reports an outage with GPS, opens a Tawasul ticket, files a complaint, requests extra demand load, or checks a welfare refund. Guest pay settles a bill from only the contract-account number, with no full login. Copy is Arabic and English; the app is the nationwide official client sitting beside SADAD bill-pay and Absher rather than a competing utility.

Hasibati estimates pin a contractAccountID to a meterNumber and return ForecastBillAmount against the same Vkont / PartnerNo keys that identify every postpaid account. Dashboard rows carry totalDueAmount, BilledAmount and LastPaymentDate; consumption history splits usage into currentMeterRead / previousMeterRead and tariff bands priced in halalah per kWh, while prepaid accounts expose PrepaidBalance and LastRechargeDate. Outage and Tawasul tickets add ticketNumber; PayFort checkout returns a payment URL keyed by fortId and hash.

Bill-desk and ERP teams reconcile SAR due amounts and prepaid top-ups, operations teams consume outage and complaint ticket status, and efficiency tools read kWh slabs plus Hasibati estimates. openData Studio turns those fields into callable open data.

Screenshots

API surface

The endpoints and request/response examples below are reconstructed from the app's interface — illustrative, not a live capture.

Send Rayah login OTP
POST /v1/electricity/auth/otp osint
Sends a Rayah one-time code to the mobile registered on the national ID or iqama so the next call can mint a session.
Auth: None. National ID or iqama plus mobile number identify the holder; the SMS OTP is consumed by POST /v1/electricity/auth/session.
- nationalId
- IdNumber
- IdType
- iqamaNumber
- mobileNumber
- lang
- status
- message
```
POST /v1/electricity/auth/otp HTTP/1.1
Content-Type: application/json

{
  "nationalId": "1087654321",
  "IdNumber": "1087654321",
  "IdType": "NATIONAL_ID",
  "iqamaNumber": null,
  "mobileNumber": "966501234567",
  "lang": "en"
}
```
```
{
  "status": "OK",
  "mobileNumber": "966501234567",
  "IdNumber": "1087654321",
  "IdType": "NATIONAL_ID",
  "message": "OTP sent"
}
```
Validate Rayah login OTP
POST /v1/electricity/auth/session osint
Exchanges a national ID or iqama and Rayah OTP for the SAP partner and contract-account keys (PartnerNo, Vkont, accountID) used on every subsequent call.
Auth: None on this call. National ID or iqama plus the SMS OTP from POST /v1/electricity/auth/otp mint the session cookie used on later calls.
- nationalId
- IdNumber
- IdType
- OTP
- mobileNumber
- lang
- status
- PartnerNo
- partnerNo
- accountID
- accountId
- Vkont
- iqamaNumber
```
POST /v1/electricity/auth/session HTTP/1.1
Content-Type: application/json

{
  "nationalId": "1087654321",
  "IdNumber": "1087654321",
  "IdType": "NATIONAL_ID",
  "OTP": "482193",
  "mobileNumber": "966501234567",
  "lang": "en"
}
```
```
{
  "status": "OK",
  "PartnerNo": "0011592481",
  "partnerNo": "0011592481",
  "accountID": "100006470226",
  "accountId": "100006470226",
  "Vkont": "100006470226",
  "mobileNumber": "966501234567",
  "iqamaNumber": null
}
```

Fetch account holder details

GET /v1/electricity/account/profile osint

Returns the signed-in business-partner profile: contract account, display name, national ID or iqama, mobile, email and VAT number shown on the account screen.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

accountID
PartnerNo
Vkont
contractAccount
contractAccountFullName
nationalId
iqamaNumber
mobileNumber
emailAddress
vatNumber

GET /v1/electricity/account/profile?accountID=100006470226 HTTP/1.1
Cookie: se-session=…

{
  "accountID": "100006470226",
  "PartnerNo": "0011592481",
  "Vkont": "100006470226",
  "contractAccount": "31001234567",
  "contractAccountFullName": "AHMED ALQAHTANI",
  "nationalId": "1087654321",
  "iqamaNumber": null,
  "mobileNumber": "966501234567",
  "emailAddress": "[email protected]",
  "vatNumber": "300123456700003"
}

Dashboard contract-account list

GET /v1/electricity/accounts opendata

Lists every contract account on the signed-in partner with alias, prepaid flag and due amount for the home switcher.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

PartnerNo
contractAccount
Vkont
alias
isPrePay
totalDueAmount

GET /v1/electricity/accounts?PartnerNo=0011592481 HTTP/1.1
Cookie: se-session=…

{
  "PartnerNo": "0011592481",
  "accounts": [
    {
      "contractAccount": "31001234567",
      "Vkont": "100006470226",
      "alias": "Home - Riyadh",
      "isPrePay": false,
      "totalDueAmount": 412.75
    },
    {
      "contractAccount": "31009876543",
      "Vkont": "10009876543",
      "alias": "Shop - Jeddah",
      "isPrePay": true,
      "totalDueAmount": 0
    }
  ]
}

Business-partner total due
GET /v1/electricity/billing/due openfinance
Reads the SAP business-partner total due in SAR for the signed-in contract account, the figure on the home balance tile.
Auth: Signed-in session cookie from POST /v1/electricity/auth/session.
- PartnerNo
- Vkont
- totalDueAmount
- dueAmount
- currency
- dueDate
- contractAccount
```
GET /v1/electricity/billing/due?PartnerNo=0011592481&Vkont=100006470226 HTTP/1.1
Cookie: se-session=…
```
```
{
  "PartnerNo": "0011592481",
  "Vkont": "100006470226",
  "totalDueAmount": 412.75,
  "dueAmount": 412.75,
  "currency": "SAR",
  "dueDate": "2026-10-18",
  "contractAccount": "31001234567"
}
```

Dashboard bills result set

GET /v1/electricity/billing/bills openfinance

Pages the dashboard bill list for a contract account with billed amount, last payment date, next bill date and prepaid flag.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

Vkont
contractAccount
BilledAmount
dueDate
LastPaymentDate
isPrePay
NextBillDate

GET /v1/electricity/billing/bills?Vkont=100006470226 HTTP/1.1
Cookie: se-session=…

{
  "Vkont": "100006470226",
  "contractAccount": "31001234567",
  "bills": [
    {
      "BilledAmount": 387.40,
      "dueDate": "2026-09-18",
      "LastPaymentDate": "2026-09-10",
      "isPrePay": false,
      "NextBillDate": "2026-10-01"
    },
    {
      "BilledAmount": 412.75,
      "dueDate": "2026-10-18",
      "LastPaymentDate": null,
      "isPrePay": false,
      "NextBillDate": "2026-11-01"
    }
  ]
}

Bill history consumption

GET /v1/electricity/usage/history opendata

Returns monthly kWh consumption with current and previous meter readings behind the bill-history chart.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

contractAccount
meterNumber
MeterSerialNumber
consumption
currentMeterRead
previousMeterRead
BilledAmount
NumberOfDays

GET /v1/electricity/usage/history?contractAccount=31001234567&meterNumber=052184736 HTTP/1.1
Cookie: se-session=…

{
  "contractAccount": "31001234567",
  "meterNumber": "052184736",
  "MeterSerialNumber": "052184736",
  "months": [
    {
      "consumption": 1840,
      "currentMeterRead": 91240,
      "previousMeterRead": 89400,
      "BilledAmount": 387.40,
      "NumberOfDays": 30
    },
    {
      "consumption": 1965,
      "currentMeterRead": 93205,
      "previousMeterRead": 91240,
      "BilledAmount": 412.75,
      "NumberOfDays": 31
    }
  ]
}

Consumption tariff slabs

GET /v1/electricity/usage/tariff-bands opendata

Breaks a billing period into SEC tariff slabs with kWh in each band and the halalah-per-kWh rate used on the bill.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

contractAccount
tariff
efficientConsumption
kwh
halalah
consumption
BilledAmount

GET /v1/electricity/usage/tariff-bands?contractAccount=31001234567 HTTP/1.1
Cookie: se-session=…

{
  "contractAccount": "31001234567",
  "tariff": "RESIDENTIAL",
  "efficientConsumption": true,
  "slabs": [
    {"kwh": 1965, "halalah": 18, "consumption": 1965, "BilledAmount": 353.70},
    {"kwh": 0, "halalah": 30, "consumption": 0, "BilledAmount": 0}
  ]
}

Hasibati bill estimate
GET /v1/electricity/usage/bill-estimate opendata
Projects the next bill from a typed current meter reading on the Hasibati estimator, including kWh used and an efficiency flag.
Auth: Signed-in session cookie from POST /v1/electricity/auth/session. A guest variant keyed on the contract-account number works without login.
- contractAccountID
- contractAccount
- contractAccountFullName
- meterNumber
- currentMtrRead
- previousMeterRead
- ForecastBillAmount
- consumption
- efficientConsumption
- currency
```
GET /v1/electricity/usage/bill-estimate?contractAccountID=31001234567 HTTP/1.1
Cookie: se-session=…
```
```
{
  "contractAccountID": "31001234567",
  "contractAccount": "31001234567",
  "contractAccountFullName": "AHMED ALQAHTANI",
  "meterNumber": "052184736",
  "currentMtrRead": 93205,
  "previousMeterRead": 91240,
  "ForecastBillAmount": 428.10,
  "consumption": 2040,
  "efficientConsumption": false,
  "currency": "SAR"
}
```
PayFort payment URL
GET /v1/electricity/payments/checkout-link openfinance
Mints a PayFort hosted-checkout URL, fortId and request hash so the customer can pay the due amount by card.
Auth: Signed-in session cookie from POST /v1/electricity/auth/session. Guest checkout uses /v1/electricity/guest/checkout-link?token=.
- token
- PaymentURL
- fortId
- hash
- merchant_identifier
- access_code
- refNumber
- isPrePay
- lang
```
GET /v1/electricity/payments/checkout-link?token=se-sess-7f3a1c HTTP/1.1
Cookie: se-session=…
```
```
{
  "PaymentURL": "https://payments.example.com/hosted-checkout",
  "fortId": "169000000012345678",
  "hash": "a3f1c9e0b21d7a55",
  "merchant_identifier": "UTILITYMERCH",
  "access_code": "<access-code>",
  "refNumber": "SE-41275-100006470226",
  "isPrePay": false,
  "lang": "en"
}
```

Prepaid account snapshot

GET /v1/electricity/prepaid/snapshot openfinance

Returns remaining prepaid credit, last recharge and kWh used for a prepaid meter account.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

contractAccount
isPrePay
meterNumber
PrepaidBalance
currency
RechargeAmount
LastRechargeDate
consumption

GET /v1/electricity/prepaid/snapshot?contractAccount=31009876543&isPrePay=true HTTP/1.1
Cookie: se-session=…

{
  "contractAccount": "31009876543",
  "isPrePay": true,
  "meterNumber": "088441122",
  "PrepaidBalance": 86.50,
  "currency": "SAR",
  "RechargeAmount": 100.00,
  "LastRechargeDate": "2026-09-28",
  "consumption": 412
}

Create outage report

POST /v1/electricity/outages opendata

Opens an outage ticket for a contract account and returns ticketNumber so the holder can track restoration.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session. Guest filing uses POST /v1/electricity/guest/outages.

partnerNo
Vkont
meterNumber
fromNotification
message
lang
ticketNumber
refNumber
status

POST /v1/electricity/outages HTTP/1.1
Cookie: se-session=…
Content-Type: application/json

{
  "partnerNo": "0011592481",
  "Vkont": "100006470226",
  "meterNumber": "052184736",
  "fromNotification": false,
  "message": "No supply since 21:10",
  "lang": "en"
}

{
  "ticketNumber": "OUT-2026-441902",
  "refNumber": "SR-889120",
  "status": "OPEN",
  "partnerNo": "0011592481",
  "Vkont": "100006470226"
}

Tawasul ticket status

GET /v1/electricity/support/ticket-status opendata

Reads a Tawasul CRM ticket's category and status for the signed-in contract account.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

ticketNumber
requestType
ReqCat
status
PartnerNo
refNumber

GET /v1/electricity/support/ticket-status?ticketNumber=TW-2026-11820 HTTP/1.1
Cookie: se-session=…

{
  "ticketNumber": "TW-2026-11820",
  "requestType": "BILLING_INQUIRY",
  "ReqCat": "BILLING",
  "status": "IN_PROGRESS",
  "PartnerNo": "0011592481",
  "refNumber": "SR-774310"
}

Submit complaint

POST /v1/electricity/support/complaints opendata

Files a billing or service complaint and returns the ticket number shown on the complaints screen.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

contractAccount
Vkont
message
lang
ticketNumber
refNumber
status

POST /v1/electricity/support/complaints HTTP/1.1
Cookie: se-session=…
Content-Type: application/json

{
  "contractAccount": "31001234567",
  "Vkont": "100006470226",
  "message": "High bill vs prior month",
  "lang": "en"
}

{
  "ticketNumber": "CMP-2026-22011",
  "refNumber": "SR-22011",
  "status": "OPEN",
  "contractAccount": "31001234567"
}

Smart-meter consumption header
GET /v1/electricity/meters/summary opendata
Returns the smart-meter header used by the consumption-analysis screen: latest reading, next read date and breaker capacity.
Auth: Signed-in session cookie from POST /v1/electricity/auth/session.
- Vkont
- meterNumber
- MeterSerialNumber
- currentMeterRead
- NextMeterReadDate
- consumption
- BillBreakerCapacity
```
GET /v1/electricity/meters/summary?Vkont=100006470226 HTTP/1.1
Cookie: se-session=…
```
```
{
  "Vkont": "100006470226",
  "meterNumber": "052184736",
  "MeterSerialNumber": "052184736",
  "currentMeterRead": 93205,
  "NextMeterReadDate": "2026-10-31",
  "consumption": 1965,
  "BillBreakerCapacity": 60
}
```
Demand-load forecast bill
GET /v1/electricity/demand-load/forecast opendata
Forecasts the bill impact of a requested extra demand load on the contract account.
Auth: Signed-in session cookie from POST /v1/electricity/auth/session.
- contractAccount
- ConsumptionLoad
- DemandLoad
- ForecastBillAmount
- tariff
- currency
```
GET /v1/electricity/demand-load/forecast?contractAccount=31001234567 HTTP/1.1
Cookie: se-session=…
```
```
{
  "contractAccount": "31001234567",
  "ConsumptionLoad": 9,
  "DemandLoad": 15,
  "ForecastBillAmount": 640.20,
  "tariff": "RESIDENTIAL",
  "currency": "SAR"
}
```
Welfare refund
GET /v1/electricity/billing/welfare-refund openfinance
Checks welfare-refund eligibility and the IBAN that would receive the credit.
Auth: Signed-in session cookie from POST /v1/electricity/auth/session.
- partnerNo
- eligible
- iBAN
- status
- currency
```
GET /v1/electricity/billing/welfare-refund?partnerNo=0011592481 HTTP/1.1
Cookie: se-session=…
```
```
{
  "partnerNo": "0011592481",
  "eligible": true,
  "iBAN": "SA0380000000608010167519",
  "status": "AVAILABLE",
  "currency": "SAR"
}
```

Contract-account meters

GET /v1/electricity/accounts/meters opendata

Lists meters on a contract account with serial, latest reading, prepaid flag and breaker capacity.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

Vkont
contractAccount
meterNumber
MeterSerialNumber
currentMeterRead
currentMtrRead
isPrePay
BillBreakerCapacity

GET /v1/electricity/accounts/meters?Vkont=100006470226 HTTP/1.1
Cookie: se-session=…

{
  "Vkont": "100006470226",
  "contractAccount": "31001234567",
  "meters": [
    {
      "meterNumber": "052184736",
      "MeterSerialNumber": "052184736",
      "currentMeterRead": 93205,
      "currentMtrRead": 93205,
      "isPrePay": false,
      "BillBreakerCapacity": 60
    }
  ]
}

Guest contract-account lookup
GET /v1/electricity/guest/bill-lookup openfinance
Looks up due amount and account display name for guest bill-pay, without a Rayah session.
Auth: None. Contract-account number is the only identifier; guest card checkout follows on /v1/electricity/guest/checkout-link.
- contractAccount
- contractAccountFullName
- totalDueAmount
- dueAmount
- dueDate
- isPrePay
- currency
```
GET /v1/electricity/guest/bill-lookup?contractAccount=31001234567 HTTP/1.1
```
```
{
  "contractAccount": "31001234567",
  "contractAccountFullName": "AHMED ALQAHTANI",
  "totalDueAmount": 412.75,
  "dueAmount": 412.75,
  "dueDate": "2026-10-18",
  "isPrePay": false,
  "currency": "SAR"
}
```

Print bill PDF

GET /v1/electricity/billing/document opendata

Returns the printable bill PDF for a payment-plan / invoice id shown on the bill-details screen.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

PaymentPlanID
contractAccount
BilledAmount
contentUrl
MeterSerialNumber

GET /v1/electricity/billing/document?PaymentPlanID=PP-31001234567-202610 HTTP/1.1
Cookie: se-session=…

{
  "PaymentPlanID": "PP-31001234567-202610",
  "contractAccount": "31001234567",
  "BilledAmount": 412.75,
  "contentUrl": "https://cdn.example.com/bills/PP-31001234567-202610.pdf",
  "MeterSerialNumber": "052184736"
}

Prepaid recharge history

GET /v1/electricity/prepaid/recharges openfinance

Lists prepaid-meter top-up invoices with amount, date, remaining credit and a ref number for each recharge.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

contractAccount
isPrePay
RechargeAmount
LastRechargeDate
PrepaidBalance
currency
refNumber

GET /v1/electricity/prepaid/recharges?contractAccount=31009876543 HTTP/1.1
Cookie: se-session=…

{
  "contractAccount": "31009876543",
  "isPrePay": true,
  "invoices": [
    {
      "RechargeAmount": 100.00,
      "LastRechargeDate": "2026-09-28",
      "PrepaidBalance": 86.50,
      "currency": "SAR",
      "refNumber": "PR-889120"
    },
    {
      "RechargeAmount": 50.00,
      "LastRechargeDate": "2026-08-14",
      "PrepaidBalance": 12.10,
      "currency": "SAR",
      "refNumber": "PR-774310"
    }
  ]
}

Bill payment history

GET /v1/electricity/billing/payments openfinance

Pages settled postpaid payments for a contract account with billed amount, payment date and payment-plan id.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

contractAccount
Vkont
BilledAmount
LastPaymentDate
PaymentPlanID
currency
refNumber

GET /v1/electricity/billing/payments?contractAccount=31001234567 HTTP/1.1
Cookie: se-session=…

{
  "contractAccount": "31001234567",
  "Vkont": "100006470226",
  "payments": [
    {
      "BilledAmount": 387.40,
      "LastPaymentDate": "2026-09-10",
      "PaymentPlanID": "PP-31001234567-202609",
      "currency": "SAR",
      "refNumber": "SADAD-441902"
    }
  ]
}

Demand-load eligibility
GET /v1/electricity/demand-load/eligibility opendata
Tells whether the contract account can request extra demand load, with current consumption load and breaker capacity.
Auth: Signed-in session cookie from POST /v1/electricity/auth/session.
- contractAccount
- Vkont
- DemandLoad
- ConsumptionLoad
- eligible
- BillBreakerCapacity
```
GET /v1/electricity/demand-load/eligibility?contractAccount=31001234567 HTTP/1.1
Cookie: se-session=…
```
```
{
  "contractAccount": "31001234567",
  "Vkont": "100006470226",
  "DemandLoad": 15,
  "ConsumptionLoad": 9,
  "eligible": true,
  "BillBreakerCapacity": 60
}
```
Request tracking by mobile
GET /v1/electricity/support/requests opendata
Lists Tawasul / service requests tied to a mobile number so the holder can track tickets without a contract-account picker.
Auth: Signed-in session cookie from POST /v1/electricity/auth/session. Guest tracking by mobile number uses /v1/electricity/guest/requests?mobileNumber=.
- mobileNumber
- ticketNumber
- requestNumber
- refNumber
- ReqCat
- status
```
GET /v1/electricity/support/requests?mobileNumber=966501234567 HTTP/1.1
Cookie: se-session=…
```
```
{
  "mobileNumber": "966501234567",
  "requests": [
    {
      "ticketNumber": "TW-2026-11820",
      "requestNumber": "SR-774310",
      "refNumber": "SR-774310",
      "ReqCat": "BILLING",
      "status": "IN_PROGRESS"
    }
  ]
}
```
Qitaf redeem quote
GET /v1/electricity/loyalty/redemption-quote openfinance
Quotes how many STC Qitaf points the signed-in partner can redeem against the current electricity due, with the SAR equivalent.
Auth: Signed-in session cookie from POST /v1/electricity/auth/session.
- PartnerId
- Vkont
- QitafReedemPoint
- qitafAmountPaidFromQitaf
- QitafReferenceNo
- currency
```
GET /v1/electricity/loyalty/redemption-quote?PartnerId=0011592481&Vkont=100006470226 HTTP/1.1
Cookie: se-session=…
```
```
{
  "PartnerId": "0011592481",
  "Vkont": "100006470226",
  "QitafReedemPoint": 4200,
  "qitafAmountPaidFromQitaf": 42.00,
  "QitafReferenceNo": "QT-889120",
  "currency": "SAR"
}
```

PayFort Apple Pay charge

POST /v1/electricity/payments/wallet-charge openfinance

Submits an Apple Pay token to PayFort so the due amount (or prepaid recharge) is charged without a hosted card page.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session. Guest Apple Pay uses /v1/electricity/guest/wallet-charge.

applePayToken
paymentData
Vkont
isPrePay
lang
fortId
refNumber
status
hash

POST /v1/electricity/payments/wallet-charge HTTP/1.1
Cookie: se-session=…
Content-Type: application/json

{
  "applePayToken": "tok_apple_7f3a1c",
  "paymentData": "eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoiLi4uIn0=",
  "Vkont": "100006470226",
  "isPrePay": false,
  "lang": "en"
}

{
  "fortId": "169000000012345678",
  "refNumber": "SE-41275-100006470226",
  "status": "SUCCESS",
  "hash": "a3f1c9e0b21d7a55",
  "isPrePay": false
}

Pending property declaration
GET /v1/electricity/property/declarations/pending opendata
Lists a pending property / meter declaration on the partner so the holder can finish SPL national-address confirmation.
Auth: Signed-in session cookie from POST /v1/electricity/auth/session.
- PartnerId
- PartnerNo
- nationalAddress
- status
- contractAccount
```
GET /v1/electricity/property/declarations/pending?PartnerId=0011592481 HTTP/1.1
Cookie: se-session=…
```
```
{
  "PartnerId": "0011592481",
  "PartnerNo": "0011592481",
  "nationalAddress": "RRRD7856",
  "status": "PENDING",
  "contractAccount": "31001234567"
}
```

Saved PayFort cards

GET /v1/electricity/payments/saved-cards openfinance

Lists PayFort-tokenised cards on the contract account so the pay-bill screen can reuse a default card without re-entering PAN.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

accountId
cardToken
CardNumber
CardExpiry
expiryDate
defaultCard
isDefault

GET /v1/electricity/payments/saved-cards?accountId=100006470226 HTTP/1.1
Cookie: se-session=…

{
  "accountId": "100006470226",
  "cards": [
    {
      "cardToken": "tok_pf_441902",
      "CardNumber": "****4242",
      "CardExpiry": "09/28",
      "expiryDate": "2028-09",
      "defaultCard": true,
      "isDefault": true
    }
  ]
}

Away-mode period details
GET /v1/electricity/away-mode/details opendata
Returns the signed-in contract account's away-mode window: freeze dates, notification frequency and whether kWh surged while the property was vacant.
Auth: Signed-in session cookie from POST /v1/electricity/auth/session.
- awayModeID
- AwayModeID
- Vkont
- contractAccount
- AwayModeNotificationFrequency
- awayModeFreezedDates
- IsConsumptionHigherWhileAway
- HighestSurgeDuringAwayMode
- PreviousPeriodConsumption
```
GET /v1/electricity/away-mode/details?Vkont=100006470226 HTTP/1.1
Cookie: se-session=…
```
```
{
  "awayModeID": "AM-2026-11820",
  "AwayModeID": "AM-2026-11820",
  "Vkont": "100006470226",
  "contractAccount": "31001234567",
  "AwayModeNotificationFrequency": "WEEKLY",
  "awayModeFreezedDates": ["2026-08-01", "2026-08-31"],
  "IsConsumptionHigherWhileAway": false,
  "HighestSurgeDuringAwayMode": 2.4,
  "PreviousPeriodConsumption": 1840
}
```

Bill installment plan

GET /v1/electricity/billing/installment-plan openfinance

Reads the in-force electricity bill installment plan: remaining due, VAT and the payment-plan id used on the installment tile.

Auth: Signed-in session cookie from POST /v1/electricity/auth/session.

contractAccount
Vkont
InstallmentPlanInforce
InvoiceDate
InvoiceType
TotalInstallmentAmount
TotalDueAmount
VATAmount
TotalAmountBeforeTax
PaymentPlanID

GET /v1/electricity/billing/installment-plan?contractAccount=31001234567 HTTP/1.1
Cookie: se-session=…

{
  "contractAccount": "31001234567",
  "Vkont": "100006470226",
  "InstallmentPlanInforce": true,
  "InvoiceDate": "2026-09-18",
  "InvoiceType": "INSTALLMENT",
  "TotalInstallmentAmount": 1238.25,
  "TotalDueAmount": 412.75,
  "VATAmount": 53.66,
  "TotalAmountBeforeTax": 1184.59,
  "PaymentPlanID": "PP-31001234567-202610"
}

Current meter-read billing contract
GET /v1/electricity/meter-read/contract opendata
Returns the billing contract and latest / previous meter readings used by the current-meter-read screen.
Auth: Signed-in session cookie from POST /v1/electricity/auth/session.
- billingContract
- Vkont
- contractAccount
- meterNumber
- currentMeterRead
- previousMeterRead
- PreviousReadingDate
- consumption
```
GET /v1/electricity/meter-read/contract?Vkont=100006470226 HTTP/1.1
Cookie: se-session=…
```
```
{
  "billingContract": "31001234567",
  "Vkont": "100006470226",
  "contractAccount": "31001234567",
  "meterNumber": "052184736",
  "currentMeterRead": 93205,
  "previousMeterRead": 91240,
  "PreviousReadingDate": "2026-09-01",
  "consumption": 1965
}
```
Account overview set
GET /v1/electricity/accounts/overview opendata
Loads the SAP account-overview snapshot for the signed-in partner: prepaid flag, due amount and meter on the selected Vkont.
Auth: Signed-in session cookie from POST /v1/electricity/auth/session.
- PartnerNo
- Vkont
- contractAccount
- isPrePay
- totalDueAmount
- meterNumber
- currency
```
GET /v1/electricity/accounts/overview?PartnerNo=0011592481&Vkont=100006470226 HTTP/1.1
Cookie: se-session=…
```
```
{
  "PartnerNo": "0011592481",
  "Vkont": "100006470226",
  "contractAccount": "31001234567",
  "isPrePay": false,
  "totalDueAmount": 412.75,
  "meterNumber": "052184736",
  "currency": "SAR"
}
```

Where teams use this data

Bill-desk SAR reconciliation
An ERP or collection bot pulls GetBPTotalDueAmount and GetDashboardBillsResultSet nightly, matching totalDueAmount, BilledAmount and LastPaymentDate in SAR against SADAD and bank receipts per Vkont.
Outage, Tawasul and complaints feed
A NOC dashboard subscribes to CreateOutage ticketNumber rows and TawasulTicketStatusSet / SubmitComplaintRequest status so field crews see open outages and billing inquiries on the same PartnerNo.
kWh slab and Hasibati estimator
An efficiency tool reads GetBillHistoryConsumptionData and GetConsumptionSlabSetData, then calls GetBillEstimateSet with currentMtrRead to show households how a mid-cycle reading would land on ForecastBillAmount.
Prepaid top-up and PayFort checkout
A wallet or family-pay app uses PrepaidAccountSet PrepaidBalance plus GetPayFortPaymentURL fortId/hash (or the guest contract-account lookup) to recharge a meter or settle a postpaid dueAmount without storing card data.

Frequently asked questions

How does Saudi Energy authenticate account holders?

Rayah OTP after national ID or iqama: POST /v1/electricity/auth/otp then POST /v1/electricity/auth/session. The response PartnerNo, Vkont and accountID plus the session cookie gate later calls. Guest bill-pay skips login and keys only on contractAccount via /v1/electricity/guest/bill-lookup.

Which fields carry the electricity bill due?

GET /v1/electricity/billing/due returns totalDueAmount / dueAmount in SAR for a PartnerNo + Vkont pair. The bills list at /v1/electricity/billing/bills carries per-period BilledAmount, LastPaymentDate and NextBillDate, with isPrePay marking prepaid meters.

Can I read consumption and outage tickets, not just balances?

Yes. /v1/electricity/usage/history returns monthly consumption with currentMeterRead / previousMeterRead, /v1/electricity/usage/tariff-bands splits tariff slabs in halalah per kWh, the Hasibati estimate at /v1/electricity/usage/bill-estimate projects ForecastBillAmount from currentMtrRead, and POST /v1/electricity/outages plus /v1/electricity/support/ticket-status expose ticketNumber.

How are card payments initiated?

GET /v1/electricity/payments/checkout-link mints a PayFort hosted-checkout URL with fortId, hash, merchant_identifier and access_code. Apple Pay posts to /v1/electricity/payments/wallet-charge; guests call /v1/electricity/guest/checkout-link after the contract-account lookup.

Apps similar to Saudi Energy

National Water — The National Water app from National Water Company is Saudi Arabia's water-utility self-care client, used for more than 30 account services alongside electricity bills.
eMarafiq — eMarafiq is Marafiq's e-services app for its utility accounts, used to track consumption and bills and to view notifications from the utility.
Absher — Absher is the Ministry of Interior's official individuals e-services app for citizens, residents and visitors in Saudi Arabia, and Google Play lists it among apps similar to Saudi Energy.
Nafath — Nafath is the national digital-identity app that verifies a user's identity and lets them accept login requests from government and private services in the Kingdom.
DEWA — DEWA Smart App is Dubai Electricity and Water Authority's customer app for electricity and water accounts in Dubai, including usage and bill payment.
SEWA — The SEWA app is Sharjah Electricity, Water and Gas Authority's utility client for account management, usage graphs and bill payments, with UAE Pass and Face ID login.
PLN Mobile — PLN Mobile is PLN's electricity self-care app in Indonesia for buying prepaid tokens, paying bills, filing complaints and requesting a new connection or extra load.
Enel São Paulo — Enel São Paulo is ENEL BRASIL's customer app for the São Paulo distribution concession, covering bill copies, payment, outage reports, reconnection and self meter reading.

More Utilities apps

Topics

Saudi Energy API
Saudi Electricity Company
SEC bill API
contract account Vkont
Hasibati bill estimate
Tawasul ticket
PayFort electricity payment
Saudi prepaid meter

Need this app's data API integrated?

We deliver scoped integrations for any named app — from USD 500 with source-code handoff, or hosted access billed per call. Tell us the data you need.

NDA + SOW on every engagement
Delivery in 3–7 days
Payment only after acceptance
Work scoped to authorized use

Get a quote

Saudi Energy data API: bills, kWh and outages

Screenshots

API surface

Send Rayah login OTP

Validate Rayah login OTP

Fetch account holder details

Dashboard contract-account list

Business-partner total due

Dashboard bills result set

Bill history consumption

Consumption tariff slabs

Hasibati bill estimate

PayFort payment URL

Prepaid account snapshot

Create outage report

Tawasul ticket status

Submit complaint

Smart-meter consumption header

Demand-load forecast bill

Welfare refund

Contract-account meters

Guest contract-account lookup

Print bill PDF

Prepaid recharge history

Bill payment history

Demand-load eligibility

Request tracking by mobile

Qitaf redeem quote

PayFort Apple Pay charge

Pending property declaration

Saved PayFort cards

Away-mode period details

Bill installment plan

Current meter-read billing contract

Account overview set

Data categories

Where teams use this data

Bill-desk SAR reconciliation

Outage, Tawasul and complaints feed

kWh slab and Hasibati estimator

Prepaid top-up and PayFort checkout

Frequently asked questions

Related apps

Apps similar to Saudi Energy

More Utilities apps

Adobe Scan AI PDF Scanner, OCR

All Languages Translator

Call Blocker - Blacklist

Enel São Paulo

Topics

Need this app's data API integrated?