Aggregation Support

Finicity's Aggregation Support resource includes services for escalating and managing aggregation support tickets, and for submitting Additional Authentication Information if required to resolve a ticket.

See Handling Aggregation Status Codes to understand the process for escalating an aggregation error.

Aggregations Support Ticket Flow Explained (With Diagram)

See Active Docs to experiment directly with the API.

Available services:

Aggregation Support Ticket

The following fields are available in a ticket record:

Field Name Description

id

The ticket ID
status One of the values: new, inprocess, additionalLoginInfoRequired, additionalLoginInfoSubmitted, escalated, reopened, closed, invalid
createdDate The date the ticket was created
resolutionDate An estimated date when the ticket will be resolved
accountIds The accounts belonging to this customer that were included in this ticket
institutionId The Finicity ID of the institution for this account

Testing Aggregation Support

Aggregation Support services may be tested using Testing Accounts on the FinBank institutions. The following steps will create a testing account with a failing status code, which can then be used in a call to Escalate Aggregation Error:

  1. Call Get Institution Login Form to get the loginForm for FinBank (institution ID 101732)
  2. Call Discover Customer Accounts with username demo and password go. (Do not pass an error code as the password here, as that will cause discovery itself to fail before the account is created.)
  3. Call Activate Customer Accounts v2 (without Aggregation) to activate the desired accounts.
  4. Call Modify Customer Account Credentials to change the username and password to demo123 (or 125, 127, 128, or 130) to tell the account to fail with the designated error code (see the list of credentials in Testing Accounts).
  5. Call Refresh Customer Account to perform the aggregation, which will fail with the designated error code.

The failing account can now be submitted to the service Escalate Aggregation Error. Note that the Finicity support team will ignore any tickets submitted on the FinBank institutions.

Escalate Aggregation Error

POST /v1/customers/{customerId}/institutions/{institutionId}/accounts/{accountId}/tickets

Open a high-priority support ticket for an account failing with a non-zero aggregationStatusCode. An escalated ticket can be tracked by clicking Help > View Support Tickets inside the Developer Portal.

Escalation is reserved for cases where a live customer is actually waiting for an issue to be resolved! We strive to fix all known issues within a reasonable amount of time, including those issues that have not been escalated through this service. If you flood the system by escalating issues that customers are not waiting for, you will in fact degrade the experience for your customers who are actually waiting for an issue to be resolved.

JSON Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Content-Type HTTP header application/json
Accept HTTP header

application/json

customerId path

The ID of the customer who owns the account

institutionId path

The Finicity ID of the institution for this account

accountId path

The Finicity ID of the account to be modified

aggregationStatusCode JSON field

The error code being reported

specialInstructions JSON field

More information that will help Finicity resolve the error (optional). CAUTION: Do not send sensitive information (such as passwords or credit card numbers) in this field!

Success: HTTP 200 (OK)

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/2055
{
"aggregationStatusCode": ERROR_CODE,
"specialInstructions": "SPECIAL_INSTRUCTIONS"
}

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/json" -H "Accept:application/json" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055" -d '{ "aggregationStatusCode": ERROR_CODE, "specialInstructions": "SPECIAL_INSTRUCTIONS" }'

Response Details:

A single aggregation support ticket.

Example Response:

{
"id": "8734",
"status": "new",
"createdDate": "1422395818",
"resolutionDate": "1471327200",
"institutionId": "101732",
"accountIds": [
"2055"
]
}

XML Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Content-Type HTTP header application/xml
Accept HTTP header

application/xml

customerId path

The ID of the customer who owns the account

institutionId path

The Finicity ID of the institution for this account

accountId path

The Finicity ID of the account to be modified

ticket XML element

Root element

aggregationStatusCode XML element

The error code being reported

specialInstructions XML element

More information that will help Finicity resolve the error (optional). CAUTION: Do not send sensitive information (such as passwords or credit card numbers) in this field!

Success: HTTP 200 (OK)

Example Request:

POST https://api.finicity.com/aggregation/v1/customers/41442/institutions/101732/accounts/2055
<ticket>
<aggregationStatusCode>ERROR_CODE</aggregationStatusCode>
</ticket>

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -H "Accept:application/xml" -X POST "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055" -d '<ticket> <aggregationStatusCode>ERROR_CODE</aggregationStatusCode> </ticket>'

Response Details:

XML Name Description
ticket An aggregation support ticket

Example Response:

<ticket>
  <id>8734</id>
  <status>new</status>
  <accountIds><accountId>2055</accountId></accountIds>
  <institutionId>101732</institutionId>
  <createdDate>1422395818</createdDate>
<resolutionDate>1422578197</resolutionDate> </ticket>

Get Aggregation Support Tickets for Customer

GET /v1/customers/{customerId}/tickets

