Custom 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're 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 to demonstrate the principle behind these two resources. With this information, create a flow that works well for your product.
All MX users have one default tag that doesn't need to be created: Business.
Create a Tag
First, start by creating a tag. A tag is a label that can be applied to a transaction. This doesn't 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 in the following example.
Note the tag's guid returned in the response. You'll need this for the next step.
Endpoint: POST /users/{user_guid}/tags
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
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 user's taggings across all tags and transactions. You can do this with the list taggings endpoint, shown in the following example.
Endpoint: GET /users/{user_guid}/taggings
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
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.