Introduction

Data Enrichment API enables users to gain additional insights and detailed information on transactions. By sending transaction data to the API, users can retrieve enriched information, such as merchant details, transaction categorization, and other metadata that can improve the analysis and understanding of the transaction.

Consent

User consent is the primary requirement to access any services in Open Banking. The user or account holder grants explicit consent to a Third-Party to access their financial data. This consent is given through a secure, multi-factor authentication process to verify the user's identity.

The consent request must include the following details:

Endpoint	`useCaseType` Value	`permissions` Value
`/v1/api/observice/connect`	`DATA-ENRICHMENT`	`ReadAccountsBasic` `ReadAccountsDetail` `ReadBalances` `ReadTransactionsBasic` `ReadTransactionsDetail` `ReadTransactionsCredits` `ReadTransactionsDebits`

Check Consent Management for more details to create, view, and revoke consents.

Get Customer Verification Services

Try in API Reference ➜

Endpoint details

Endpoint URL	Method	Authentication requirements
`v1/api/observice/dataEnrichmentTxns`	POST	1/. `clientId` 2. `clientCode` 3. `signature` 4. `Authorization Bearer: Token`

Sample request

{
  "dateTimeStamp": "YYYY-MM-DDTHH:MM:SS",
  "requestID": "Enter_Request_Id",
  "merchantId": "Enter_Merchant_Id",
  "fromDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
  "toDate": "YYYY-MM-DDTHH:MM:SS+HH:MM",
  "dataEnrichment":true,
  "banks": [
    {
      "code": "Enter_Bank_Code",
      "consentId":"Enter_Consent_Id"
    }
  ]
}

Request description

JSON Tag	Description	Data type
DateTimeStamp Mandatory	Stamp denoting the date and time of the request	String
RequestID Mandatory	Unique request identification	String
merchantId Mandatory	Unique merchant identification	String
fromDate Mandatory	Initial date of the transaction period	Date-Time
tpDate Mandatory	Pinal date of the transaction period	Date-Time
dateEnrichment Mandatory	Data enrichment service tag to be denoted as `true`	Boolean
banks Mandatory	Array of banks and consents	Object
code Mandatory	Unique bank identification code	String
consentId Mandatory	Unique consent identification	String

Sample response

