Changelog

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

Parameter

Type

Description

Authorization REQUIRED

String

Set type to bearer token and the value to the accessToken obtained using the Exchange Token request.

Body Parameters

Parameter

Type

Description

appSecret REQUIRED

String

Private token generated at application creation.

userSecret
REQUIRED

String

Encrypted version of the userKey.

accountID
REQUIRED

String

An identifier for a bank account the user has. Obtained from the Get Accounts endpoint.

toDate
REQUIRED

String

Date to end transactions on.
Format as “YYYY-MM-DD”.

fromDate
REQUIRED

String

Date 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

Parameter

Type

Description

operationID

String

Unique ID generated to identify a specific operation.

success

Boolean

Returns true if request is successful and false for all else.

status

Enum

Operation status.

done - Operation Completed

failed - Operation Failed

user_input_required - Pending User Input

initialized - Operation In Progress

transactions

Array<Transaction>

Array containing the transactional data for the specified period.

msg

String

Descriptive message returned only in case of failure

type

Enum

Type of error encountered

Is only returned if the request was not successful

Transaction schema

Parameter

Type

Description

afterAmount

Number

Account balance after this transaction was executed.

beforeAmount

Number

Account balance before the transaction was executed.

amount

Number

Transaction amount.

date

Date

Transaction timestamp as provided by the financial institution (in the financial institution's timezone).

description

String

Transaction description as provided by the financial institution.

details

String

Any extra details provided by the financial institution.

type

Enum

Specifies if the transaction is debit or credit.

  • debit

    -credit

currency

Object<Currency>

Object containing the transaction's currency information.

category

String

Category for the specific transaction. All transaction categories

reference

String

Reference number for bank transfers

Currency schema

Parameter

Type

Description

code

String

ISO 4217 code of the currency.

name

String

Currency'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 seeError Codes .