Tutorial: Get Transaction Group Analysis

Transaction Group Analysis product is available as a Private Beta version.

Introduction

This tutorial explains how to get Transaction Group Analysis in the UK with the Modelo Sandbox.

Note: All requests made to the Yapily API require basic authentication.

1. Select bank

To find which banks support accessing account and transaction information use GET institutions to retrieve the list of your supported institutions.

Request:

Copy

Copied

curl -L -X GET 'https://api.yapily.com/institutions' \
  -u 'APPLICATION_KEY:APPLICATION_SECRET'

Response:

Copy

Copied

{  
  "meta": {
    "tracingId": "acbb76db4ab8f4ac7f039d000456c13f",
    "count": 1
  },
  "data": [
    {
      "id": "modelo-sandbox",
      "name": "Modelo Sandbox",
      "fullName": "Modelo Sandbox",
      "countries": [
        {
          "displayName": "United Kingdom",
          "countryCode2": "GB"
        }
      ],
      "environmentType": "SANDBOX",
      "credentialsType": "OPEN_BANKING_UK_AUTO",
      "media": [
        {
          "source": "https://images.yapily.com/image/ce2bfdbf-1ae2-4919-ab7b-e8b3d5e93b36?size=0",
          "type": "icon"
        },
        {
          "source": "https://images.yapily.com/image/ca502f24-d6df-4785-b4b8-1034b100af77?size=0",
          "type": "logo"
        }
      ],
      "features": [
        "INITIATE_ACCOUNT_REQUEST",
        "ACCOUNT_REQUEST_DETAILS",
        "EXISTING_PAYMENTS_DETAILS",
        "ACCOUNT_BALANCES",
        "CREATE_BULK_PAYMENT",
        "ACCOUNT_PERIODIC_PAYMENTS",
        "ACCOUNT_STATEMENTS",
        "INITIATE_BULK_PAYMENT",
        "ACCOUNT_STATEMENT",
        "ACCOUNT",
        "INITIATE_DOMESTIC_PERIODIC_PAYMENT",
        "INITIATE_SINGLE_PAYMENT_SORTCODE",
        "ACCOUNT_DIRECT_DEBITS",
        "ACCOUNTS",
        "ACCOUNT_TRANSACTIONS",
        "EXISTING_PAYMENT_INITIATION_DETAILS",
        "CREATE_DOMESTIC_SINGLE_PAYMENT",
        "INITIATE_DOMESTIC_SINGLE_PAYMENT",
        "ACCOUNT_STATEMENT_FILE",
        "CREATE_INTERNATIONAL_SINGLE_PAYMENT",
        "IDENTITY",
        "CREATE_DOMESTIC_SCHEDULED_PAYMENT",
        "INITIATE_DOMESTIC_SCHEDULED_PAYMENT",
        "CREATE_SINGLE_PAYMENT_SORTCODE",
        "ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
        "INITIATE_INTERNATIONAL_SINGLE_PAYMENT",
        "PERIODIC_PAYMENT_FREQUENCY_EXTENDED",
        "ACCOUNT_SCHEDULED_PAYMENTS",
        "CREATE_DOMESTIC_PERIODIC_PAYMENT"
      ]
    }
  ]
}

Filter the list for all institutions that support the ACCOUNTS and ACCOUNT_TRANSACTIONS features. Then display these institutions in your application so the user can select which bank to share their account information from.

Once the user selects a bank, store the id of the institution to use in step 2.

2. Authorise

note

This example uses a single redirect flow using a callback URL.

Execute create account authorisation, including the institution ID and your callback URL.

Request:

Copy

Copied

curl -L -X POST 'https://api.yapily.com/account-auth-requests' \
 -H 'Content-Type: application/json' \
 -u 'APPLICATION_KEY:APPLICATION_SECRET' \
 -d '{
   "applicationUserId": "account-data-and-transactions-tutorial",
   "institutionId": "modelo-sandbox",
   "callback": "https://display-parameters.com/"
 }'

Response:

Copy

Copied

{
  "meta": {
    "tracingId": "ceab45e96f852afdb59ec8eaf8f93594"
  },
  "data": {
    "id": "979f8a58-c955-46b5-b25d-bdc447c28a80",
    "userUuid": "c78035e1-3140-44f7-9539-527785069356",
    "applicationUserId": "account-data-and-transactions-tutorial",
    "institutionId": "modelo-sandbox",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2021-03-04T11:05:17.234Z",
    "featureScope": [
      "ACCOUNT_STATEMENT_FILE",
      "ACCOUNT_STATEMENTS",
      "ACCOUNT_BALANCES",
      "ACCOUNT_SCHEDULED_PAYMENTS",
      "ACCOUNT_STATEMENT",
      "ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
      "ACCOUNT_TRANSACTIONS",
      "ACCOUNT_DIRECT_DEBITS",
      "IDENTITY",
      "ACCOUNT",
      "ACCOUNTS",
      "ACCOUNT_PERIODIC_PAYMENTS"
    ],
    "state": "e539228113de43b3a3d4c3b9944620d3",
    "institutionConsentId": "aac-74e55df8-a673-48b4-b8ae-3e8d0e45080f",
    "authorisationUrl": "{authorisationUrl}",
    "qrCodeUrl": "https://images.yapily.com/image/d4113d96-9d6c-4e69-a840-2e327cff1b1d/1614855917?size=0"
  }
}