{
  "success": true,
  "payload": [
    {
      "code": "SAMA",
      "consentId": "urn:SAMA:kac-63c82e6e-44ed-4890-b43f-330b20e433ae",
      "data": {
        "account": [
          {
            "accountId": "Account_Id",
            "accountHolderName": "Account_Holder_Name",
            "accountHolderShortName": "Account_Holder_Short_Name",
            "status": "Account_Status",
            "currency": "Currency",
            "nickname": "Account_Nickname",
            "accountType": "Account_Type",
            "accountSubType": "Account_Sub_Type",
            "accountIdentifiers": [
              {
                "identificationType": "Identification_Type",
                "identification": "Identification_Details",
                "name": "Name"
              }
            ],
            "servicer": {
              "identificationType": "Servicer_Identification_Type",
              "identification": "Servicer_Identification"
            },
            "statusUpdateDateTime": "YYYY-MM-DDTHH:MM:SS.SSSZ",
            "description": "Account_Description",
            "openingDate": "YYYY-MM-DDTHH:MM:SS.SSSZ",
            "maturityDate": "YYYY-MM-DDTHH:MM:SS.SSSZ",
            "transactions": [
              {
                "transactionId": "Transaction_Id",
                "transactionDateTime": "YYYY-MM-DDTHH:MM:SS.SSSZ",
                "transactionReference": "Transaction_Reference",
                "transactionInformation": "Transaction_Information",
                "subTransactionType": "Transaction_Sub_Type",
                "paymentModes": "Payment_Modes",
                "amount": {
                  "amount": "0.20",
                  "currency": "SAR"
                },
                "merchantDetails": {
                  "merchantName": "Merchant_Name",
                  "merchantCategoryCode": "Merchant_Category_Code",
                  "merchantId": "Merchant_Id"
                },
                "balance": {
                  "creditDebitIndicator": "Credit_Debit_Indicator",
                  "type": "Type",
                  "amount": {
                    "amount": "00.00",
                    "currency": "Currency"
                  }
                },
                "status": "Transaction_Status",
                "transactionMutability": "Transaction_Mutability",
                "bookingDateTime": "YYYY-MM-DDTHH:MM:SS.SSSZ",
                "chargeAmount": {
                  "amount": "0.00",
                  "currency": "SAR",
                  "chargeIncluded": true/false
                },
                "terminalId": 0000000,
                "flags": [
                  "KSAOB.Payroll"
                ],
                "cardInstrument": {
                  "cardSchemeName": "Card_Scheme_Name",
                  "instrumentType": "Instrument_Type",
                  "name": "Name",
                  "identification": "Identification_Details"
                },
                "creditorAccount": [
                  {}
                ],
                "debtorAccount": {
                  "identificationType": "Debit_Account",
                  "identification": "Identification_Details",
                  "name": "Name"
                },
                "bankTransactionCode": {
                  "domain": "Domain",
                  "domainCode": "Domain_Code",
                  "family": "Family",
                  "familyCode": "Family_Code",
                  "subFamily": "Sub_Family",
                  "subFamilyCode": "Sub_Family_Code"
                },
                "proprietaryBankTransactionCode": {
                  "code": "Code",
                  "issuer": "Issuer"
                },
                "creditorAgent": {
                  "identificationType": "Identification_Type",
                  "identification": "Identification",
                  "postalAddress": {
                    "addressType": "Address_Type",
                    "streetName": "Street_Name",
                    "buildingNumber": "Building_Number",
                    "postalCode": "Postal_Code",
                    "city": "City_Name",
                    "country": "Country",
                    "shortAddress": "Short_Address",
                    "unitNumber": "Unit_Number",
                    "secondaryNumber": "Secondary_Number",
                    "district": "District"
                  },
                  "name": "Name"
                },
                "debtorAgent": {
                  "identificationType": "Identification_Type",
                  "identification": "Identification",
                  "postalAddress": {
                    "addressType": "Address_Type",
                    "streetName": "Street_Name",
                    "buildingNumber": "Building_Number",
                    "postalCode": "Postal_Code",
                    "city": "City_Name",
                    "country": "Country",
                    "shortAddress": "Short_Address",
                    "unitNumber": "Unit_Number",
                    "secondaryNumber": "Secondary_Number",
                    "district": "District"
                  },
                  "name": "Name"
                },
                "billDetails": {
                  "billerId": 000000,
                  "billNumber": "Bill_Number",
                  "billPaymentType": "Bill_Payment_Type"
                },
                "category": {
                  "group": "Income",
                  "name": "Food & Dining",
                  "subCategory": "POS"
                }
              }
            ]
          }
        ]
      },
      "links": {
        "self": "https://"
      },
      "meta": {
        "totalPages": 1
      }
    }
  ]
}

Response description

