Introduction

Tags and taggings are two resources in the MX Platform API that can be used together allow end users to personalize their transactions. Tags can be used to create custom labels. Taggings allow end users to apply those labels to specific transactions. Together, they are a powerful tool for personalization, customization, and money management.

This guide will take you through the process of creating a tag and then applying it to a specific transaction with a tagging. This guide shows a somewhat simplified process in order to demonstrate the principle behind these two resources. We’re sure that with this information, you’ll be able to create a flow that works well for your product.

Note that all MX users have one default tag that does not need to be created:Business.


1. Create a tag

Let’s start by creating a tag, which is just a label that can be applied to a transaction. Remember that this step does not actually attach this label to a transaction, it just creates the tag. Note the tag’s guid returned in the response. You’ll need this for the next step.

To really achieve true personalization, your app should be set up in such a way that the end user provides the name included in the body of the create request shown below.

Endpoint:

POST /users/{user_guid}/tags

Example request

1
2
3
4
5
6
7
8
9
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/tags' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "tag": {
        "name": "MY TAG"
      }
    }'

Example response

1
2
3
4
5
6
7
{
  "tag": {
    "guid": "TAG-aef36e72-6294-4c38-844d-e573e80aed52",
    "name": "MY TAG",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

2. Apply the tag to a transaction with a tagging

Now that we’ve got a tag, it can be used for tagging. This means we’ll actually apply the tag to a particular transaction. Using a transaction_guid and a tag_guid, we can create a tagging by making a simple request.

In this example, we’ll use the tag_guid you got in the last step, and we’ve chosen an arbitrary transaction_guid. In practice, you may not go straight from creating a tag to creating a tagging. You may need to use the list tags endpoint to find the desired tag_guid, and one of the list transactions endpoint to find the desired transaction_guid.

Endpoint:

POST /users/{user_guid}/taggings

Example request

1
2
3
4
5
6
7
8
9
10
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/taggings' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "tagging": {
        "tag_guid": "TAG-aef36e72-6294-4c38-844d-e573e80aed52",
        "transaction_guid": "TRN-810828b0-5210-4878-9bd3-f4ce514f90c4"
      }
    }'

Example response

1
2
3
4
5
6
7
8
9
{
  "tagging": {
    "guid": "TGN-007f5486-17e1-45fc-8b87-8f03984430fe",
    "member_is_managed_by_user": true,
    "tag_guid": "TAG-aef36e72-6294-4c38-844d-e573e80aed52",
    "transaction_guid": "TRN-810828b0-5210-4878-9bd3-f4ce514f90c4",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}

3. List all of a user's taggings

We’ve now created a tag and applied that tag to a transaction with a tagging. After you or the end user has done this many times, you might want to see a list of the the user’s taggings across all tags and transactions. You can do this easily with the list taggings endpoint, shown in the example below.

Endpoint:

GET /users/{user_guid}/taggings

Example request

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/taggings/' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "taggings": [
    {
      "guid": "TGN-007f5486-17e1-45fc-8b87-8f03984430fe",
      "member_is_managed_by_user": true,
      "tag_guid": "TAG-aef36e72-6294-4c38-844d-e573e80aed52",
      "transaction_guid": "TRN-810828b0-5210-4878-9bd3-f4ce514f90c4",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 1,
    "total_pages": 1
  }
}

4. List all transactions associated with a tag

You and your end users will almost certainly want to see a list of all transactions associated with a particular tag. This is also a very simple request to the list tag transactions endpoint.

Endpoint:

GET /users/{user_guid}/tags/{tag_guid}/transactions

Example request

1
2
3
4
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/tags/TAG-40faf068-abb4-405c-8f6a-e883ed541fff/transactions' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v2+json' \
-H 'Content-Type: application/json'

Example response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
{
  "transactions": [
    {
      "category": "Mobile Phone",
      "category_guid": "CAT-b4789667-6acc-a112-975e-15746003ed61",
      "created_at": "2021-04-06T21:03:07Z",
      "date": "2021-04-06",
      "posted_at": "2021-04-07T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Bills & Utilities",
      "transacted_at": "2021-04-06T12:00:00Z",
      "type": "DEBIT",
      "updated_at": "2021-04-06T22:35:47Z",
      "account_guid": "ACT-82ac32b4-06e6-48a9-8440-17e49bb3d720",
      "amount": 70.62,
      "check_number_string": null,
      "currency_code": "USD",
      "description": "Verizon",
      "guid": "TRN-a9f17e04-d19a-4d63-943d-e0d8d8eedb49",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_recurring": null,
      "is_subscription": null,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
      "memo": null,
      "merchant_category_code": 0,
      "merchant_guid": "MCH-8324c248-85a9-7071-a29b-1a5b36b4697e",
      "original_description": "Verizon Wireless",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    },
    {
      "category": "Financial",
      "category_guid": "CAT-6c7de3f8-de6c-7061-1dd2-b093044014bf",
      "created_at": "2021-04-06T21:03:08Z",
      "date": "2021-04-06",
      "posted_at": "2021-04-07T12:00:00Z",
      "status": "POSTED",
      "top_level_category": "Financial",
      "transacted_at": "2021-04-06T12:00:00Z",
      "type": "CREDIT",
      "updated_at": "2021-04-06T22:37:02Z",
      "account_guid": "ACT-4d6b39c7-c130-4279-b70b-e5c18d8a6cf2",
      "amount": 31.59,
      "check_number_string": null,
      "currency_code": "USD",
      "description": "Loan Payment",
      "guid": "TRN-9617ba2d-f4cb-491b-90c4-b2fd1369cd03",
      "is_bill_pay": false,
      "is_direct_deposit": false,
      "is_expense": true,
      "is_fee": false,
      "is_income": false,
      "is_international": null,
      "is_overdraft_fee": false,
      "is_payroll_advance": false,
      "is_recurring": null,
      "is_subscription": null,
      "latitude": null,
      "localized_description": null,
      "localized_memo": null,
      "longitude": null,
      "member_guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
      "memo": null,
      "merchant_category_code": 0,
      "merchant_guid": null,
      "original_description": "Loan Payment",
      "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 25,
    "total_entries": 2,
    "total_pages": 1
  }
}

Updating and deleting tags and taggings

Tags and taggings can also be updated or deleted. Check out the links given here for more details.

For instance, if an end user wants to rename a tag, they can do so while still preserving all the tagging relationships they’ve created. Or they can update a tagging to assign a different tag to a transaction.

Deleting a tag will also delete every tagging which references it. Deleting a tagging only removes that specific application of the tag to a transaction.