Parameters: fields, key:alias and JSON Objects flattening/nesting (advanced response shaping)

In order to help reduce an integration's complexity and time to deployment, TrackTik's API offers many payload shaping tools so that you can transit data from TrackTik to a destination system in a format that it expects. This reduces development time and complexity because it eliminates the need to have to map and reshape the data for consumption at destination. 

In our Basic Shaping guide you're introduced to our Fields List and Relation Lists mechanisms and parameters, and in this document we offer more advanced features:

• Key Name Aliasing (if our dictionary is different than yours, rename/alias the keys)
• JSON Nested Object Flattening (nested JSON object, like our relation lists, flattened into a list of keys that are a part of the main key:value pairs list)
• JSON Object Nesting (take some fields at the root of the payload and nest it as a 1:1 object)

Key Name Aliasing

Any key in an API call's response can be renamed/aliased to something else using the "fields" parameter and a comma separated list of:

sourceKey : aliasKey

E.g.

• startedOn is aliased to "clockIn"
• endedOn is aliased to "clockOut"
• employee is aliased to "guard"

[GET] /work-sessions?sort=-id&fields=id,startedOn:clockIn,endedOn:clockOut,employee:guard

{
            "id": 5102,
            "clockIn": "2025-08-13T11:56:11+00:00",
            "clockOut": "2025-08-13T19:56:11+00:00",
            "guard": 1516
}

JSON Nested Object Flattening

Many of TrackTik's endpoints have Relation Lists that can be expanded and embedded into the payload. When included in the response, it appears as a nested JSON object. The "fields" parameter can be used to pull and flatten that nested object into the main body of the response.

In general, the Aliasing mechanism performs many duties, and its format is:

sourceobjectkey.key : aliaskey

One example is the Address of an Employee. Consider the below payload that has the Address relation list included as a nested JSON object. 

[GET] /employees/1442?include=address

{
        "jobTitle": "",
        "region": 2,
        "employmentProfile": 360,
        "id": 1442,
        "customId": "",
        "firstName": "Happy",
        "middleName": "",
        "lastName": "Developer",
        "name": "Happy Developer",
        "primaryPhone": "",
        "secondaryPhone": "",
        "email": "",
        "status": "ACTIVE",
        "avatar": "https://innovation.staffr.net/rest/v1/avatar/employees/1442/e0b38e6f7e390fc888883971d04fc81c",
        "address": {
            "addressLine1": "4200 Blvd Saint-Laurent",
            "addressLine2": "Suite 445",
            "city": "Montréal",
            "country": "CA",
            "state": "QC",
            "postalCode": "H2W 2R2",
            "latitude": null,
            "longitude": null,
            "formattedAddress": "4200 Blvd Saint-Laurent, Suite 445, Montréal Quebec H2W 2R2, Canada",
            "id": 1638
        }
}

What if your destination system that you're moving data to prefers to have the address data inline with the rest of the payload? Instead of developing your own transformer after receiving the payload, you can instead modify the API call to do this for you at runtime. To achieve this you need to add a "fields" parameter that define aliases for each of the nested fields as parent fields:

• address.addressLine1 becomes "addressLine1"
• address.addressLine2 becomes "addressLine2"
• address.city becomes "city"
• etc.

[GET] /employees/1442?fields=id,region,firstName,lastName,status,address.addressLine1:addressLine1,address.addressLine2:addressLine2,address.city:city,address.country:country,address.state:state,address.postalCode:postalCode

{
        "id": 1442,
        "region": 2,
        "firstName": "Happy",
        "lastName": "Developer",
        "status": "ACTIVE",
        "addressLine1": "4200 Blvd Saint-Laurent",
        "addressLine2": "Suite 445",
        "city": "Montréal",
        "country": "CA",
        "state": "QC",
        "postalCode": "H2W 2R2"
}

JSON Object Nesting

If the destination system you're pulling data into requires data to be encapsulated differently as nested JSON objects, key aliases and the "fields" parameter can be used to perform this for you. The parameter format/strategy is:

sourcekey : nestedobjectname.key

The "nestedobjectname" will be the name of the key of the nested JSON object, and the "key" will be the key of the key:value pair within it. You will need to define one of these aliases for each key:value pair you want added to the object. 

Here's an example where a Report's dates and times data are broken out as their own nested object, and fewer fields are included from the original payload to simulate a preference for less data on the whole: 

BEFORE

[GET] /reports/6205

{
        "reportTemplate": 40,
        "timeZone": "America/New_York",
        "reportDateTime": "2025-06-03T08:18:23-04:00",
        "submitTime": 1748953103,
        "submittedOn": "2025-06-03T12:18:23+00:00",
        "account": 34,
        "position": 11,
        "job": null,
        "dispatchTask": null,
        "mobileScheduleOccurrenceLog": null,
        "approvedOn": "2025-06-03T14:26:28+00:00",
        "approvalDateTime": "2025-06-03T14:26:28+00:00",
        "status": "APPROVED",
        "approvedBy": 1,
        "checkpoint": 42,
        "reportFlag": null,
        "siteLocation": null,
        "uuid": "362a9a9b-81bf-47d1-acaf-17204c0ba04e",
        "id": 6205
}

AFTER

[GET] /reports/6205?fields=id,reportTemplate,account,position,approvedBy,checkpoint,timeZone:chronology.timeZone,submittedOn:chronology.submittedOn,approvedOn:chronology.approvedOn,updatedOn:chronology.updatedOn

{
        "id": 6205,
        "reportTemplate": 40,
        "account": 34,
        "position": 11,
        "approvedBy": 1,
        "checkpoint": 42,
        "chronology": {
            "timeZone": "America/New_York",
            "submittedOn": "2025-06-03T12:18:23+00:00",
            "approvedOn": "2025-06-03T14:26:28+00:00",
            "updatedOn": "2025-06-03T14:26:28+00:00"
        }
}