Tutorial: Get financial profile

The Financial Profile feature is available as a Private Beta version. Please contact your Customer Success Manager if you would like to access it.

The Financial Profile endpoints assist in collating authorised consents for a user which can subsequently be used to classify user income streams across multiple accounts. For each income stream, the financial profile determines the frequency and score that describes how well the income stream fits to that schedule.

1. Create a user

First, we must create a new user for our PSU. This will allow each PSU to be associated with a unique user and userUuid, which will be used to make the requests to the financial profile endpoints.

Request:

Copy
Copied
curl -L -X POST 'https://api.yapily.com/users' \
-H 'Content-Type: application/json' \
-u 'APPLICATION_KEY:APPLICATION_SECRET' \
-d '{
    "applicationUserId": "user_0.8327278427722762",
    "referenceId": "USER_REFERENCE"
}'

Response:

Copy
Copied
{
    "applicationUserId": "user_0.8327278427722762",
    "referenceId": "USER_REFERENCE",
    "institutionConsents": [],
    "uuid": "6decd40f-fb72-445f-96c1-b52aff1f55d8",
    "applicationUuid": "3f11f634-97b0-4025-8086-2b3292509a7b"
}
  • The value of uuid is the userUuid which will be used in subsequent requests.

2. Generate an authorisation URL

Through our application user interface, we allow the PSU to select their bank account from a list of Yapily supported institutions. In the case of this tutorial, the PSU has selected the Yapily Mock Bank (institution-id = mock-sandbox). Following this, we are able to pass the institutionId and userUuid through to the request to generate an account authorisation URL, which will be used to direct the PSU to their chosen bank and authorise the accounts request.

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 '{
	"userUuid": "6decd40f-fb72-445f-96c1-b52aff1f55d8",
	"institutionId": "mock-sandbox",
	"callback": "https://display-parameters.herokuapp.com/",
	"accountRequest": {
		"featureScope": [
            "ACCOUNTS",
            "ACCOUNT",
            "ACCOUNT_TRANSACTIONS"
        ]
	}
}'

Response:

