Set up the Correct Attributes API Call

So everything is nearly set up, you only have a couple more API calls to make before you are fully ready to go to production! This section will guide you through the process of obtaining a new requestId, retrieving the most recent transactions at that time (/GetAccountsDetail) and using that requestId to call the ‘Attributes’ service.

Overview

In order to take advantage of enhanced data, there are a couple of steps that need to happen. To pull back data attributes, Flinks needs to analyze the most recent transactional data for the end user and convert this into easily ingestible insights.

Here is a step-by-step overview of this process:

1. Receive a new requestId — using the loginId stored for the end user, call the /Authorize endpoint with the parameter MostRecentCached:true
2. Using the requestId that is generated from this new /Authorize call, make a call to the /GetAccountsDetail endpoint to retrieve the most recent transaction history
3. Using this requestId, call the specific Attributes Endpoint to retrieve the required data.

📘

Note on Steps 1 + 2

These have been covered previously in the Make API Calls section — please refer to there for more information.

Assuming that you have the new session open and you have your end user’s most recent transaction history, you’re ready to call for Attributes.

Within your integration, you have a choice of 5 endpoint variations. We have Four (4) Use-Case Specific Endpoints and One (1) Custom Endpoint for Attributes. Please find information on each of the Endpoints below. (Further detailed information on the Attributes included in each endpoint is detailed in the 'List of Attributes Use-Cases' tab on the left hand side - so please refer to there if you don't already know which endpoint to call)

/GetIncomeAttributes

This endpoint returns a set of Income Verification Attributes, and should be used by clients that have the Income Verification Use-Case Package. The Attributes contained within this request cannot be customized. Please refer to the List of Attributes Use-Cases tab for the full list of Attributes returned in this endpoint.

Required Parameters:

• instance
• customerId
• loginId
• requestId

curl -X GET \
  https://{instance}-api.private.fin.ag/v3/{customerId}/insight/login/{loginId}/attributes/{requestId}/GetIncomeAttributes \

/GetCreditRiskAttributes

This endpoint returns a set of Credit Risk Attributes, and should be used by clients that have the Credit Risk Use-Case Package. The Attributes contained within this request cannot be customized. Please refer to the List of Attributes Use-Cases tab for the full list of Attributes returned in this endpoint.

Required Parameters:

• instance
• customerId
• loginId
• requestId

curl -X GET \
  https://{instance}-api.private.fin.ag/v3/{customerId}/insight/login/{loginId}/attributes/{requestId}/GetCreditRiskAttributes \

/GetUserAnalysisAttributes

This endpoint returns a set of User Analysis Attributes, and should be used by clients that have the User Analysis Use-Case Package. The Attributes contained within this request cannot be customized. Please refer to the List of Attributes Use-Cases tab for the full list of Attributes contained in this endpoint.

Required Parameters:

• instance
• customerId
• loginId
• requestId

curl -X GET \
  https://{instance}-api.private.fin.ag/v3/{customerId}/insight/login/{loginId}/attributes/{requestId}/GetUserAnalysisAttributes \

/GetLendingAttributes

This endpoint returns a set of Lending Attributes, and should be used by clients that have the Lending Use-Case Package. The Attributes contained within this request cannot be customized. Please refer to the List of Attributes Use-Cases tab for the full list of Attributes contained in this endpoint.

Required Parameters:

• instance
• customerId
• loginId
• requestId

curl -X GET \
  https://{instance}-api.private.fin.ag/v3/{customerId}/insight/login/{loginId}/attributes/{requestId}/GetLendingAttributes \

/GetAllAttributes

This endpoint returns all available Attributes that Flinks currently has available, this endpoint is restricted to only clients that have a Tier 2 Package and above. The Attributes contained within this request cannot be customized. Please refer to the List of Attributes Use-Cases tab for the full list of Attributes contained in this endpoint.

Required Parameters:

• instance
• customerId
• loginId
• requestId

curl -X GET \
  https://{instance}-api.private.fin.ag/v3/{customerId}/insight/login/{loginId}/attributes/{requestId}/GetAllAttributes \

/Attributes

This endpoint is the most customizable Attributes Endpoint. In order to call this Endpoint, you will need to know/include the names of Attributes within your request. This endpoint is used primarily by clients who have specific needs that fall outside of our Use-Case Endpoints.

Required Parameters:

• instance
• customerId
• loginId
• requestId

Required Fields:

• MostRecentCached
• Attributes*

You can also include these additional optional fields (Please refer to our reference for further details):

• Filters
• AccountFilter
• Options
• AttributesDetail

🚧

Note on Attributes Field*

If you are on a Tier 2 Package, and need to create a custom Attribute request, please reach out to our team for the full list of Attribute Names that you can include here, as needed for your custom use-case.

curl -X POST \
  https://toolbox-api.private.fin.ag/v3/{customerId}/insight/login/{loginId}/attributes/{requestId} \
  -H 'Content-Type: application/json' \
  -d '{
    "Attributes": {
        "Card": [
            "account_age_days",
            "balance_current",
            "balance_max",
            "balance_min",
            "count_nsf",
            "avg_monthly_deposit",
            "sum_employer_income"
        ]
    },
    "Filters": {
        "AccountCategory": [
            "Operations"
        ]
    },
    "Options": {
        "AttributesDetail": [
            "count_nsf",
            "sum_employer_income"
        ],
        "AccountFilter": [
      		"472c349a-3aed-4358-3563-08d7ccf7c1f7"
        ]
    },
    "MostRecentCached": true
}

{
  "Card": {
        "Id": "347fafd7-0aa6-4e2f-90b6-08d7750bf480",
        "account_age_days": 195,
        "balance_current": -86200.82,
        "balance_max": -65148.62,
        "balance_min": -91212.27,
        "count_nsf": 0,
        "avg_monthly_deposit": 30322.74,
        "sum_employer_income": 48700.74,
        "AttributesDetail": [
            {
                "Attribute": "sum_employer_income",
                "Transactions": [
                    {
                        "TransactionId": "31ca0d0e-4ce5-4e49-82d3-9a5698d86a7b",
                        "AccountId": "911807a7-72b6-431d-381a-08d792dc3bfc",
                        "Date": "2020/02/13",
                        "Description": "PAYROLL deposit - Flinks Technologies",
                        "Debit": 0.00,
                        "Credit": 9338.32
                    }
                ]
            }
        ]
    },
    "Login": {
        "Username": "Attributes_1",
        "IsScheduledRefresh": false,
        "LastRefresh": "2020-03-12T16:54:51.7558369",
        "Type": "Personal",
        "Id": "347fafd7-0aa6-4e2f-90b6-08d7750bf480"
    },
    "RequestId": "fb4f2c83-b4c0-43e4-82f5-844a3594a9cb"
}

Once the Attributes engine is done processing the transactional data, the API will respond with a HTTP 200 and a JSON payload containing all the requested data attributes (per the requested use-case) in a standard format. Your app server should be ready to start handling them according to your use case.

👍

Before moving on, let's review what we just did:

• Received a new requestId with incoming loginId by calling /Authorize with MostRecentCached:true

• Requested ready-to-deliver data with /GetAccountsDetail and handle 202 OPERATION_PENDING responses

• Set up the call to the required /Attributes endpoint and started receiving data attributes