What are Tags and Taggings?
Tags and taggings are two resources in the MX Platform API that, when used together, give end users more control over organizing their transactions. Tags are basically custom labels. Taggings are when you actually apply those labels to specific transactions. Together, they are a powerful tool for personalization, customization, and money management.
This guide shows the process of creating a tag and then applying it to a specific transaction with a tagging. It shows a somewhat simplified process in order to demonstrate the principle behind these two resources. With this information, create a flow that works well for your product.
1. Create a Tag
First, 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.
To achieve true personalization, set up your app so that the end user provides the name included in the body of the request as shown below.
Take note of the tag’s guid returned in the response. You’ll need this for the next step.
Endpoint:
POST /users/{user_guid}/tags
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"
}
}'
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 with a Tagging
After you create a tag, use it for tagging. This means you should actually apply the tag to a particular transaction. Using a transaction_guid and a tag_guid, create a tagging by making a simple request.
As shown in this example, use the tag_guid from the last step and chose 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
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"
}
}'
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 a User's Taggings
You’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
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'
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 a Tag's Transactions
You and your end users will almost certainly want to see a list of all transactions associated with a particular tag. To do this, make a request to the list tag transactions endpoint.
Endpoint:
GET /users/{user_guid}/tags/{tag_guid}/transactions
1
2
3
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' \
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
}
}
5. Update and Delete 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.