Get Categorized Transactions

Method is used to retrieve transactions that user has performed over a specific period of time from their bank account. Every transaction in the response is categorized. Transaction categories stay the same across all banks.

Date range of the transactions that can be retrieved varies for each bank. The range supported by the user's bank is shown in the transactionRange parameter of Get Account Metadata endpoint.

Request

https://api.dapi.com/v2/data/categorizedTransactions/get

Request Example

{
    "appSecret": "00bae841ad979345fca2e2585c000da7eac420504d189cf63315e7a6234d45c68dbd6fff749167292cd1475622805dce7a2b979db3c16e25a2897158ee63845b1043930ff603e19deb1d2d54ad9afc3d52df241d3c4e7286244a2f98a10212e38b2e9f8b0e3a7592702fa4358fb9103b93a26dd6bb92c2be0327ac054f14becc",
    "userSecret": "t1fcWW3IXbzsMYdMNlr6m6E6N75WFcaaVjsMiqUieBnbmGUoUJv5O/0Zy2WwwiNKUPGmIUTa64QIxmIkG/CjIfOSe5H0ZY7XMRwNao/qqDUIlY//viU2eAyihm4x5bkiwzQ2/pg7TaQatGLv/bX0oBCOmNNf2teoT8fIHHcfVzhZCyfsWoqrA8wM0tD0UgybqK/QQcfos589TpIZ9M32Ibm0loupK8y+xWVoBE88FTp2ovqoGF0jvR39oy9FL/P3lVNWxsd/r9fGq2zn9DeUjZKRlhYeudHxDlyQbyfYQUzusY8pS1I34Yt4GMwICQbKxZINO4nkcgajlbt8/Iykkq7cEOywiOAMsjQ0pmf6SN+wn2m42FWknIzwSA7enMJn3DoPrtCzZq99E04m2Y5YRhJ2glUlbZ+4SQPlskzoOkmV6kOumBl3cEIEV0Q0NIGyA6gvBumEMJBrk7SpL27HVoFvMAdsAHtxz8PejXg1hNgxuBIFocsJeOZNq5dXALAMZzUDUl5/SlCMWms3tlUPusrWKjkKr7eOQ/HpXlauluGGq5NN03cLBaGinyVBmGWiDqgJi6IzLYrrmeB1QJzYOCg+e/JFQ54/EwfaMTB7vupkIpkHmKlu2SP83RwQ3ZMsnr+Nvun32sAKCBHB70Jq2+0WWCFUzTHZ3QIBeb/LRwg=",
    "fromDate": "2020-04-01",
    "toDate": "2020-04-30",
    "accountID": "ntV7rbYoexYaGDRfLCAo8vw1xXgu2VaXXtqvNoMU0sfy6aNErfUEGMD+P6lAlkzu/GKxPeoef7d7eNoxlHKyRw=="
}

Request headers

ParameterTypeDescription
Authorization
REQUIRED
StringSet type to bearer token and the value to the accessToken obtained using the Exchange Token request.

Body Parameters

ParameterTypeDescription
appSecret
REQUIRED
StringPrivate token generated at application creation.
userSecret
REQUIRED
StringEncrypted version of the userKey.
accountID
REQUIRED
StringAn identifier for a bank account the user has. Obtained from the Get Accounts endpoint.
toDate
REQUIRED
StringDate to end transactions on.
Format as “YYYY-MM-DD”.
fromDate
REQUIRED
StringDate to start transactions from. Format as “YYYY-MM-DD”.
userInputs
OPTIONAL
Array<userInputs>Array of UserInputs object, required only if initial request responded with user inputs specification.

You can read more about user inputs specification on Specify User Input

Response

Response Example

{
    "operationID": "e1303f1a-5146-4a91-99a6-1762726cea30",
    "success": true,
    "status": "done",
    "transactions": [
        {
            "afterAmount": 200,
            "beforeAmount": 244.1,
            "amount": 44.1,
            "currency": {
                "code": "AED",
                "name": "UNITED ARAB EMIRATES DIRHAM"
            },
            "date": "2020-03-12T19:04:11.000Z",
            "description": "ZARA",
            "details": "99392038-AlGamor",
            "category": "Shopping",
            "type": "debit",
            "reference": "A9283829"
        },
        {
            "afterAmount": 132.8,
            "beforeAmount": 200,
            "amount": 67.2,
            "currency": {
                "code": "AED",
                "name": "UNITED ARAB EMIRATES DIRHAM"
            },
            "date": "2020-03-12T19:22:47.000Z",
            "description": "POTATO STATION MEALS",
            "details": "",
            "category": "Dining",
            "type": "debit",
            "reference": "A8283829"
        },
    ]
}

