Create member

curl --request POST \
  --url https://int-data.moneydesktop.com/members \
  --header 'Content-Type: application/vnd.mx.nexus.v1+json' \
  --header 'MD-SESSION-TOKEN: <api-key>' \
  --data '{}'

{
  "member": {
    "aggregated_at": "2016-10-13T18:07:57.000Z",
    "background_aggregation_is_disabled": false,
    "connection_status": "CONNECTED",
    "external_guid": null,
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "institution_code": "chase",
    "institution_guid": "INS-1572a04c-912b-59bf-5841-332c7dfafaef",
    "is_being_aggregated": false,
    "is_managed_by_user": false,
    "is_oauth": false,
    "is_user_created": true,
    "most_recent_job_guid": "JOB-d6bb804b-6d12-44f1-b0ad-403441c03372",
    "metadata": "\\\"credentials_last_refreshed_at\\\": \\\"2015-10-15\\\"",
    "name": "Chase Bank",
    "successfully_aggregated_at": "2016-10-13T17:57:38.000Z",
    "use_cases": [
      "PFM"
    ],
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

POST

members

Create member

curl --request POST \
  --url https://int-data.moneydesktop.com/members \
  --header 'Content-Type: application/vnd.mx.nexus.v1+json' \
  --header 'MD-SESSION-TOKEN: <api-key>' \
  --data '{}'

{
  "member": {
    "aggregated_at": "2016-10-13T18:07:57.000Z",
    "background_aggregation_is_disabled": false,
    "connection_status": "CONNECTED",
    "external_guid": null,
    "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
    "institution_code": "chase",
    "institution_guid": "INS-1572a04c-912b-59bf-5841-332c7dfafaef",
    "is_being_aggregated": false,
    "is_managed_by_user": false,
    "is_oauth": false,
    "is_user_created": true,
    "most_recent_job_guid": "JOB-d6bb804b-6d12-44f1-b0ad-403441c03372",
    "metadata": "\\\"credentials_last_refreshed_at\\\": \\\"2015-10-15\\\"",
    "name": "Chase Bank",
    "successfully_aggregated_at": "2016-10-13T17:57:38.000Z",
    "use_cases": [
      "PFM"
    ],
    "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
  }
}

This endpoint allows you to create a new member. Standard members are created with the required parameters credentials and institution_guid. When creating a standard member, you’ll need to include the correct type of credential required by the financial institution, with values provided by the end user. You can find out which credential type is required with the read institution credentials endpoint.

Once you successfully create a standard member, MX will immediately validate the provided credentials and attempt to aggregate data for accounts and transactions. You can prevent this automatic aggregation by setting the skip_aggregation parameter to true. OAuth members can only be created with institutions that support it. OAuth members require no credentials, but do require you to set the is_oauth parameter to true. OAuth members will be created with a connection status of PENDING; a one-time use redirect URI will be provided in the oauth_window_uri field of the response. Making a separate request to the oauth_window_uri will then take the end user to the registered OAuth application where they can provide credentials and choose what data to share with MX.

After completing the OAuth process, aggregation will automatically begin and the connection status will be updated, unless the skip_aggregation parameter was set to true. Partners should not add multiple members to a user if they are connecting to the same institution using the same credentials. This is not supported by many data providers and will result in undefined behavior. This restriction also applies to OAuth members. In addition, it is important to note that the name field is rarely necessary in a member create request. The preferred option is to omit the field and use the default name, i.e. the name of the institution set up by an MX Integration Engineer.

Only in rare circumstances would the name field be supplied in a member create request, and it should not be used unless you have discussed it with a MX Integration Engineer. This endpoint accepts the optional MX-Skip-Webhook header and skip_webhook parameter.

Authorizations

MD-SESSION-TOKEN

string

header

required

MX Session Token

Request an API token using the read API token endpoint in the MX SSO API.
Exchange an API token for a session token.
- A session token is obtained by sending a POST request to /sessions
- The session token will be used in each request made for the user. It should be passed in an MD-SESSION-TOKEN HTTP header as shown below.
- This session token is valid for 30 minutes from the time it was created. The 30 minute expiration counter is refreshed with each call.
- If you send a request with an expired session token you'll receive an error code of 4011.

curl -i https://int-data.moneydesktop.com/accounts \
-H 'MD-SESSION-TOKEN: CWforZl1Vn2vC_v6H4rnQRT1DoWpDouJAV-_5TBmiQRAtA8rsOG_BoajTiOSsL0A3bd-bmHXlA-eQzc9ywItKg' \
-H 'Content-Type: application/vnd.mx.nexus.v1+json' \
-H 'Accept: application/vnd.mx.nexus.v1+json'

In documentation code examples, replace <API_KEY_VALUE> with the session token.

Body

application/vnd.mx.nexus.v1+json

The parameters to create a member.

member

object

Hide child attributes

member.institution_guid

string

required

Unique identifier for the institution. Defined by MX.

Example:

"INS-1572a04c-912b-59bf-5841-332c7dfafaef"

member.background_aggregation_is_disabled

boolean

This field indicates whether background aggregation is disabled for the member.

Example:

false

member.credentials

object[]

Required unless is_oauth is true.

Hide child attributes

member.credentials.credential_guid

string

The unique identifier for the institution credential. Obtained from the institution required credentials endpoint.

Example:

"CRD-18cd14ce-2628-5eb6-ae17-b11f89d0b667"

member.credentials.value

string

The user-provided value for this credential field (e.g., username, password, security answer).

Example:

"user-entered-value"

member.client_redirect_url

string

The URL to redirect the user to after completing OAuth authentication.

Example:

null

member.connection_status

string

Can only be set if the member is under a test institution. Attempting to set this on a member of a non-test institution will result in a 400. When present, the value must be one of the member connection status strings. If credentials are also set, any value for connection_status will be ignored as updating credentials automatically triggers an aggregation job, which will automatically update the connection status.

Example:

null

member.external_guid

string

Partner created identifier for the member. It must be unique for all members belonging to all users within the client.

Example:

null

member.is_oauth

boolean

This indicates whether the member uses OAuth to authenticate the member. Defaults to false. authentication.

Example:

false

member.referral_source

string

The source from which the member creation was referred or initiated.

Example:

null

member.metadata

string

Additional information a partner can store on the member.

Example:

"Additional information"

member.skip_aggregation

boolean

When set to true, prevents automatic aggregation from starting after member creation. Defaults to false.

Example:

false

member.skip_webhook

boolean

When set to true, prevents webhook notifications from being sent for this member creation. Defaults to false.

Example:

false

member.ui_message_webview_url_scheme

string

The URL scheme for displaying UI messages in a webview during the aggregation process.

Example:

null

member.use_cases

enum<string>[]

The use case associated with the member. Valid values are PFM and/or MONEY_MOVEMENT. Only set this if you've met with MX and have opted in to using this field. For more info, see Member Use Cases.

Available options:

MONEY_MOVEMENT,

PFM

Example:

["PFM"]

Response

200 - application/vnd.mx.nexus.v1+json

member

object

Hide child attributes

member.aggregated_at

string | null

The date and time the most recent aggregation-type job was started, given in ISO 8601 format with a time component. A job will automatically be started when a member is created or its credentials are updated, unless the skip_aggregation parameter is used. Jobs can also be started via manual aggregations, background aggregations, API endpoints, or when opening an MX widget. A job can be a normal aggregation, or a premium job 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.

Example:

"2016-10-13T18:07:57.000Z"

member.background_aggregation_is_disabled

boolean

This field indicates whether background aggregation is disabled for the member.

Example:

false

member.connection_status

string | null

This field indicates the state of a member's aggregation, provided as a string.

Example:

"CONNECTED"

member.external_guid

any | null

Partner created identifier for the member. It must be unique for all members belonging to all users within the client.

Example:

null

member.guid

string | null

Unique identifier for the member. Defined by MX.

Example:

"MBR-7c6f361b-e582-15b6-60c0-358f12466b4b"

member.institution_code

string | null

The code identifier for the institution.

Example:

"chase"

member.institution_guid

string

The unique identifier for the institution. Defined by MX.

Example:

"INS-1572a04c-912b-59bf-5841-332c7dfafaef"

member.is_being_aggregated

boolean | null

This field will be true if the member is being aggregated at the time of the request. Otherwise, this field will be false.

Example:

false

member.is_managed_by_user

boolean | null

If the member is managed by the user, this field will be true. Otherwise, the member is managed by the MX partner, and this field will be false. Members created with Nexus are considered to be managed by the user. This field should be used in place of is_user_created.

Example:

false

member.is_oauth

boolean | null

This indicates whether the member uses OAuth to authenticate the member. Defaults to false. authentication.

Example:

false

member.is_user_created

boolean

If the member is user created, this field will be true. Otherwise, this field will be false. Members created with Nexus are considered user created. You should use the field is_managed_by_user instead of this field as it is being deprecated.

Example:

true

member.most_recent_job_guid

string

Unique identifier for the most recent job. Defined by MX.

Example:

"JOB-d6bb804b-6d12-44f1-b0ad-403441c03372"

member.metadata

string | null

Additional information a partner can store on the member.

Example:

"\\\"credentials_last_refreshed_at\\\": \\\"2015-10-15\\\""

member.name

string | null

Name of the given member. If omitted in a member create request, the institution name within the MX Platform will be used.

Example:

"Chase Bank"

member.successfully_aggregated_at

string | null

Date and time the account was last successfully aggregated, represented in ISO 8601 format with timestamp (e.g., 2015-04-13T12:01:23-00:00).

Example:

"2016-10-13T17:57:38.000Z"

member.use_cases

enum<string>[]

Available options:

MONEY_MOVEMENT,

PFM

Example:

["PFM"]

member.user_guid

string | null

Unique identifier for the user the member is attached to. Defined by MX.

Example:

"USR-fa7537f3-48aa-a683-a02a-b18940482f54"

List members

Read member