Redirect the user to the authorisationUrl returned in the response.

The user is then asked to login and authorise the account sharing request with their bank. The Modelo sandbox credentials are: mits / mits.

Upon completion, the user is redirected back to the callback URL supplied in the request. In this example, the callback is https://display-parameters.com/ which displays the parameters returned with the redirect.

Store the consentToken and userUuid from the API response to use when creating a financial profile in step 3.

3. Create financial profile consent

Create a financial profile consent specifying the userUuid in the path, and the consentToken in the header.

Request:

Copy

Copied

curl -L -X POST 'https://api.yapily.com/users/{userUuid}/profile/consents' \
  -H 'consent: {consentToken}' \
  -u 'APPLICATION_KEY:APPLICATION_SECRET'

Response:

Copy

Copied

{
    "id": "bb76f9a7-f5ff-480d-8d40-4b0e1eb8f400",
    "status": "PENDING",
    "userId": "c78035e1-3140-44f7-9539-527785069356",
    "referenceConsentId": "979f8a58-c955-46b5-b25d-bdc447c28a80",
    "institutionId": "modelo-sandbox"
}

The status of the financial profile consent is returned in the response.

The initial status is PENDING as the profile consent has been created but the financial data associated with that consent has not been retrieved yet. The requests to retrieve the financial data for a profile consent are handled by Yapily behind the scenes asynchronously.

You should poll GET /profile/consents/{id} until the status transitions to COMPLETED, and then move to step 4. This could take several minutes after creating the profile consent, depending on the amount of financial data available.

Note: If the user has multiple consents, repeat Steps 2-3 for each consent obtained from the user.

4. Get Transaction Group Analysis

Get Transaction Group Analysis for the user, specifying the userUuid.

Note: After 5 minutes the profileConsents.status will be EXPIRED. To retrieve Transaction Group Analysis again you need to create a new financial profile consent for the user.

Request:

Copy

Copied

curl -L -X GET 'https://api.yapily.com/users/{userUuid}/profile/transaction-groups' \
  -u 'APPLICATION_KEY:APPLICATION_SECRET'

Response:

Copy

Copied

{
  "status": "COMPLETED",
  "profileConsents": [
    {
      "id": "bb76f9a7-f5ff-480d-8d40-4b0e1eb8f400",
      "status": "COMPLETED",
      "userId": "c78035e1-3140-44f7-9539-527785069356",
      "referenceConsentId": "979f8a58-c955-46b5-b25d-bdc447c28a80",
      "institutionId": "modelo-sandbox"
    }
  ],
  "enrichment": {
      "incomeStreams": [
        {
          "name": "4",
          "transactions": [
            {
              "transactionId": "94611550-751a-42b8-9608-2821da426e20",
              "transactionInformation": "4",
              "amount": 100.23,
              "institution": "modelo-sandbox",
              "bookingDateTime": "2022-08-25T07:28:09.202Z"
            },
            {
              "transactionId": "8399d235-8240-4d4c-b527-ad4fb45464dc",
              "transactionInformation": "4",
              "amount": 100.23,
              "institution": "modelo-sandbox",
              "bookingDateTime": "2022-08-24T07:22:18.002Z"
            },
            {
              "transactionId": "155ffa5b-2a26-4478-b071-c63ab2a3585b",
              "transactionInformation": "4",
              "amount": 100.23,
              "institution": "modelo-sandbox",
              "bookingDateTime": "2022-08-23T07:20:31.089Z"
            },
            {
              "transactionId": "af58efcf-f8cb-4478-a11b-57d8fe10e75d",
              "transactionInformation": "4",
              "amount": 100.23,
              "institution": "modelo-sandbox",
              "bookingDateTime": "2022-07-11T06:53:12.783Z"
            },
            {
              "transactionId": "9a1a24bf-4917-4918-a709-d0e0d2531251",
              "transactionInformation": "4",
              "amount": 172.8,
              "institution": "modelo-sandbox",
              "bookingDateTime": "2022-07-07T13:47:01.125Z"
            },
            {
              "transactionId": "c51b4a45-05b0-494f-b962-d5d1898a4f21",
              "transactionInformation": "4",
              "amount": 100.23,
              "institution": "modelo-sandbox",
              "bookingDateTime": "2022-06-23T12:59:35.274Z"
            }
          ],
        "transactionSchedule": {
          "frequency": "Every two weeks",
          "detailedFrequency": "Every two weeks on day n",
          "detailedFrequencyParameter": 4
          },
        "scheduleConsistencyScore": 0.5,
        "nextExpectedTransactionDate": "2022-09-02",
        "earliestTransactionDate": "2022-06-24",
        "mostRecentTransactionDate": "2022-08-25",
        "amountConsistencyScore": 0.76,
        "averageAmount": 112.33
      }
    ],
    "expenditureStreams": [],
    "recentlyTerminatedIncomeStreams": [],
    "recentlyTerminatedExpenditureStreams": []
  }
}

profileConsents lists all the profile consents which were used to generate the financial profile.
enrichment.incomeStreams lists all the transaction streams which were identified for the user.
enrichment.transactionSchedule provides more detail about the consistency of the transaction amount and schedule and predicts the next occurrence of this transaction.