action field that specifies the associated value of created, updated, or deleted.
The X-CALLBACK-PAYLOAD header will appear if it was set in the Create Member or Update Member Platform API request that initiated this webhook.
| Field | Data Type | Definition |
|---|---|---|
aggregated_at | Integer | The date and time when the most recent aggregation process was started. The process automatically starts when a member is created or its credentials are updated, unless the skip_aggregation parameter is used. Connections can also be started via manual aggregations, background aggregations, API endpoints, or when opening an MX widget. It can be a normal aggregation, or a different process such as identification, verification, fetching statements, or fetching an extended transaction history. If a member is deleted and then re-created with the skip_aggregation parameter set to true, or if it is re-created within the throttle window (typically three hours), the previous value will be returned. |
connection_status_id | Integer | The state of a member’s aggregation, provided as an integer. See member connection statuses for more information on possible values. |
connection_status_message | String | A message that can be displayed to the user to help them navigate the connection and aggregation process. |
connection_status | String | The state of a member’s aggregation, provided as a string. See member connection statuses for more information on possible values. |
created_at | Integer | The date and time when the member was created. |
guid | String | The unique identifier for the member. Defined by MX. |
id | String | The unique partner-defined identifier for the member. |
institution_code | String | The unique identifier for the institution associated with the member. Defined by MX. |
institution_guid | String | The unique identifier for the institution the member belongs to. Defined by MX. |
is_being_aggregated | Boolean | Whether the member is being aggregated at the time of the request. |
is_managed_by_user | Boolean | Whether the member is managed by the user. |
is_manual | Boolean | Whether the member was manually created. |
is_oauth | Boolean | Whether the member uses OAuth to authenticate. Defaults to false. |
is_user_created | Boolean | This field is deprecated. Use is_managed_by_user instead. |
metadata | String | Additional information a partner can store on the member. |
most_recent_job_guid | String | The unique identifier for the most recent job. Defined by MX. |
name | String | The name of the given member. |
needs_updated_credentials | Boolean | Whether MX needs to update the member’s credentials. |
revision | Integer | The revision number of this member record. |
successfully_aggregated_at | Integer | The date and time when the account was last successfully aggregated. |
updated_at | Integer | The date and time when the member was last updated. |
use_cases | Array | The use case associated with the member. Valid values are PFM and MONEY_MOVEMENT. To use this field, you must have met with MX and opted into using this field. For more info, see Member Use Cases. |
user_id | String | The unique partner-defined identifier for the user. |
JSON
POST /admin/webhooks
HTTP/1.1
content-type: application/json; charset=utf-8
accept: application/json
User-Agent: HTTPClient/1.0 (2.7.1, ruby 2.2.2
(2015-09-02)) Date: Thu, 12 Jul 2017 04:26:04 GMT Content-Length: 231
Host: abc.com
{
"action": "updated",
"member": {
"aggregated_at": 1588007604,
"connection_status": "CONNECTED",
"connection_status_id": 6,
"connection_status_message": "Connected to Gringotts.",
"created_at": 1558116397,
"guid": "MBR-8a4bdc76-2b77-46f8-9e30-39f120e15bfe",
"institution_code": "gringotts",
"institution_guid": "INS-80230e9b-bfc3-d488-e606-1bf82f862406",
"id": null,
"is_being_aggregated": false,
"is_manual": false,
"is_managed_by_user": true,
"is_oauth": false,
"is_user_created": true,
"metadata": null,
"most_recent_job_guid": "JOB-5ce1788a-3f63-44b9-8642-d015b38b41c0",
"name": "Gringotts",
"needs_updated_credentials": false,
"successfully_aggregated_at": 1588007610,
"user_id": "u-1234567",
"revision": 5097,
"updated_at": 1588007610,
"use_cases": ["PFM"],
"user_guid": "USR-98bdfe3883-2b77-46f8-9e30-39f120e15bfe"
}
}
Member Connection Statuses
| Integer Value | Status | Definition | Next Steps | End-User Message |
|---|---|---|---|---|
| null | null | The member exists but does not have credentials. A member that does not aggregate (e.g., a manual member) will always have this status. | None. | None. |
| 0 | CREATED | The member is new and has not yet been aggregated. | Aggregate the member once the end user logs in; poll for a status update. | Connecting to […] … |
| 1 | PREVENTED | MX is preventing aggregation until the member’s credentials have been updated. | Display end-user message; after end user has updated their credentials, aggregate again. | The last 3 attempts to connect have failed. Please re-enter your credentials to continue importing data. |
| 2 | DENIED | The credentials provided for the member were invalid. | Display end-user message; after end user has updated their credentials, aggregate again. | The credentials entered do not match your credentials at this institution. Please re-enter your credentials to continue importing data. |
| 3 | CHALLENGED | The member has been challenged by multi-factor authentication. | Display end-user message; follow MFA pathway; after the user answers MFA, poll for a status update. | To authenticate your connection to […], please answer the following challenge(s). |
| 4 | REJECTED | An MFA challenge was answered incorrectly. | Display end-user message; another challenge may follow or aggregation may need to be restarted. | The answer or answers provided were incorrect. Please try again. |
| 5 | LOCKED | The financial institution is preventing authentication. The end user must contact the financial institution. | Display end-user message. | Your account is locked. Please log in to the appropriate website for […] and follow the steps to resolve the issue. |
| 6 | CONNECTED | The member was successfully authenticated and data is now aggregating. | Display the account as having been connected. | Connected to […] … |
| 7 | IMPEDED | The end user’s attention is required at their online banking institution, e.g., there is a marketing message that must be viewed, terms and conditions that must be accepted, etc. | Display end-user message. | Your attention is needed at this institution’s website. Please log in to the appropriate website for […] and follow the steps to resolve the issue. |
| 8 | RECONNECTED | The member has been migrated to a new data source and aggregation is likely to trigger one-time password MFA. MX will not perform background aggregation in order to avoid unnecessarily disruptive texts, emails, etc. The member must be re-aggregated in the foreground with the end user present. | Aggregate the member once the end user logs in; poll for a status update. | Reconnecting to […] … |
| 9 | DEGRADED | Aggregation has failed at least three times within a short period of time. | Display end-user message. | We are upgrading this connection. Please try again later. |
| 10 | DISCONNECTED | Aggregation has failed at least three times and has not succeeded for at least two weeks. | Display end-user message. | It looks like your data from […] cannot be imported. We are working to resolve the issue. |
| 11 | DISCONTINUED | The connection to this financial institution is no longer available. | Display end-user message. | Connections to this institution are no longer supported. You may create a manual account and use manual transactions to track data for this account. |
| 12 | CLOSED | The end user, MX, the client, or a partner has marked the member as closed. | Display end-user message. | This connection has been closed. You may track this account manually. If reopened, you may connect the institution again. |
| 13 | DELAYED | Aggregating the member has taken longer than expected and it has not yet been connected. | Display end-user message; poll for a status update. | Importing your data from […] may take a while. Please check back later. |
| 14 | FAILED | Aggregation failed without being connected. | Display end-user message; try aggregating again later. | There was a problem validating your credentials with […]. Please try again later. |
| 15 | UPDATED | The member has been updated — i.e., credentials have been updated — but it has not yet been connected. | Aggregate the member once the end user logs in; poll for a status update. | Connecting to […] … |
| 16 | DISABLED | Aggregation has been momentarily paused, but the member is still connected. | Display end-user message. | Importing data from this institution has been disabled. Please contact us if you believe it has been disabled in error. |
| 17 | IMPORTED | MX does not have credentials and will not try to aggregate the member until the end user provides credentials. | Display end-user message; re-aggregate after the end user updates credentials. | You must re-authenticate before your data can be imported. Please enter your credentials for […]. |
| 18 | RESUMED | The answer to an MFA challenge was received, but it is not yet clear whether it was correct. | Poll for a status update. | Connecting to […] … |
| 19 | EXPIRED | The MFA answer was not provided within the time allotted by the financial institution. | Display end-user message; re-aggregate the member if the end user initiates it. | The answer or answers were not provided in time. Please try again. |
| 20 | IMPAIRED | The member is missing some or all credentials needed in order to connect. | Display end-user message; re-aggregate after the end user updates credentials. | You must re-authenticate before your data can be imported. Please enter your credentials for […]. |
| 21 | PENDING | The member is using OAuth to authenticate credentials and still needs to go through the financial institution’s OAuth process. A PENDING status will appear only on members less than one hour old with is_oauth: true. Members that stay PENDING longer than one hour will be deleted by MX. | Redirect the end user to the oauth_window_uri provided in the create member response, or request one through the generate OAuth window URI endpoint. | None. |
Member Data Updated
Member data updated webhooks notify you new transaction data is available for the member. It will include a count of new transactions and of updated transactions. This webhook fires only after a completed aggregation event; changes made directly using MX APIs (such as creating or modifying a transaction via Nexus, MDX Real Time, or Batch) will not trigger the webhook. TheX-CALLBACK-PAYLOAD header will appear if it was set in the Aggregate Member or Verify Member Platform API request that initiated this webhook.
| Field | Data Type | Description |
|---|---|---|
action | String | This field should always equal member_data_updated. |
completed_at | Integer | The time at which the aggregation that triggered the webhook was finished. |
completed_on | String | The date on which the aggregation that triggered the webhook was finished. |
is_background | Boolean | This indicates whether the aggregation was performed manually in the foreground or automatically in the background. |
job_guid | String | The unique identifier for the job. Defined by MX. |
member_guid | String | The unique identifier for the member which has new or updated transaction data. Defined by MX. |
transactions_created_count | Integer | The number of newly created transactions. |
transactions_updated_count | Integer | The number of newly updated transactions. |
type | String | The type of webhook being delivered. |
user_guid | String | The unique identifier for the user with which the data is associated. Defined by MX. |
user_id | String | The unique partner-defined identifier for the user associated with the aggregation. |
JSON
{
"action": "member_data_updated",
"completed_at": 1531947410,
"completed_on": "2018-07-18",
"is_background": true,
"job_guid": "JOB-823ab268-5107-4a67-97c8-60292572ac2e",
"member_guid": "MBR-48d9a481-f2a2-7e13-2685-62869cf0d33a",
"transactions_created_count": 3,
"transactions_updated_count": 2,
"type": "AGGREGATION",
"user_guid": "USR-eaf4ac68-d17d-5e9b-7b46-959a5b315a9e",
"user_id": "partner-defined-id"
}