JSON Tag	Description
success	Process success status represented as `True` or `False`
payload	Payload tag carrying response information
code	Unique bank code identification
consentId	Unique consent identification details
data	Tag carrying accounts and transactions data enrichment included in the response
account	Tag carrying information on the response for requested bank account
accountId	Unique account identification
accountHolderName	Name of the account holder
accountHolderShortName	Short name of the account holder
status	Status of the account
currency	Default currency of the account
nickname	Nickname of the account
accountType	Details of account type
accountSubType	Details of account sub-type
accountIdentifiers	Tag carrying account identifiers details
identificationType	Account identification type details
identification	Account identification details
name	Name of the account identifier
servicer	Tag carrying account servicer details
identificationType	Servicer identification type details
identification	Servicer identification details
statusUpdateDateTime	Last time and date of update for account information
description	Description of the update
openingDate	Opening date of the account
maturityDate	Maturity date of the account
transactions	Tag carrying account transactions information
transactionId	Unique transaction identification
transactionDateTime	Time and date of the transaction executed
transactionReference	Unique transaction reference details
transactionInformation	Details on transaction information
subTransactionType	Sub-type of the transaction
paymentModes	Mode of the payment
amount	Tag carrying information on transaction amount
amount	Amount of the transaction
currency	Currency in which the amount is displayed
merchantDetails	Tag carrying information about the merchant
merchantName	Name of the merchant
merchantCategoryCode	Unique merchant category identification code
merchantId	Unique merchant identification details
balance	Tag carrying info on account balance after the transaction
creditDebitIndicator	Credit or debit indicator for the transaction
type	Type of account balance
amount	Tag carrying information on balance amount
amount	Balance amount
currency	Currency in which the balance amount is shown
status	Status of the transaction
transactionMutability	Mutability factor of the transaction
bookingDateTime	Date and time of booking the transaction
chargeAmount	Tag carrying transaction charges information
amount	Total amount charged for the transaction
currency	Default currency of account in which the transaction charge amount is indicated
chargeIncluded	Indicates if the charge amount is included in transaction amount as `true` or `false`
terminalId	Unique terminal identification
flags	Tag carrying flags as array of strings
cardInstrument	Tag carrying card details
cardSchemeName	Scheme name description of the card
instrumentType	Type of instrument used for the card payment
name	Name on the card
identification	Unique card identification
creditorAccount	Tag carrying creditor account information
debtorAccount	Tag carrying debtor account information
identificationType	Type of identification of the account
identification	Account identification details
name	Name of the account holder
bankTransactionCode	Tag carrying transaction bank codes
domain	Domain details
domainCode	Domain code
family	Domain family details
familyCode	Domain family code
subFamily	Domain sub-family details
subFamilyCode	Domain sub-family code
proprietaryBankTransactionCode	Tag representing proprietary bank transaction code and details
code	Unique proprietary transaction code
issuer	Name of the issuer of the code
creditorAgent	Tag carrying creditor agent information
debtorAgent	Tag carrying debtor agent information
identificationType	Type of identification of the creditor/debtor account
identification	Unique identification details of the creditor/debtor account
postalAddress	Postal address of the creditor/debtor account
addressType	Address type on the creditor/debtor account
streetName	Street name on the creditor/debtor account
buildingNumber	Building number of the creditor/debtor account
postalCode	Postal code on the creditor/debtor
city	City of the creditor/debtor
country	Country of the creditor/debtor
shortAddress	Short address of the creditor/debtor
unitNumber	Unit number of the creditor/debtor
secondaryNumber	Secondary number of the creditor/debtor
district	District of the creditor/debtor
name	Name of the creditor/debtor
billDetails	Tag carrying bill details
billerId	Unique biller identification
billNumber	Bill number
billPaymentType	Payment type for the bill
category	Tag carrying transaction category details
group	Group of transaction among `Income` or `Expense`
name	Name for the transaction category
subCategory	Sub-category of the transaction
links	Redirect link
self	Own link/URL details
meta	Meta tag
totalPages	Information displayed in terms of pages

Available Categories

Category Name (English)	Category Name (Arabic)
Auto & Transport	السيارات والنقل
Bills & Utilities	الفواتير والمرافق
Business Service	خدمات الأعمال
Clothing Stores	متاجر الملابس
Education	التعليم
Fees & Charges	الرسوم والتكاليف
Financial	المالية
Food & Dining	الطعام
Gifts & Donations	يُقرض
Health & Fitness	الصحة واللياقة
Human Resources	الموارد البشرية
Income	الدخل
Insurance	تأمين
Investment	استثمار
Loans	القروض
Manufacturing	تصنيع
Miscellaneous	متنوع
Professional Related	ذات الصلة المهنية
Research & Development	البحث والتطوير
Retail Outlet Services	خدمات منافذ البيع بالتجزئة
Shopping	التسوق
Taxes	الزكاة و الضرائب
Technology & IT	تقنية المعلومات
Transfer	الحوالات
Travel	سفر
Uncategorized	غير مصنف