Enrichment API

The Enrichment V2 endpoint accepts a response-type parameter, which should be set to consumer. It returns enriched customer transactions.

---

Authorization

Header	Value
Api-key	string (tkn_ten_XXX..)
Content-Type	application/json

---

Enriching Transactions

Endpoint

UAESaudi ArabiaBahrainProductionStaging

POST https://enrichment-prd-uae.lunedata.io/api/v2/transaction/enrich?response-type=consumer

Query Parameters

Key	Value
response-type	consumer

Request Body Schema

Required (Required field) · Important (Impacts accuracy/functionality — essentially required if available)

Field	Type	Lunehub Transactions	Analytics (Insights & Nudges)	Lune Pulse
Core Transaction Fields
raw_description	string	Required	Required	Required
amount	float	Required	Required	Required
ref_id	string	Required	Required	Required
transaction_id	string	Required	Required	Required
Identity Fields
customer_id	string	Required	Required	Required
account_id	string	Important	Required	Required
card_id	string	Important	Required	Required
card_name	string	Important	Required	Required
Merchant Fields
merchant_name	string	Required	Required	Required
merchant_id	string	Important	Important	Required
mcc	string	Required	Required	Required
Transaction Metadata
direction	string	Required	Required	Required
is_self_transaction	boolean	Required	Required	Required
is_transfer	boolean	Required	Required	Required
iso_currency_cd	string	Required	Required	Required
occurred_at	string/DateTime	Required	Required	Required
pos_id	string	Important	Important	Required
pos_entry_mode	string	Important	Important	Required
Location object sub-fields of location object
location	object	Required	Required	Required
↳ iso_country_cd	string	Required	Required	Required
↳ city	string	Required	Required	Required
↳ address	string	Important	Important	Important
↳ region	string	Important	Important	Important
↳ postal_code	string	Important	Important	Important

Response Schema

Field	Type	Description
ref_id	string	Reference ID for the enriched transaction
transaction_id	string	Client's internal transaction ID (returned in place of ref_id only when the client's account is configured to return transaction_id)
global_tx_id	string	Unique global transaction identifier
brand_name	string	Enriched brand name
brand_name_ar	string	Brand name transliterated or translated in Arabic (returned only if Arabic is enabled for the tenant)
brand_logo	string	Relative path to brand logo. Concatenate with https://brandlogos.azureedge.net/media/
brand_url	string	Website URL of the brand
category_id	string	Consumer category identifier
category_name	string	Consumer category name in English
category_name_ar	string	Consumer category name in Arabic (returned only if Arabic is enabled for the tenant)
sub_category_id	string	Consumer sub-category identifier
sub_category_name	string	Consumer sub-category name in English
sub_category_name_ar	string	Consumer sub-category name in Arabic (returned only if Arabic is enabled for the tenant)

Request Example

{
  "transactions": [
    {
      "raw_description": "STARBUCKS-D582 AL SHAY DUBAI ARE",
      "amount": -40,
      "ref_id": "0001234",
      "transaction_id": "1234AB34",
      "customer_id": "cust1",
      "account_id": "acc1",
      "card_id": "card1",
      "card_name": "Emirates Skywards Platinum",
      "merchant_name": "STARBUCKS-D582 AL SHAY DUBAI ARE",
      "direction": "DEBIT",
      "is_self_transaction": false,
      "is_transfer": true,
      "iso_currency_cd": "AED",
      "occurred_at": "2025-09-30",
      "mcc": "0780",
      "merchant_id": "43253545",
      "pos_id": "POS12345",
      "pos_entry_mode": "CHIP",
      "location": {
        "iso_country_cd": "ARE",
        "city": "Dubai",
        "address": "Al Suwayeb Str. 28",
        "region": null,
        "postal_code": null
      }
    }
  ]
}

Response Example

{
  "transactions": [
    {
      "brand_name": "Starbucks",
      "brand_logo": "brand_logos/Starbucks_RsMC6xy.png",
      "global_tx_id": "1a4aa7df-1c31-43ec-99a1-9604419caf44",
      "brand_name_ar": "ستاربكس",
      "brand_url": "https://www.starbucks.com/",
      "category_id": "10",
      "category_name": "Dining",
      "sub_category_id": "10-3",
      "sub_category_name": "Coffeeshop",
      "category_name_ar": "المطاعم",
      "sub_category_name_ar": "مقهى",
      "ref_id": "1a4aa7df-1c31-43ec-99a1-9604419caf44"
    }
  ]
}

note

If the client’s account is configured to enforce the transaction_id field, only then will the transaction_id be included in the response.

---

Response Status Codes

• 200 Success: Standard response for successful HTTP requests.
• 400 Bad Request: The request cannot be fulfilled due to bad syntax.