Get all aggregation support tickets for the specified customer.

JSON Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header

application/json

customerId path

The ID of the customer whose tickets are to be retrieved

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/tickets

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -X GET "https://api.finicity.com/aggregation/v1/customers/41442/tickets"

Response Details:

A list of aggregation support tickets

Example Response:

{ [
{
"id": "8734",
"status": "escalated",
"createdDate": "1422395818",
"resolutionDate": "1471327200",
"institutionId": "101732",
"accountIds": [
"2055"
]
},
  {
"id": "9261",
"status": "closed",
"createdDate": "1422395818",
"resolutionDate": "1471327200",
"institutionId": "101732",
"accountIds": [
"2055"
]
}
]
}

XML Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header

application/xml

customerId path

The ID of the customer whose tickets are to be retrieved

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/tickets

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/xml" -X GET "https://api.finicity.com/aggregation/v1/customers/41442/tickets"

Response Details:

XML Name Description
tickets Root element
ticket An aggregation support ticket

Example Response:

<tickets>
<ticket>
<id>8734</id>
<status>escalated</status>
<accountIds>
<accountId>2055</accountId>
</accountIds>
<institutionId>101732</institutionId>
<createdDate>1422395818</createdDate>
</ticket> <ticket>
<id>9261</id>
<status>closed</status>
<accountIds>
<accountId>2055</accountId>
  <accountId>3921</accountId>
</accountIds>
<institutionId>101732</institutionId>
<createdDate>1422395818</createdDate>
<resolutionDate>1422396929</resolutionDate>
</ticket>
</tickets>

Get Aggregation Support Tickets for Account
GET /v1/customers/{customerId}/accounts/{accountId}/tickets

Get all aggregation support tickets for the specified customer account.

JSON Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header

application/json

customerId path

The ID of the customer whose tickets are to be retrieved

accountId path

The Finicity ID of the account whose tickets are to be retrieved

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/tickets

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -X GET "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/tickets"

Response Details:

A list of aggregation support tickets

Example Response:

{ [
{
"id": "8734",
"status": "escalated",
"createdDate": "1422395818",
"resolutionDate": "1471327200",
"institutionId": "101732",
"accountIds": [
"2055"
]
},
{
"id": "9261",
"status": "closed",
"createdDate": "1422395818",
"resolutionDate": "1471327200",
"institutionId": "101732",
"accountIds": [
"2055"
]
}
]
}

XML Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header

application/xml

customerId path

The ID of the customer whose tickets are to be retrieved

accountId path

The Finicity ID of the account whose tickets are to be retrieved

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/tickets

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/xml" -X GET "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055/tickets"

Response Details:

XML Name Description
tickets Root element
ticket An aggregation support ticket

Example Response:

<tickets>
<ticket>
<id>8734</id>
<status>escalated</status>
<accountIds>
<accountId>2055</accountId>
</accountIds>
<institutionId>101732</institutionId>
<createdDate>1422395818</createdDate>
</ticket> <ticket>
<id>9261</id>
<status>closed</status>
<accountIds>
<accountId>2055</accountId>
  <accountId>3921</accountId>
</accountIds>
<institutionId>101732</institutionId>
<createdDate>1422395818</createdDate>
<resolutionDate>1422396929</resolutionDate>
</ticket>
</tickets>

Get Aggregation Support Ticket
GET /v1/customers/{customerId}/tickets/{ticketId}

Get all aggregation support tickets for the specified customer account.

JSON Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header

application/json

customerId path

The ID of the customer whose tickets are to be retrieved

ticketId path

The ID of the ticket

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/tickets/8734

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/json" -X GET "https://api.finicity.com/aggregation/v1/customers/41442/tickets/8734"

Response Details:

A single aggregation support ticket.

Example Response:

{
"id": "8734",
"status": "new",
"createdDate": "1422395818",
"resolutionDate": "1471327200",
"institutionId": "101732",
"accountIds": [
"2055"
]
}

XML Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Accept HTTP header

application/xml

customerId path

The ID of the customer whose tickets are to be retrieved

ticketId path

The ID of the ticket

Success: HTTP 200 (OK)

Example Request:

GET https://api.finicity.com/aggregation/v1/customers/41442/tickets/8734

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Accept:application/xml" -X GET "https://api.finicity.com/aggregation/v1/customers/41442/tickets/8734"

Response Details:

XML Name Description
ticket An aggregation support ticket

Example Response:

<ticket>
<id>8734</id>
<status>escalated</status>
<accountIds>
<accountId>2055</accountId>
</accountIds>
<institutionId>101732</institutionId>
<createdDate>1422395818</createdDate>
</ticket>

Submit Additional Authentication Information for Ticket

PUT /v1/customers/{customerId}/tickets/{ticketId}/aai

