> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom Tags and Taggings for Transaction Personalization
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.
**INFO**
All MX users have one default tag that doesn't need to be created: `Business`.
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`
```shell Request theme={null}
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"
}
}'
```
```json Response theme={null}
{
"tag": {
"guid": "TAG-aef36e72-6294-4c38-844d-e573e80aed52",
"name": "MY TAG",
"user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
}
}
```
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](/api-reference/platform-api/reference/tags) endpoint to find the desired `tag_guid`, and one of the [list transactions](/api-reference/platform-api/reference/transactions) endpoint to find the desired `transaction_guid`.
`Endpoint: POST /users/{user_guid}/taggings`
```shell Request theme={null}
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"
}
}'
```
```json Response theme={null}
{
"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"
}
}
```
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`
```shell Request theme={null}
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'
```
```json Response theme={null}
{
"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
}
}
```
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](/api-reference/platform-api/reference/transactions) endpoint.
`Endpoint: GET /users/{user_guid}/tags/{tag_guid}/transactions`
```shell Request theme={null}
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' \
```
```json Response theme={null}
{
"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
}
}
```
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](/api-reference/platform-api/reference/tags), they can do so while still preserving all the tagging relationships they've created. Or they can [update a tagging](/api-reference/platform-api/reference/taggings) to assign a different tag to a transaction.
[Deleting a tag](/api-reference/platform-api/reference/tags) will also delete every tagging which references it. [Deleting a tagging](/api-reference/platform-api/reference/taggings) only removes that specific application of the tag to a transaction.