canonical: https://jentic.com/apis/api.dewa.gov.ae/dewa

# DEWA Bank and Agencies API

Jentic publishes the only available OpenAPI specification for DEWA Bank and Agencies API, keeping it validated and agent-ready. The DEWA Bank and Agencies API lets banks and collection agencies integrated with Dubai Electricity and Water Authority retrieve outstanding utility-bill information for their customers. Two read-only endpoints expose the same data - one keyed on the DEWA contract account number, one on the bill reference number - and both return the outstanding amount, due date, and bill reference details so the calling system can present a payable bill. This is the integration surface partner banks and government agencies use to power 'pay your DEWA bill' flows inside their own apps.

## For AI agents

Look up outstanding DEWA utility-bill amounts by contract account or bill reference number for partner bank and agency integrations.

## Scope

Does not handle bill payment, account opening, meter readings, or service connections - use for outstanding-bill enquiries by contract account or reference number only.

## Capabilities

- Fetch outstanding bill details by DEWA contract account number via `/bill/enquiry/contractaccount`
- Fetch outstanding bill details by reference number via `/bill/enquiry/referencenumber`
- Surface bill amount, currency, and due date for partner-bank pay-bill flows
- Validate that a contract account or reference number is currently billable
- Power 'pay DEWA bill' integrations inside bank mobile apps and collection-agency portals

## Use cases

### Pay-Your-DEWA-Bill in a Bank App

Partner banks expose a 'pay DEWA' tile in their mobile app so customers can settle utility bills without leaving the bank. The flow calls `/bill/enquiry/contractaccount` with the customer's DEWA contract number, displays the outstanding amount and due date, and then routes the payment through the bank's existing rails. Two endpoints, no authentication, sub-second response times.

Example prompt: Call GET `/bill/enquiry/contractaccount` with the customer's contract account number, display the outstanding amount and due date, and confirm with the user before initiating payment

### Collection-Agency Bill Verification

Authorised collection agencies verify outstanding DEWA bills before pursuing a customer for payment. `/bill/enquiry/referencenumber` accepts the bill reference, returns the current outstanding amount, and confirms the bill has not been paid since the agency last polled. This avoids the embarrassment of chasing a bill that is already settled.

Example prompt: Call GET `/bill/enquiry/referencenumber` with reference 1234567890, confirm the bill is still outstanding, and update the agency's collection record

### Customer-Service Bill Lookup

Customer-service reps at partner banks pull up a customer's DEWA bill while on the phone so they can answer 'how much do I owe?' without bouncing the call to DEWA. Both endpoints respond with the outstanding amount and due date. The two-endpoint design covers both common identifiers customers carry: the long-lived contract account number printed on the meter, and the per-bill reference number on the most recent invoice.

Example prompt: Look up the outstanding bill for contract account 200012345 via GET `/bill/enquiry/contractaccount` and read the amount due to the customer

### AI Agent Bill Concierge

An AI agent embedded in a bank's chat experience uses DEWA via Jentic to answer 'what's my electricity bill?' without holding any DEWA-specific configuration. The agent searches Jentic by intent, loads the schema, and executes the lookup using the contract account the user supplies. Because the API is unauthenticated, the agent can begin returning bill data without any credential management.

Example prompt: Search Jentic for 'look up DEWA outstanding bill', load the contract-account schema, and report the amount due for the user's contract number

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/bill/enquiry/contractaccount` | Outstanding bill enquiry by contract account number |
| GET | `/bill/enquiry/referencenumber` | Outstanding bill enquiry by bill reference number |

## Key resources

- **Outstanding** — Outstanding DEWA bill enquiries by contract account or bill reference number

## Why Jentic

- **Setup:** Wiring the DEWA Bank and Agencies API by hand means targeting the v1 host, since the endpoints declare no authentication header, and mapping the two bill-enquiry routes with their query parameters yourself. Through Jentic you install once, import DEWA from the API Directory, store any required credential once, and your agent calls it.
- **Permission scoping:** DEWA selects a bill through query parameters rather than a resource id in the URL path, so you limit the agent to the operations it needs, such as enquiring by contract account. Enquiry by reference number is a separate operation that is only available if you include it in the allowed set.
- **Credential handling:** Any DEWA credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'look up a DEWA outstanding bill', and Jentic returns the matching enquiry operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Qonto API** — Qonto is a banking API that pairs with utility-bill lookups when partner banks build pay-bill flows.
- **Xero Accounting API** — Xero accounting can ingest utility-bill amounts as expense entries once they are settled.
- **Sage API** — Sage is an enterprise accounting platform that businesses use to log utility expenses.

## FAQ

### Why is there no official OpenAPI spec for DEWA Bank and Agencies API?

DEWA does not publish an OpenAPI specification on its developer portal. Jentic generates and maintains this spec so that AI agents and developers can call DEWA Bank and Agencies API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the DEWA Bank and Agencies API use?

The Bank and Agencies surface declared in this OpenAPI spec does not include a security scheme - the two enquiry endpoints are accessed over the DEWA partner network without an explicit Authorization header. In production, partner banks and agencies are typically allow-listed at the network level by DEWA. Confirm any onboarding requirements with DEWA before going live.

### Can I look up a DEWA bill by reference number?

Yes - GET `/bill/enquiry/referencenumber` accepts the bill reference number printed on the most recent DEWA invoice and returns the outstanding amount and due date. Use it when the customer has the bill in hand. For long-lived lookups keyed on the meter contract, use `/bill/enquiry/contractaccount` instead.

### What are the rate limits for the DEWA Bank and Agencies API?

Public DEWA documentation does not publish per-partner rate limits. The endpoints are intended for transactional pay-bill flows, not bulk data extraction - call them on demand inside a customer-driven payment journey rather than scraping all contracts. If you receive a throttled response, back off and retry with exponential delay.

### How do I look up a DEWA bill in a banking workflow through Jentic?

Run `pip install jentic`, search for 'look up DEWA outstanding bill', load the GET `/bill/enquiry/contractaccount` schema, and execute with the customer's contract account number. The response carries the outstanding amount and due date which the bank app can render and pass to its payment rail.

### Does this API let me actually pay a DEWA bill?

No. The two endpoints are read-only enquiries - they tell you what is outstanding, not how to settle it. Payment is executed through the partner bank or agency's own rails, with the DEWA-issued reference number used to mark the bill paid. Pair this enquiry with your bank's payment API to complete the transaction.

### Can I limit what my agent is allowed to do with the DEWA Bank and Agencies API?

Yes. Because you run Jentic One yourself, your own rules decide which of this API's operations and credentials your agent may use. The DEWA API selects a bill through query parameters rather than a resource id in the path, so you can allow only the operation the agent needs, such as enquiring by contract account via GET `/bill/enquiry/contractaccount.` Enquiry by reference number through GET `/bill/enquiry/referencenumber` is a separate operation that the agent can call only if you add it to the allowed set.