EFD Invoice Query API

Authentication

Every request must include an X-Api-Key header. The key identifies which client's invoices are queried — no TIN is needed in the request body. Requests with a missing or revoked key are rejected with HTTP 401.

Required Headers

X-Api-Key: <your-client-api-key>

Content-Type: application/json

Keep your API key confidential. Each key is bound to your account.

Base URLs

Environment	Base URL	Notes
Production	`https://portal.cypressrealitylabs.com`	Live URA EFRIS data

Endpoint

POST /api/efris/invoice-list-query

Queries URA for EFD invoices belonging to the client identified by the X-Api-Key header. Send filters as a JSON object in the request body with Content-Type: application/json. Results are always filtered to dataSource=101 (EFD devices only). Supports date range, buyer TIN, invoice number, type, and kind filters with server-side pagination.

Request Body

Send a JSON object with Content-Type: application/json. All fields are optional — the client is identified by the API key, not a TIN in the body. Omit or set to null any filter you don't need. An empty body {} is valid and returns all invoices for the key's client.

Parameter	Type		Description
startDate	string	Optional	Filter invoices issued on or after this date. Format: `YYYY-MM-DD`. Example: `2024-01-01`.
endDate	string	Optional	Filter invoices issued on or before this date. Format: `YYYY-MM-DD`. Example: `2024-12-31`. Date range must not exceed one year.
invoiceNo	string	Optional	Filter by exact invoice number.
buyerTin	string	Optional	Filter by buyer TIN.
invoiceType	string	Optional	Filter by invoice type. Values: `1` = Normal invoice, `2` = Credit note, `3` = Debit note.
invoiceKind	string	Optional	Filter by invoice kind. Values: `1` = Local sale, `2` = Export.
pageNo	integer	Optional	Page number to retrieve. default: 1
pageSize	integer	Optional	Number of records per page. Between 1 and 100. Values outside this range are clamped to 50. default: 50

Response

All responses are JSON with Content-Type: application/json. The success field is the first indicator of outcome — check it before reading other fields.

Field	Type	Description
success	boolean	`true` if URA returned data. `false` on any error (auth, not found, or URA rejection).
request	object	Echo of the effective parameters sent to URA, including `clientTin` (the TIN resolved from the API key). Always present on both success and URA-failure responses. Useful for reconciliation and debugging.
pageNo	integer	Current page number as confirmed by URA. Present on success.
pageCount	integer	Total number of pages available for this query. Present on success.
totalSize	integer	Total number of matching invoices across all pages. Present on success.
records	array	Array of invoice objects for this page. Empty array `[]` on error.
message	string	Error description. Present only when `success` is `false`.

Record Fields

Each object in the records array contains the following fields. All values are strings; null means URA did not return that field for the record.

Field	Type	Description
invoiceNo	string	EFD invoice number assigned by URA.
deviceNo	string	EFD device serial number that issued the invoice. May have leading zeros — treat as text.
invoiceDate	string	Date and time the invoice was issued. Format varies by URA response.
invoiceType	string	`"1"` = Normal, `"2"` = Credit note, `"3"` = Debit note.
invoiceKind	string	`"1"` = Local, `"2"` = Export.
buyerTin	string \| null	Buyer TIN. `null` for non-TIN transactions.
buyerLegalName	string \| null	Registered legal name of the buyer.
sellerTin	string	Seller TIN (same as the queried `tin`).
grossAmount	string	Total invoice amount including tax.
netAmount	string	Invoice amount excluding tax.
taxAmount	string	VAT amount.
currency	string	Currency code. Typically `"UGX"`.
isInvalid	string	`"0"` = Valid, `"1"` = Voided/cancelled.
isRefund	string \| null	`"1"` if this is a refund transaction.
referenceNo	string \| null	Original invoice number for credit/debit notes.
antifakeCode	string \| null	URA anti-fake verification code.
branchName	string \| null	Branch name if the seller operates multiple branches.

Errors

HTTP Status	Condition	`message` example
401	Missing, invalid, or revoked `X-Api-Key`	`Invalid or revoked X-Api-Key`
403	Key is valid but not authorised for this endpoint	`This API key does not have EFD Invoice Query scope`
200 `success: false`	URA rejected or timed out the query	`URA rejected query (code 15): ...`

Note: when URA itself rejects the query the HTTP status is still 200 — check success: false and read message for the URA error detail. The request echo is included in this case so you can see exactly what was sent.

Example — cURL

Request Body

{
  "startDate":   "2024-01-01",
  "endDate":     "2024-06-30",
  "pageNo":      1,
  "pageSize":    50
}

cURL

curl -X POST \
  "https://portal.cypressrealitylabs.com/api/efris/invoice-list-query" \
  -H "X-Api-Key: <your-client-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2024-01-01",
    "endDate": "2024-06-30",
    "pageNo": 1,
    "pageSize": 50
  }'

To fetch all pages, send the same body with pageNo incremented from 1 up to the pageCount value returned in the first response.

Example — Success Response

HTTP 200 · success: true

{
  "success": true,
  "request": {
    "clientTin":   "1000048801",
    "startDate":   "2024-01-01",
    "endDate":     "2024-06-30",
    "invoiceNo":   null,
    "buyerTin":    null,
    "invoiceType": null,
    "invoiceKind": null,
    "pageNo":      1,
    "pageSize":    50
  },
  "pageNo":    1,
  "pageCount": 3,
  "totalSize": 120,
  "records": [
    {
      "invoiceNo":      "EFD20240115001",
      "deviceNo":       "0102345678",
      "invoiceDate":    "2024-01-15 10:22:00",
      "invoiceType":    "1",
      "invoiceKind":    "1",
      "buyerTin":       "1000099900",
      "buyerLegalName": "ACME ENTERPRISES LTD",
      "sellerTin":      "1000048801",
      "grossAmount":    "115000",
      "netAmount":      "100000",
      "taxAmount":      "15000",
      "currency":       "UGX",
      "isInvalid":      "0",
      "isRefund":       null,
      "referenceNo":    null,
      "antifakeCode":   "A1B2C3D4E5",
      "branchName":     null
    }
  ]
}

Example — Error Responses

HTTP 401 — Missing or revoked API key

{
  "success": false,
  "message": "Invalid or revoked X-Api-Key",
  "records": []
}

HTTP 403 — Key not authorised for this endpoint

{
  "success": false,
  "message": "This API key does not have EFD Invoice Query scope",
  "records": []
}

HTTP 200 · success: false — URA rejected the query

{
  "success":  false,
  "message":  "URA rejected query (code 15): Certificate verification failed",
  "records":  [],
  "request": {
    "clientTin": "1000048801",
    "startDate": "2024-01-01",
    "endDate":   "2024-06-30",
    "pageNo":    1,
    "pageSize":  50
  }
}