Categorize transactions

curl --request POST \
  --url https://int-data.moneydesktop.com/transactions/categorize_and_describe \
  --header 'Content-Type: application/vnd.mx.nexus.v1+json' \
  --header 'MD-SESSION-TOKEN: <api-key>' \
  --data '
{
  "transactions": [
    {
      "amount": 203.76,
      "description": "In N Out Burger",
      "external_guid": "FXP123",
      "memo": "Family dinner night",
      "user_guid": "USR-35972b5e-99fb-b320-6412-a9760a0239e4"
    }
  ]
}
'

{
  "transaction": {
    "account_guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
    "amount": 33.88,
    "amount_set_by": 1,
    "amount_set_by_name": "FEED",
    "category_guid": "CAT-97a2b899-5a32-4196-b87c-a8e65d8a9849",
    "category_name": "Office Supplies",
    "category_set_by": 3,
    "category_set_by_name": "SYSTEM",
    "check_number": null,
    "check_number_set_by": null,
    "check_number_set_by_name": null,
    "check_number_string": null,
    "created_at": "2022-06-14T21:17:10+00:00",
    "currency_code": "USD",
    "currency_code_set_by": 1,
    "currency_code_set_by_name": "FEED",
    "date": "2022-06-14",
    "date_set_by": 1,
    "date_set_by_name": "FEED",
    "description": "Office Depot",
    "description_set_by": 3,
    "description_set_by_name": "SYSTEM",
    "extended_transaction_type": "",
    "external_guid": "transfer-0bc9936d-6761-4aed-af7f-a94e7a0f7e7e",
    "feed_amount": 33.88,
    "feed_check_number": null,
    "feed_check_number_string": null,
    "feed_currency_code": "USD",
    "feed_description": "Office Depot",
    "feed_is_international": null,
    "feed_latitude": null,
    "feed_longitude": null,
    "feed_memo": null,
    "feed_posted_at": "2022-06-15T12:00:00+00:00",
    "feed_posted_on": "2022-06-15",
    "feed_status": 1,
    "feed_transacted_at": "2022-06-14T12:00:00+00:00",
    "feed_transacted_on": "2022-06-14",
    "feed_transaction_type": 2,
    "feed_transaction_type_name": "DEBIT",
    "guid": "TRN-24af807c-66b5-416c-a84e-d18f1003809e",
    "has_been_split": false,
    "has_been_viewed": false,
    "is_bill_pay": false,
    "is_business": false,
    "is_direct_deposit": false,
    "is_expense": true,
    "is_fee": false,
    "is_flagged": false,
    "is_hidden": false,
    "is_income": false,
    "is_international": null,
    "is_international_set_by": null,
    "is_international_set_by_name": null,
    "is_overdraft_fee": false,
    "is_payroll_advance": false,
    "is_recurring": null,
    "is_subscription": false,
    "latitude": null,
    "latitude_set_by": null,
    "latitude_set_by_name": null,
    "localized_description": null,
    "localized_memo": null,
    "longitude": null,
    "longitude_set_by": null,
    "longitude_set_by_name": null,
    "member_is_managed_by_user": true,
    "memo": null,
    "memo_set_by": null,
    "memo_set_by_name": null,
    "merchant_category_code": 0,
    "merchant_guid": "MCH-8f595f23-43fb-2c82-429e-56313bb6dada",
    "merchant_location_guid": null,
    "metadata": "some hard coded transaction metadata",
    "parent_guid": null,
    "posted_at": "2022-06-15T12:00:00+00:00",
    "posted_at_set_by": 1,
    "posted_at_set_by_name": "FEED",
    "revision": 1,
    "scheduled_payment_guid": null,
    "status": 1,
    "status_name": "POSTED",
    "status_set_by": 1,
    "status_set_by_name": "FEED",
    "top_level_category_guid": "CAT-94b11142-e97b-941a-f67f-6e18d246a23f",
    "transacted_at": "2022-06-14T12:00:00+00:00",
    "transacted_at_set_by": 1,
    "transacted_at_set_by_name": "FEED",
    "transaction_type": 2,
    "transaction_type_name": "DEBIT",
    "transaction_type_set_by": 1,
    "transaction_type_set_by_name": "FEED",
    "updated_at": "2022-06-14T21:17:10+00:00",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

POST

transactions

categorize_and_describe

Categorize transactions

curl --request POST \
  --url https://int-data.moneydesktop.com/transactions/categorize_and_describe \
  --header 'Content-Type: application/vnd.mx.nexus.v1+json' \
  --header 'MD-SESSION-TOKEN: <api-key>' \
  --data '
{
  "transactions": [
    {
      "amount": 203.76,
      "description": "In N Out Burger",
      "external_guid": "FXP123",
      "memo": "Family dinner night",
      "user_guid": "USR-35972b5e-99fb-b320-6412-a9760a0239e4"
    }
  ]
}
'

{
  "transaction": {
    "account_guid": "ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530",
    "amount": 33.88,
    "amount_set_by": 1,
    "amount_set_by_name": "FEED",
    "category_guid": "CAT-97a2b899-5a32-4196-b87c-a8e65d8a9849",
    "category_name": "Office Supplies",
    "category_set_by": 3,
    "category_set_by_name": "SYSTEM",
    "check_number": null,
    "check_number_set_by": null,
    "check_number_set_by_name": null,
    "check_number_string": null,
    "created_at": "2022-06-14T21:17:10+00:00",
    "currency_code": "USD",
    "currency_code_set_by": 1,
    "currency_code_set_by_name": "FEED",
    "date": "2022-06-14",
    "date_set_by": 1,
    "date_set_by_name": "FEED",
    "description": "Office Depot",
    "description_set_by": 3,
    "description_set_by_name": "SYSTEM",
    "extended_transaction_type": "",
    "external_guid": "transfer-0bc9936d-6761-4aed-af7f-a94e7a0f7e7e",
    "feed_amount": 33.88,
    "feed_check_number": null,
    "feed_check_number_string": null,
    "feed_currency_code": "USD",
    "feed_description": "Office Depot",
    "feed_is_international": null,
    "feed_latitude": null,
    "feed_longitude": null,
    "feed_memo": null,
    "feed_posted_at": "2022-06-15T12:00:00+00:00",
    "feed_posted_on": "2022-06-15",
    "feed_status": 1,
    "feed_transacted_at": "2022-06-14T12:00:00+00:00",
    "feed_transacted_on": "2022-06-14",
    "feed_transaction_type": 2,
    "feed_transaction_type_name": "DEBIT",
    "guid": "TRN-24af807c-66b5-416c-a84e-d18f1003809e",
    "has_been_split": false,
    "has_been_viewed": false,
    "is_bill_pay": false,
    "is_business": false,
    "is_direct_deposit": false,
    "is_expense": true,
    "is_fee": false,
    "is_flagged": false,
    "is_hidden": false,
    "is_income": false,
    "is_international": null,
    "is_international_set_by": null,
    "is_international_set_by_name": null,
    "is_overdraft_fee": false,
    "is_payroll_advance": false,
    "is_recurring": null,
    "is_subscription": false,
    "latitude": null,
    "latitude_set_by": null,
    "latitude_set_by_name": null,
    "localized_description": null,
    "localized_memo": null,
    "longitude": null,
    "longitude_set_by": null,
    "longitude_set_by_name": null,
    "member_is_managed_by_user": true,
    "memo": null,
    "memo_set_by": null,
    "memo_set_by_name": null,
    "merchant_category_code": 0,
    "merchant_guid": "MCH-8f595f23-43fb-2c82-429e-56313bb6dada",
    "merchant_location_guid": null,
    "metadata": "some hard coded transaction metadata",
    "parent_guid": null,
    "posted_at": "2022-06-15T12:00:00+00:00",
    "posted_at_set_by": 1,
    "posted_at_set_by_name": "FEED",
    "revision": 1,
    "scheduled_payment_guid": null,
    "status": 1,
    "status_name": "POSTED",
    "status_set_by": 1,
    "status_set_by_name": "FEED",
    "top_level_category_guid": "CAT-94b11142-e97b-941a-f67f-6e18d246a23f",
    "transacted_at": "2022-06-14T12:00:00+00:00",
    "transacted_at_set_by": 1,
    "transacted_at_set_by_name": "FEED",
    "transaction_type": 2,
    "transaction_type_name": "DEBIT",
    "transaction_type_set_by": 1,
    "transaction_type_set_by_name": "FEED",
    "updated_at": "2022-06-14T21:17:10+00:00",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

This endpoint takes an array of transactions and automatically categorizes them based on description, transaction_type, and amount. This endpoint can receive and categorize a maximum of 100 transactions per call.

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

transactions

object[]

Hide child attributes

transactions.amount

number

required

The amount of the transaction.

transactions.description

string

required

The description of the transaction.

transactions.user_guid

string

required

Unique identifier for the user initiating the transaction.

transactions.extended_transaction_type

string

The transaction type assigned by the partner.

transactions.external_guid

string

External identifier for the transaction.

transactions.memo

string

Additional memo or notes for the transaction.

Response

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

transaction

object

Hide child attributes

transaction.account_guid

string

Unique identifier for the account. Defined by MX.

Example:

"ACT-8e6f92c8-1491-42ce-8bf6-c309e9531530"

transaction.amount

number

The transaction amount. This will always be a positive value. The Transaction Type determines how the transaction affects the account.

Example:

33.88

transaction.amount_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

1

transaction.amount_set_by_name

string

The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information.

Example:

"FEED"

transaction.category_guid

string

Unique identifier for the transaction category. Defined by MX.

Example:

"CAT-97a2b899-5a32-4196-b87c-a8e65d8a9849"

transaction.category_name

string

The name of the transaction category.

Example:

"Office Supplies"

transaction.category_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

3

transaction.category_set_by_name

string

The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information.

Example:

"SYSTEM"

transaction.check_number

integer

The check number for the transaction. (Deprecated).

Example:

null

transaction.check_number_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

null

transaction.check_number_set_by_name

string

The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information.

Example:

null

transaction.check_number_string

string

The check number for the transaction.

Example:

null

transaction.created_at

string

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

Example:

"2022-06-14T21:17:10+00:00"

transaction.currency_code

string

The ISO 4217 three-character currency code (e.g. USD).

Example:

"USD"

transaction.currency_code_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

1

transaction.currency_code_set_by_name

string

The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information.

Example:

"FEED"

transaction.date

string

Date the transaction was created, represented in ISO 8601 format (e.g. 2011-03-28).

Example:

"2022-06-14"

transaction.date_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

1

transaction.date_set_by_name

string

The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information.

Example:

"FEED"

transaction.description

string

A human-readable description of the transaction.

Example:

"Office Depot"

transaction.description_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

3

transaction.description_set_by_name

string

The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information.

Example:

"SYSTEM"

transaction.extended_transaction_type

string

Additional transaction type classification for specialized transaction categories.

Example:

""

transaction.external_guid

string

Partner created identifier for the transaction.

Example:

"transfer-0bc9936d-6761-4aed-af7f-a94e7a0f7e7e"

transaction.feed_amount

number

Transaction amount, as provided by our data feed. See amount for more information.

Example:

33.88

transaction.feed_check_number

integer

Check number, as provided by our data feed. See check_number for more information.

Example:

null

transaction.feed_check_number_string

string

Check number, as provided by our data feed. See check_number_string for more information.

Example:

null

transaction.feed_currency_code

string

Currency code, as provided by our data feed. See currency_code for more information.

Example:

"USD"

transaction.feed_description

string

Description of the transaction, as provided by our data feed. See description for more information.

Example:

"Office Depot"

transaction.feed_is_international

boolean

Whether the transaction is international, as provided by our data feed. See is_international for more information.

Example:

null

transaction.feed_latitude

number

Latitude for the transaction, as provided by our data feed. See latitude for more information.

Example:

null

transaction.feed_longitude

number

Longitude for the transaction, as provided by our data feed. See longitude for more information.

Example:

null

transaction.feed_memo

string

The transaction memo, as provided by our data feed. See memo for more information.

Example:

null

transaction.feed_posted_at

string

Date and time the transaction was posted, as provided by our data feed. See posted_at for more information.

Example:

"2022-06-15T12:00:00+00:00"

transaction.feed_posted_on

string

Date the transaction was posted, as provided by our data feed. See posted_on for more information.

Example:

"2022-06-15"

transaction.feed_status

integer

Status of the transaction, as provided by our data feed. See status for more information.

Example:

1

transaction.feed_transacted_at

string

Date and time the transaction took place, as provided by our data feed. See transacted_at for more information.

Example:

"2022-06-14T12:00:00+00:00"

transaction.feed_transacted_on

string

Date the transaction took place, as provided by our data feed.

Example:

"2022-06-14"

transaction.feed_transaction_type

integer

The type of transaction, as provided by our data feed. See transaction_type for more information.

Example:

2

transaction.feed_transaction_type_name

string

The type of transaction, as provided by our data feed. See transaction_type_name for more information.

Example:

"DEBIT"

transaction.guid

string

Unique identifier for the transaction. Defined by MX.

Example:

"TRN-24af807c-66b5-416c-a84e-d18f1003809e"

transaction.has_been_split

boolean

If the transaction is a split, this field will be true. Otherwise, this field will be false.

Example:

false

transaction.has_been_viewed

boolean

If the transaction has been viewed, this field will be true. Otherwise, this field will be false.

Example:

false

transaction.is_bill_pay

boolean

If the transaction is a bill pay, this field will be true. Otherwise, this field will be false.

Example:

false

transaction.is_business

boolean

If the transaction is categorized as a business expense, this field will be true. Otherwise, this field will be false.

Example:

false

transaction.is_direct_deposit

boolean

If the transaction is a direct deposit, this field will be true. Otherwise, this field will be false.

Example:

false

transaction.is_expense

boolean

If the transaction is an expense, this field will be true. Otherwise, this field will be false.

Example:

true

transaction.is_fee

boolean

If the transaction is a fee, this field will be true. Otherwise, this field will be false.

Example:

false

transaction.is_flagged

boolean

If the transaction has been flagged, this field will be true. Otherwise, this field will be false.

Example:

false

transaction.is_hidden

boolean

If the transaction is hidden, this field will be true. Otherwise, this field will be false.

Example:

false

transaction.is_income

boolean

If the transaction is income, this field will be true. Otherwise, this field will be false.

Example:

false

transaction.is_international

boolean

If the transaction is international, as defined by the data provider, this field will be true. If the data provider determines it is not international, then it will be false. It will be null if the data provider does not provide this information.

Example:

null

transaction.is_international_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

null

transaction.is_international_set_by_name

string

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

null

transaction.is_overdraft_fee

boolean

If the transaction is an overdraft fee, this field will be true. Otherwise, this field will be false.

Example:

false

transaction.is_payroll_advance

boolean

If the transaction is a payroll advance, this field will be true. Otherwise, this field will be false.

Example:

false

transaction.is_recurring

boolean

This field should be ignored. If this information is required, please reach out to MX to discuss an alternative.

Example:

null

transaction.is_subscription

boolean

If the transaction represents a payment for a subscription service such as Netflix or Audible, this field will be true. Otherwise it will be false.

Example:

false

transaction.latitude

number

The latitude of the location where the transaction occurred. The number is a signed decimal (e.g. Rio de Janeiro's latitude is -22.9027800 and Tokyo's latitude is 35.689488).

Example:

null

transaction.latitude_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

null

transaction.latitude_set_by_name

string

The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information.

Example:

null

transaction.localized_description

string

A human-readable description of the transaction, provided in a local language.

Example:

null

transaction.localized_memo

string

Additional descriptive information about the transaction, provided in a local language.

Example:

null

transaction.longitude

number

The longitude of the location where the transaction occurred. The number is a signed decimal (e.g. Rio de Janeiro's longitude is -43.2075000 and Tokyo's longitude is 139.691706).

Example:

null

transaction.longitude_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

null

transaction.longitude_set_by_name

string

The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information.

Example:

null

transaction.member_is_managed_by_user

boolean

If the member the transaction belongs to 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.

Example:

true

transaction.memo

string

The memo is additional descriptive information about the transaction.

Example:

null

transaction.memo_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

null

transaction.memo_set_by_name

string

The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information.

Example:

null

transaction.merchant_category_code

integer

The merchant category code.

Example:

0

transaction.merchant_guid

string

Unique identifier for the merchant identified in the transaction. Defined by MX.

Example:

"MCH-8f595f23-43fb-2c82-429e-56313bb6dada"

transaction.merchant_location_guid

string

The unique identifier for the merchant location associated with the transaction. Defined by MX.

Example:

null

transaction.metadata

string

Additional information a partner can store on the transaction. NOTE: this field may potentially be overwritten by the data provider when data is refreshed through aggregation. See the FAQs for more information.

Example:

"some hard coded transaction metadata"

transaction.parent_guid

string

The parent guid of the transaction.

Example:

null

transaction.posted_at

string

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

Example:

"2022-06-15T12:00:00+00:00"

transaction.posted_at_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

1

transaction.posted_at_set_by_name

string

The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information.

Example:

"FEED"

transaction.revision

integer

The revision number of this transaction record.

Example:

1

transaction.scheduled_payment_guid

string

The unique identifier for the scheduled payment associated with this transaction. Defined by MX.

Example:

null

transaction.status

integer

The status of the transaction (1 = POSTED, 2 = PENDING). See Status for more information.

Example:

1

transaction.status_name

string

The status of the transaction (POSTED or PENDING). See Status for more information.

Example:

"POSTED"

transaction.status_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

1

transaction.status_set_by_name

string

The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information.

Example:

"FEED"

transaction.top_level_category_guid

string

Unique identifier of the parent category that this transaction's category is assigned to.

Example:

"CAT-94b11142-e97b-941a-f67f-6e18d246a23f"

transaction.transacted_at

string

Date and time the transaction took place, represented in ISO 8601 format with timestamp (e.g. 2015-04-13T12:01:23-00:00).

Example:

"2022-06-14T12:00:00+00:00"

transaction.transacted_at_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

1

transaction.transacted_at_set_by_name

string

The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information.

Example:

"FEED"

transaction.transaction_type

integer

The type of transaction (1 = CREDIT, 2 = DEBIT). See Transaction Types for more information.

Example:

2

transaction.transaction_type_name

string

The type of transaction (CREDIT or DEBIT). See Transaction Types for more information.

Example:

"DEBIT"

transaction.transaction_type_set_by

integer

The source that set the data ( 1 = FEED, 2 = USER, 3 = SYSTEM ). See Transaction Set By for more information.

Example:

1

transaction.transaction_type_set_by_name

string

The source that set the data ( FEED, USER, or SYSTEM ). See Transaction Set By for more information.

Example:

"FEED"

transaction.updated_at

string

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

Example:

"2022-06-14T21:17:10+00:00"

transaction.user_guid

string

Unique identifier for the user. Defined by MX.

Example:

"USR-11141024-90b3-1bce-cac9-c06ced52ab4c"

List transactions updated between two dates

Users Overview