Copy
Copied
{
    "meta": {
        "tracingId": "429959dedb1e154da19afcde09166da7"
    },
    "data": {
        "id": "abda605f-ac46-4de3-ab05-bbe47eb1b615",
        "userUuid": "6decd40f-fb72-445f-96c1-b52aff1f55d8",
        "applicationUserId": "user_0.8327278427722762",
        "referenceId": "AAC_a12076ca-2167-4e32-8939-0d3c21da9472",
        "institutionId": "mock-sandbox",
        "status": "AWAITING_AUTHORIZATION",
        "createdAt": "2021-03-29T07:54:01.892Z",
        "transactionFrom": "2020-12-29T07:54:01.892Z",
        "transactionTo": "2024-03-29T07:54:01.892Z",
        "expiresAt": "2021-06-29T07:54:01.892Z",
        "featureScope": [
            "ACCOUNT",
            "ACCOUNTS",
            "ACCOUNT_TRANSACTIONS"
        ],
        "institutionConsentId": "AAC_a12076ca-2167-4e32-8939-0d3c21da9472",
        "state": "pp23fcbb-54c2-4cb7-8bf7-e38303a2f804",
        "authorisationUrl": "https://uk.mock.master.p2.yapily.com/oauth2/authorize?client_id=3fc339ca-6338-4f43-9e1c-bafc4362041c&response_type=code+id_token&state=pp23fcbb-54c2-4cb7-8bf7-e38303a2f804&redirect_uri=https%3A%2F%2Fauth.yapily.com%2F&scope=accounts+openid&request=eyJraWQiOiJlcGwyT09Mem82WHlCWExDeFR4dUZ6SnJEQ0kiLCJhbGciOiJQUzI1NiJ9.eyJhdWQiOiJodHRwczpcL1wvdWsubW9jay5tYXN0ZXIucDIueWFwaWx5LmNvbVwvb2F1dGgyIiwic2NvcGUiOiJhY2NvdW50cyBvcGVuaWQiLCJpc3MiOiIzZmMzMzljYS02MzM4LTRmNDMtOWUxYy1iYWZjNDM2MjA0MWMiLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsiYWNyIjp7InZhbHVlIjoidXJuOm9wZW5iYW5raW5nOnBzZDI6c2NhIiwiZXNzZW50aWFsIjp0cnVlfSwib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoiQUFDX2ExMjA3NmNhLTIxNjctNGUzMi04OTM5LTBkM2MyMWRhOTQ3MiIsImVzc2VudGlhbCI6dHJ1ZX19LCJ1c2VyaW5mbyI6eyJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiJBQUNfYTEyMDc2Y2EtMjE2Ny00ZTMyLTg5MzktMGQzYzIxZGE5NDcyIiwiZXNzZW50aWFsIjp0cnVlfX19LCJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOlwvXC9hdXRoLnlhcGlseS5jb21cLyIsInN0YXRlIjoicHAyM2ZjYmItNTRjMi00Y2I3LThiZjctZTM4MzAzYTJmODA0IiwiZXhwIjoxNjE3MDE0OTM2LCJub25jZSI6InBwMjNmY2JiLTU0YzItNGNiNy04YmY3LWUzODMwM2EyZjgwNCIsImNsaWVudF9pZCI6IjNmYzMzOWNhLTYzMzgtNGY0My05ZTFjLWJhZmM0MzYyMDQxYyJ9.IcHiuqjcrPZEXy77IkJrsCMR_hSI7rCulUZlSh0CoQCS-TUAebSk3kjGDXuNR94Snkk1q2z7tOYaW_iu3_DSpqUCRxhGzhN__V72j9Cteb0Cry4G7DwyHIXEteQI3f4yac57odaekf_4vrSLMS6U6sJDovUk3P6C8Bix28x9gRvsGWkoPgRg1NqfYtcktQS-QDonGKFuIvd49MUk2LHeEZDrK-bvl-rWWAezvgLj3vVTpFzcmSNI_SJPnzG56g4ar8Yp2ZJy17bWueDx1sVzmX8fuPDOCDgcbrVTby6otrGPriiL_UkveTesdLmXLt4jupGAuvgmFfbfZhigxsln2Q&nonce=pp23fcbb-54c2-4cb7-8bf7-e38303a2f804",
        "qrCodeUrl": "https://images.yapily.com/image/b574c682-1041-4f11-9d54-84ad1235fe70/consent-auth-url.png?size=0"
    }
}
  • id is the consent id for the consent. This value will be needed in subsequent requests.
  • The response includes the authorisationUrl and qrCodeUrl , one of which should be used to direct the PSU to their bank.
  • The PSU will be asked to login and authorise the payment with their bank.
  • Upon completion, the PSU will be redirected back to the callback url supplied in the request. In our example we are using https://display-parameters.herokuapp.com/ , which will display the parameters returned with the redirect.

3. Get the consent token

After the PSU has provided their consent and we have received the redirect, we can retrieve the consent token by making a request to the consents endpoint, using the id returned by the account authorisation response obtained above.

Request:

Copy
Copied
curl -L -X GET 'https://api.yapily.com/consents/abda605f-ac46-4de3-ab05-bbe47eb1b615' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'
  • The consent has a status of "AUTHORISED", indicating that the PSU was able to successfully authorise their account.

4. Create a profile consent

After retrieving the consentToken from the consents response above, we can use this to create a profile consent for the user.

Request:

Copy
Copied
curl -L -X POST 'https://api.yapily.com/users/6decd40f-fb72-445f-96c1-b52aff1f55d8/profile/consents' \
-H 'Consent: {consentToken}' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'

**Response:**