Submit all authentication information required for this ticket. This service should be invoked if a ticket shows the status additionalLoginInfoRequired. Follow these steps:

  1. Call Get Institution Login Form for the ticket's institution.
  2. Prompt the user for the proper value for each login field, and for any MFA questions or other special instructions that may be required to access this account.
  3. Call Submit Additional Authentication Information for Ticket to submit all of this information to Finicity in a secure manner.

JSON Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Content-Type HTTP header Must be application/json
customerId path

The ID of the customer who owns the account

ticketId path

The ID of the ticket requiring AAI information

credentials JSON field

A credentials record

mfaChallenges JSON field

An MFA Challenges segment

specialInstructions JSON field

More information that will help Finicity resolve the error (optional). CAUTION: Do not send sensitive information (such as passwords or credit card numbers) in this field!

Success: HTTP 204 (No Content)

Example Request:

PUT https://api.finicity.com/aggregation/v1/customers/tickets/8734/aai
{
"credentials": [
{
"id": FIELD_ID_1,
"name": "FIELD_NAME_1",
"value": "FIELD_VALUE_1"
},
{
"id": FIELD_ID_2,
"name": "FIELD_NAME_2",
"value": "FIELD_VALUE_2"
}
],
"mfaChallenges": [
{
  "text": "What was the last name of your favorite teacher?",
"answer": "MFA_ANSWER"
  },
{
"text": "Enter your first pet's name:",
"answer": "MFA_ANSWER"
}
],
"specialInstructions": "SPECIAL_INSTRUCTIONS"
}

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -X PUT "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055" -d '{ "credentials": [ { "id": FIELD_ID_1, "name": "FIELD_NAME_1", "value": "FIELD_VALUE_1" }, { "id": FIELD_ID_2, "name": "FIELD_NAME_2", "value": "FIELD_VALUE_2" } ], "mfaChallenges": [ { "text": "What was the last name of your favorite teacher?", "answer": "MFA_ANSWER" }, { "text": "Enter your first pet's name:", "answer": "MFA_ANSWER" } ], "specialInstructions": "SPECIAL_INSTRUCTIONS" }'

XML Implementation

Request Details: 

Parameter Type Description
Finicity-App-Key HTTP header Finicity-App-Key from Developer Portal
Finicity-App-Token HTTP header Token returned from Partner Authentication
Content-Type HTTP header application/xml
customerId path

The ID of the customer who owns the account

ticketId path

The ID of the ticket requiring AAI information

additionalAuthenticationInformation XML element

Root element

credentials XML element

A credentials record

mfaChallenges XML element

An MFA Challenges segment

specialInstructions XML element

More information that will help Finicity resolve the error (optional). CAUTION: Do not send sensitive information (such as passwords or credit card numbers) in this field!

Success: HTTP 204 (No Content)

Example Request:

PUT https://api.finicity.com/aggregation/v1/customers/tickets/8734/aai
<additionalAuthenticationInformation>
<credentials>
<loginField>
<id>FIELD_ID_1</id>
<name>FIELD_NAME_1</name>
<value>FIELD_VALUE_1</value>
</loginField>
<loginField>
<id>FIELD_ID_2</id>
<name>FIELD_NAME_2</name>
<value>FIELD_VALUE_2</value>
</loginField>
</credentials>
<mfaChallenges>
<questions>
<question>
  <text>What was the last name of your favorite teacher?</text>
  <answer>MFA_ANSWER</answer>
  </question>
    <question>
  <text>Enter your first pet's name:</text>
  <answer>MFA_ANSWER</answer>
</question>
</questions>
</mfaChallenges>
<specialInstructions>SPECIAL_INSTRUCTIONS</specialInstructions>
</additionalAuthenticationInformation>

Using curl:

curl -v -H "Finicity-App-Key:APP_KEY" -H "Finicity-App-Token:ACCESS_TOKEN" -H "Content-Type:application/xml" -X PUT "https://api.finicity.com/aggregation/v1/customers/41442/accounts/2055" -d '<additionalAuthenticationInformation> <credentials> <loginField> <id>FIELD_ID_1</id> <name>FIELD_NAME_1</name> <value>FIELD_VALUE_1</value> </loginField> <loginField> <id>FIELD_ID_2</id> <name>FIELD_NAME_2</name> <value>FIELD_VALUE_2</value> </loginField> </credentials> <mfaChallenges> <questions> <question> <text>What was the last name of your favorite teacher?</text> <answer>MFA_ANSWER</answer> </question> <question> <text>Enter your first pet's name:</text> <answer>MFA_ANSWER</answer> </question> </questions> </mfaChallenges> <specialInstructions>SPECIAL_INSTRUCTIONS</specialInstructions> </additionalAuthenticationInformation>'

 

 

Have more questions? Submit a request

Comments

Powered by Zendesk