--- title: Using Trackers in the API | PostGrid description: Step-by-step guide to creating, referencing, and managing QR code and PURL Trackers via the PostGrid API with code examples. --- An overview of how to create, view and manage Trackers via the API ## Creating a Tracker A Tracker must first be created before one can be used to generate personalized URLs (PURLs) or QR codes in orders. To create a Tracker, make a `POST` request to the `/trackers` endpoint. An example in TypeScript is provided below. ``` async function createTracker() { const requestBody = { redirectURLTemplate: "https://postgrid.com?name={{to.firstName}}", urlExpireAfterDays: 30, }; const requestOptions = { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": "key_abcdefg", // Use your live/test api key here }, body: JSON.stringify(requestBody), }; const res = await fetch( "https://api.postgrid.com/print-mail/v1/trackers", requestOptions, ); return await res.json(); } ``` This function will create a Tracker with a personalized URL containing a query parameter of the receiving contact’s first name titled `name`. When supplying the `redirectURLTemplate`, any merge variable available in the order can be accessed. This includes the `to` and `from` contacts as well as any custom merge variables. After a Tracker has been created, it can be referenced in an order to generate PURLs and QR codes. For more details on the request, refer to our [API documentation](https://docs.postgrid.com/#dc548501-507d-42ee-b05c-4b05856aec72). ## Using Trackers in an order In this example we will create a sample letter which will have a QR code created by a Tracker. An example in TypeScript is provided below. ``` function createOrderHTML(trackerID: string) { const html = `

Check out our cool URL: {{${trackerID}}}

Scan the QR code to be taken to our website

`; return html; } async function createLetter(trackerID: string) { const requestBody = { html: createOrderHTML(trackerID), to: "contact_abcd", from: "contact_efgh", size: "us_letter", }; const requestOptions = { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": "key_abcdefg", // Use your live/test api key here }, body: JSON.stringify(requestBody), }; const letter = await fetch( "https://api.postgrid.com/print-mail/v1/letters", requestOptions, ); return await letter.json(); } ``` In this example we create a letter with HTML that contains a merge variable of a Tracker we wish to use. Both a short URL and a QR code which lead to the Trackers `redirectURLTemplate` will be generated. Check out our guide [Sending Letters using the API](/print-and-mail/api/sending-letters-using-the-api/index.md) for more information about creating letters using the API. ## URL Shortening When a Tracker is referenced in a template or order HTML using the `{{your_tracker_id.url}}` merge variable, PostGrid automatically shortens the generated URL. This means you do not need to use a third-party link shortener — the personalized URL (PURL) produced for each recipient will already be a short, compact link. Shortened URLs are especially useful in printed mail where space is limited and long URLs are difficult for recipients to type manually. The short URL will redirect to the Tracker’s `redirectURLTemplate`, with any merge variables resolved for the specific recipient. ```

Visit your personalized link: {{tracker_abc123.url}}

``` In the rendered mail piece, `{{your_tracker_id.url}}` will be replaced with a shortened URL unique to that order and Tracker combination. ## Tracking Tracker metrics ## Visit counts Interactions with Trackers are tracked using Tracker Visits. Although the overall number of interactions are recorded on the Tracker itself, Tracker Visits provide information by recording the device used, IP address and referred Tracker/order ID for each visit. Since Trackers contain the unique and total number of visits, to obtain this information simply query for the desired Tracker. An example in TypeScript is provided below. ``` async function fetchTracker(trackerID: string) { const requestOptions = { method: "GET", headers: { "x-api-key": "key_abcdefg", // Use your live/test api key here }, }; const tracker = await fetch( `https://api.postgrid.com/print-mail/v1/trackers/${trackerID}`, requestOptions, ); return await tracker.json(); } ``` This will return the desired Tracker if it exists which will have information regarding the unique and total number of visits. Check out the [Trackers](https://docs.postgrid.com/#ec4f1454-77a8-43e3-82d5-4a07dc9e33a8) documentation for an exhaustive list of fields available. ## Individual Visits Tracker Visits provide more targeted information regarding the interactions on a Tracker and are useful when more information is needed on the individual visits of a Tracker. To view individual visits for a Tracker, query the `/tracker/:id` endpoint. An example in TypeScript is provided below. ``` async function fetchVisits(trackerID: string) { const requestOptions = { method: "GET", headers: { "x-api-key": "key_abcdefg", // Use your live/test api key here }, }; const visits = await fetch( `https://api.postgrid.com/print-mail/v1/trackers/${trackerID}/visits`, requestOptions, ); return await visits.json(); } ``` This will return a list of paginated Tracker Visits. Check out the [Tracker Visits](https://docs.postgrid.com/#ec4f1454-77a8-43e3-82d5-4a07dc9e33a8) documentation for an exhaustive list of fields available. ## Updating Trackers You may find yourself needing to modify the expiration date or base URL of the Trackers generated PURLs to better fit your requirements. In this case, you can modify an existing Tracker by making a `POST` request to the `/trackers/:id` endpoint. An example in TypeScript is provided below. ``` async function updateTracker(trackerID: string) { const requestBody = { redirectURLTemplate: "https://postgrid.com?name={{to.firstName}}&id={{to.metadata.id}}", urlExpireAfterDays: 60 }; const requestOptions = { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": "key_abcdefg", // Use your live/test api key here }, body: JSON.stringify(requestBody), }; const tracker = await fetch(`https://api.postgrid.com/print-mail/v1/trackers/${trackerID}`, requestOptions); return await tracker.json(); } ``` This will update the desired Tracker if it exists to have an updated redirect URL and URL expiration. For more detailed information, refer to our [API documentation](https://docs.postgrid.com/#b53c4e24-115f-4b52-b22e-1c8a5ab4a7dd). ## Deleting Trackers When a Tracker is no longer required, it can be deleted by making a `DELETE` request to the `/trackers/:id` endpoint. An example in TypeScript is provided below. ``` async function deleteTracker(trackerID: string) { const requestOptions = { method: "DELETE", headers: { "Content-Type": "application/json", "x-api-key": "key_abcdefg", // Use your live/test api key here }, }; const deleted = await fetch( `https://api.postgrid.com/print-mail/v1/trackers/${trackerID}`, requestOptions, ); return await deleted.json(); } ``` This will delete the requested Tracker if it exists meaning you will not be able to use it for future orders. [API Reference](/api/index.md)