````json
{
    "id": "04fdef75-5da0-4a36-b210-57f743d3cd06",
    "referenceConsentId": "abda605f-ac46-4de3-ab05-bbe47eb1b615",
    "userId": "6decd40f-fb72-445f-96c1-b52aff1f55d8",
    "status": "PENDING",
    "institutionId": "mock-sandbox"
}
  • The initial status of a profile consent will be PENDING , indicating that a profile consent has been created but the financial data associated with that consent has not yet been retrieved. The requests to retrieve the financial data for a profile consent will be handled by Yapily behind the scenes asynchronously.
  • If the PSU holds multiple accounts, repeat Steps 2-4 for as many accounts as the PSU holds. In the case of this tutorial, the PSU holds only one account, so we will progress to step 5.

5. Get the financial profile

Finally, we can retrieve the financial profile for the user by making the following request:

Request:

Copy
Copied
curl -L -X GET 'https://api.yapily.com/users/6decd40f-fb72-445f-96c1-b52aff1f55d8/profile' \
-u 'APPLICATION_KEY:APPLICATION_SECRET'

Response:

Copy
Copied
{
    "status": "COMPLETED",
    "profileConsents": [
        {
            "id": "04fdef75-5da0-4a36-b210-57f743d3cd06",
            "referenceConsentId": "abda605f-ac46-4de3-ab05-bbe47eb1b615",
            "userId": "6decd40f-fb72-445f-96c1-b52aff1f55d8",
            "status": "COMPLETED",
            "institutionId": "mock-sandbox"
        }
    ],
    "enrichment": {
        "transactionStreams": [
            {
                "name": "Cash from Austin Dieter I.",
                "transactions": [
                    {
                        "transactionId": "92b8ed95-a3fb-4946-8ea9-deda160f961a",
                        "transactionInformation": "Cash from Austin, Dieter I.",
                        "institution": "mock-sandbox",
                        "bookingDateTime": "2020-02-04T20:51:58.376Z",
                        "amount": 489.29
                    },
                    {
                        "transactionId": "29000d02-e028-4ec3-9065-a385d41c1030",
                        "transactionInformation": "Cash from Austin, Dieter I.",
                        "institution": "mock-sandbox",
                        "bookingDateTime": "2020-03-14T22:49:49.160Z",
                        "amount": 485.86
                    },
                    {
                        "transactionId": "5c1287bb-e9ec-4a3c-923e-686578c9c22e",
                        "transactionInformation": "Cash from Austin, Dieter I.",
                        "institution": "mock-sandbox",
                        "bookingDateTime": "2020-02-23T22:53:21.160Z",
                        "amount": 294.6
                    },
                    {
                        "transactionId": "37acfb4e-cbaf-4aa4-9447-23576dc1482a",
                        "transactionInformation": "Cash from Austin, Dieter I.",
                        "institution": "mock-sandbox",
                        "bookingDateTime": "2020-02-14T11:04:01.160Z",
                        "amount": 353.79
                    }
                ],
                "transactionSchedule": {
                    "frequency": "Weekly",
                    "detailedFrequency": "Weekly on day n",
                    "detailedFrequencyParameter": 5
                },
                "scheduleConsistencyScore": 0.11,
                "mostRecentTransactionDate": "2020-02-14",
                "earliestTransactionDate": "2020-02-04",
                "nextExpectedTransactionDate": "2020-02-15",
                "averageAmount": 405.885,
                "amountConsistencyScore": 0.79
            }, 
            {...}     
        ]
    }
}
  • profileConsents lists all the profile consents which were used to generate the financial profile.
  • enrichment.transactionStreams lists all the transaction streams which were identified for the user. transactionSchedule provides more details about the predicted frequency of each transaction stream.
  • Before retrieving a financial profile, all profile consents associated with the user must have a status of COMPLETED . This could take several minutes after creating the profile consent, depending on the amount of financial data available.

Congratulations! You've just retrieved a Financial Profile via Yapily.

Related Tutorials