Response Parameters

ParameterTypeDescription
operationIDStringUnique ID generated to identify a specific operation.
successBooleanReturns true if request is successful and false for all else.
statusEnumOperation status.

done - Operation Completed

failed - Operation Failed

user_input_required - Pending User Input

initialized - Operation In Progress

*For further explanation see Operation Statuses
transactionsArray<Transaction>Array containing the transactional data for the specified period.
msgStringDescriptive message returned only in case of failure
typeEnumType of error encountered

Is only returned if the request was not successful

Transaction schema

ParameterTypeDescription
afterAmountNumberAccount balance after this transaction was executed.
beforeAmountNumberAccount balance before the transaction was executed.
amountNumberTransaction amount.
dateDateTransaction timestamp as provided by the financial institution (in the financial institution's timezone).
descriptionStringTransaction description as provided by the financial institution.
detailsStringAny extra details provided by the financial institution.
typeEnumSpecifies if the transaction is debit or credit.

- debit

-credit
currencyObject<Currency>Object containing the transaction's currency information.
categoryStringCategory for the specific transaction. All transaction categories
referenceStringReference number for bank transfers

Currency schema

ParameterTypeDescription
codeStringISO 4217 code of the currency.
nameStringCurrency's full name.

Examples

Successful

{
    "appSecret": "00bae841ad979345fca2e2585c000da7eac420504d189cf63315e7a6234d45c68dbd6fff749167292cd1475622805dce7a2b979db3c16e25a2897158ee63845b1043930ff603e19deb1d2d54ad9afc3d52df241d3c4e7286244a2f98a10212e38b2e9f8b0e3a7592702fa4358fb9103b93a26dd6bb92c2be0327ac054f14becc",
    "userSecret": "t1fcWW3IXbzsMYdMNlr6m6E6N75WFcaaVjsMiqUieBnbmGUoUJv5O/0Zy2WwwiNKUPGmIUTa64QIxmIkG/CjIfOSe5H0ZY7XMRwNao/qqDUIlY//viU2eAyihm4x5bkiwzQ2/pg7TaQatGLv/bX0oBCOmNNf2teoT8fIHHcfVzhZCyfsWoqrA8wM0tD0UgybqK/QQcfos589TpIZ9M32Ibm0loupK8y+xWVoBE88FTp2ovqoGF0jvR39oy9FL/P3lVNWxsd/r9fGq2zn9DeUjZKRlhYeudHxDlyQbyfYQUzusY8pS1I34Yt4GMwICQbKxZINO4nkcgajlbt8/Iykkq7cEOywiOAMsjQ0pmf6SN+wn2m42FWknIzwSA7enMJn3DoPrtCzZq99E04m2Y5YRhJ2glUlbZ+4SQPlskzoOkmV6kOumBl3cEIEV0Q0NIGyA6gvBumEMJBrk7SpL27HVoFvMAdsAHtxz8PejXg1hNgxuBIFocsJeOZNq5dXALAMZzUDUl5/SlCMWms3tlUPusrWKjkKr7eOQ/HpXlauluGGq5NN03cLBaGinyVBmGWiDqgJi6IzLYrrmeB1QJzYOCg+e/JFQ54/EwfaMTB7vupkIpkHmKlu2SP83RwQ3ZMsnr+Nvun32sAKCBHB70Jq2+0WWCFUzTHZ3QIBeb/LRwg=",
    "fromDate": "2020-02-01",
    "toDate": "2020-04-30",
	  "accountID": "ntV7rbYoexYaGDRfLCAo8vw1xXgu2VaXXtqvNoMU0sfy6aNErfUEGMD+P6lAlkzu/GKxPeoef7d7eNoxlHKyRw=="
}
{
    "operationID": "e1303f1a-5146-4a91-99a6-1762726cea30",
    "success": true,
    "status": "done",
    "transactions": [
        {
            "afterAmount": 200,
            "beforeAmount": 244.1,
            "amount": 44.1,
            "currency": {
                "code": "AED",
                "name": "UNITED ARAB EMIRATES DIRHAM"
            },
            "date": "2020-03-12T19:04:11.000Z",
            "description": "ZARA",
            "details": "99392038-AlGamor",
            "category": "Shopping",
            "type": "debit",
            "reference": "A9283829"
        },
        {
            "afterAmount": 132.8,
            "beforeAmount": 200,
            "amount": 67.2,
            "currency": {
                "code": "AED",
                "name": "UNITED ARAB EMIRATES DIRHAM"
            },
            "date": "2020-03-12T19:22:47.000Z",
            "description": "POTATO STATION MEALS",
            "details": "",
            "category": "Dining",
            "type": "debit",
            "reference": "A8283829"
        },
    ]
}

When User Input Required

{
    "appSecret": "00bae841ad979345fca2e2585c000da7eac420504d189cf63315e7a6234d45c68dbd6fff749167292cd1475622805dce7a2b979db3c16e25a2897158ee63845b1043930ff603e19deb1d2d54ad9afc3d52df241d3c4e7286244a2f98a10212e38b2e9f8b0e3a7592702fa4358fb9103b93a26dd6bb92c2be0327ac054f14becc",
    "userSecret": "t1fcWW3IXbzsMYdMNlr6m6E6N75WFcaaVjsMiqUieBnbmGUoUJv5O/0Zy2WwwiNKUPGmIUTa64QIxmIkG/CjIfOSe5H0ZY7XMRwNao/qqDUIlY//viU2eAyihm4x5bkiwzQ2/pg7TaQatGLv/bX0oBCOmNNf2teoT8fIHHcfVzhZCyfsWoqrA8wM0tD0UgybqK/QQcfos589TpIZ9M32Ibm0loupK8y+xWVoBE88FTp2ovqoGF0jvR39oy9FL/P3lVNWxsd/r9fGq2zn9DeUjZKRlhYeudHxDlyQbyfYQUzusY8pS1I34Yt4GMwICQbKxZINO4nkcgajlbt8/Iykkq7cEOywiOAMsjQ0pmf6SN+wn2m42FWknIzwSA7enMJn3DoPrtCzZq99E04m2Y5YRhJ2glUlbZ+4SQPlskzoOkmV6kOumBl3cEIEV0Q0NIGyA6gvBumEMJBrk7SpL27HVoFvMAdsAHtxz8PejXg1hNgxuBIFocsJeOZNq5dXALAMZzUDUl5/SlCMWms3tlUPusrWKjkKr7eOQ/HpXlauluGGq5NN03cLBaGinyVBmGWiDqgJi6IzLYrrmeB1QJzYOCg+e/JFQ54/EwfaMTB7vupkIpkHmKlu2SP83RwQ3ZMsnr+Nvun32sAKCBHB70Jq2+0WWCFUzTHZ3QIBeb/LRwg=",
    "fromDate": "2020-02-01",
    "toDate": "2020-04-30",
	  "accountID": "ntV7rbYoexYaGDRfLCAo8vw1xXgu2VaXXtqvNoMU0sfy6aNErfUEGMD+P6lAlkzu/GKxPeoef7d7eNoxlHKyRw=="
}
{
    "operationID": "47204fa6-dca6-44a5-8111-6c6489a232a2",
    "success": true,
    "status": "user_input_required",
    "userInputs": [
    {
      "answer": "",
      "id": "otp",
      "index": 0,
      "query": "Please enter a Smart Pass Token from your ENBD mobile application",
      "queryType": "txt"
    }
    ]
}

Failed - Invalid Date Format

{
    "appSecret": "00bae841ad979345fca2e2585c000da7eac420504d189cf63315e7a6234d45c68dbd6fff749167292cd1475622805dce7a2b979db3c16e25a2897158ee63845b1043930ff603e19deb1d2d54ad9afc3d52df241d3c4e7286244a2f98a10212e38b2e9f8b0e3a7592702fa4358fb9103b93a26dd6bb92c2be0327ac054f14becc",
    "userSecret": "t1fcWW3IXbzsMYdMNlr6m6E6N75WFcaaVjsMiqUieBnbmGUoUJv5O/0Zy2WwwiNKUPGmIUTa64QIxmIkG/CjIfOSe5H0ZY7XMRwNao/qqDUIlY//viU2eAyihm4x5bkiwzQ2/pg7TaQatGLv/bX0oBCOmNNf2teoT8fIHHcfVzhZCyfsWoqrA8wM0tD0UgybqK/QQcfos589TpIZ9M32Ibm0loupK8y+xWVoBE88FTp2ovqoGF0jvR39oy9FL/P3lVNWxsd/r9fGq2zn9DeUjZKRlhYeudHxDlyQbyfYQUzusY8pS1I34Yt4GMwICQbKxZINO4nkcgajlbt8/Iykkq7cEOywiOAMsjQ0pmf6SN+wn2m42FWknIzwSA7enMJn3DoPrtCzZq99E04m2Y5YRhJ2glUlbZ+4SQPlskzoOkmV6kOumBl3cEIEV0Q0NIGyA6gvBumEMJBrk7SpL27HVoFvMAdsAHtxz8PejXg1hNgxuBIFocsJeOZNq5dXALAMZzUDUl5/SlCMWms3tlUPusrWKjkKr7eOQ/HpXlauluGGq5NN03cLBaGinyVBmGWiDqgJi6IzLYrrmeB1QJzYOCg+e/JFQ54/EwfaMTB7vupkIpkHmKlu2SP83RwQ3ZMsnr+Nvun32sAKCBHB70Jq2+0WWCFUzTHZ3QIBeb/LRwg=",
    "fromDate": "2020-22-01",
    "toDate": "2020-04-30",
	  "accountID": "ntV7rbYoexYaGDRfLCAo8vw1xXgu2VaXXtqvNoMU0sfy6aNErfUEGMD+P6lAlkzu/GKxPeoef7d7eNoxlHKyRw=="
}
{
  "operationID": "9631b8b4-79ab-4568-a462-cc530fb13eb1",
  "msg": "fromDate must be before toDate",
  "type": "INVALID_DATE_FORMAT",
  "success": false,
  "status": "failed"
}

Failed - Invalid AccountID specified

{
    "appSecret": "00bae841ad979345fca2e2585c000da7eac420504d189cf63315e7a6234d45c68dbd6fff749167292cd1475622805dce7a2b979db3c16e25a2897158ee63845b1043930ff603e19deb1d2d54ad9afc3d52df241d3c4e7286244a2f98a10212e38b2e9f8b0e3a7592702fa4358fb9103b93a26dd6bb92c2be0327ac054f14becc",
    "userSecret": "t1fcWW3IXbzsMYdMNlr6m6E6N75WFcaaVjsMiqUieBnbmGUoUJv5O/0Zy2WwwiNKUPGmIUTa64QIxmIkG/CjIfOSe5H0ZY7XMRwNao/qqDUIlY//viU2eAyihm4x5bkiwzQ2/pg7TaQatGLv/bX0oBCOmNNf2teoT8fIHHcfVzhZCyfsWoqrA8wM0tD0UgybqK/QQcfos589TpIZ9M32Ibm0loupK8y+xWVoBE88FTp2ovqoGF0jvR39oy9FL/P3lVNWxsd/r9fGq2zn9DeUjZKRlhYeudHxDlyQbyfYQUzusY8pS1I34Yt4GMwICQbKxZINO4nkcgajlbt8/Iykkq7cEOywiOAMsjQ0pmf6SN+wn2m42FWknIzwSA7enMJn3DoPrtCzZq99E04m2Y5YRhJ2glUlbZ+4SQPlskzoOkmV6kOumBl3cEIEV0Q0NIGyA6gvBumEMJBrk7SpL27HVoFvMAdsAHtxz8PejXg1hNgxuBIFocsJeOZNq5dXALAMZzUDUl5/SlCMWms3tlUPusrWKjkKr7eOQ/HpXlauluGGq5NN03cLBaGinyVBmGWiDqgJi6IzLYrrmeB1QJzYOCg+e/JFQ54/EwfaMTB7vupkIpkHmKlu2SP83RwQ3ZMsnr+Nvun32sAKCBHB70Jq2+0WWCFUzTHZ3QIBeb/LRwg=",
    "fromDate": "2020-04-01",
    "toDate": "2020-04-30",
	  "accountID": "invalid_account_id"
}

❗️

Why invalid accountID ?

If you think you are passing a correct accountID into the request, but the request keeps failing. This is an indicator that you should call getAccounts endpoint again in order to retrieve up to date accountIDs.

{
    "operationID": "EBILAEAD_L:6b859dba-8ea1-43fc-b913-f9c3ed5039a8",
    "msg": "Account ID is invalid.",
    "type": "INVALID_ACCOUNT_ID",
    "success": false,
    "status": "failed"
}

📘

Note

For more information and detailed breakdown of possible errors, please see Error Codes .