Skip to main content

Use cases

Here we will outline some common workflows that customers may want to use the API for. This will illustrate how to tie together the response from one API into the request for the next.

Case 1: Updating a loan on a profile​

The statement of position data within Trail should always represent the most up-to-date information for your client, keeping it updated will ensure smooth business operations.

This case study will demonstrate updating the balance on a loan that the client may have made a bulk payment to, but this is equally relevant for any other resource type.

The first step in most API flows will be getting the correct profile; a profile is a container for most information in the system and so is pivotal for the API. If you do not know the Id of the profile you want then you can search for it by name using the Search Profiles endpoint.

Example request:

https://api.gettrail.com/api/v1/profiles/search?searchString=Duy&page=1&pageSize=10

Example response:

{
    status: "Success",
    message: "Profile retrieved successfully.",
    data: {
        items: [
            {
                id: "feeffe88-3d15-488a-9576-df50a2a2c728",
                adviserName: "Duy Dao",
                // Profile data
            },
            {
                id: "feeffe88-3d15-488a-9576-ch50a2d1b728"
                adviserName: "Duy Nguyen",
                // Profile data
            },
        ],
        totalItems: 2, // Total number of contacts
        page: 1, // Current page
        pageSize: 10, // Current page size
        totalPages: 1, // Total pages of contacts
    }
}

Here we have 2 profiles returned, it will be up to your logic to determine which is correct, in this example we will pick Duy Nguyen.

Now that we have the profile we can find the loan that we want to update using the Get Mortgages by Profile ID endpoint.

Example request:

https://api.gettrail.com/api/v1/mortgages?profileId=feeffe88-3d15-488a-a576-ch50a2d1b728&page=1&pageSize=10

Example response:

{
  "status": "Success",
  "message": "Mortgage retrieved successfully.",
  "data": {
    "items": [
      {
        "id": 439003,
        "profileId": "feeffe88-3d15-488a-a576-ch50a2d1b728",
        "lender": "ANZ"
        // Other data
      },
      {
        "id": 439004,
        "profileId": "feeffe88-3d15-488a-a576-ch50a2d1b728",
        "lender": "Westpac"
        // Other data
      }
    ],
    "totalItems": 2,
    "page": 1,
    "pageSize": 10,
    "totalPages": 1
  }
}

In this case we know that the client has made a bulk payment to their Westpac loan so that is the one we want to update. We can update the loan using the Update Mortgage endpoint.

Example request:

https://api.gettrail.com/api/v1/mortgages/439004

Example response:

{
  "status": "Success",
  "message": "Mortgage updated successfully.",
  "data": {
    "id": 439004,
    "profileId": "feeffe88-3d15-488a-a576-ch50a2d1b728"
    // Other data
  }
}

Case 2: A contact moving house​

Another common case is a client moving house, potentially moving in with their partner, or moving out on their own.

In this example we will have two clients who are in a de facto relationship and are already on the same profile, but who are now moving in together. We will assume that we know the profile that this household belongs to. We can get the households using the Get Households by Profile ID endpoint.

Example request:

https://api.gettrail.com/api/v1/households?profileId=feeffe88-3d15-488a-a576-ch50a2d1b728&page=1&pageSize=10

Example response:

{
  "status": "Success",
  "message": "Household retrieved successfully.",
  "data": {
    "items": [
      {
        "householdId": 123456,
        "profileId": "feeffe88-3d15-488a-a576-ch50a2d1b728",
        "address": "10 Tidey Road",
        "members": [
          {
            "id": "5d4be998-9c5c-4e27-aff7-bb3dedfe0c71",
            "name": "Member A"
          }
        ]
        // Other data
      },
      {
        "householdId": 123457,
        "profileId": "feeffe88-3d15-488a-a576-ch50a2d1b728",
        "address": "20 Aviemore Drive",
        "members": [
          {
            "id": "5d4be998-9c5c-4e27-aff7-cc3dedfe0c72",
            "name": "Member B"
          }
        ]
        // Other data
      }
    ],
    "totalItems": 2,
    "page": 1,
    "pageSize": 10,
    "totalPages": 1
  }
}

In this case we want to move "Member A" from "10 Tidey Road" into "20 Aviemore Drive" to do this we need to modify the new household by adding "Member A" to it. We can do this by using the Update Household endpoint.

Example request:

https://api.gettrail.com/api/v1/households/123457

// Request body
{
  "members": [
    {
      "id": "5d4be998-9c5c-4e27-aff7-bb3dedfe0c71",
    },
  ];
}

Example response:

{
  "status": "Success",
  "message": "Household updated successfully.",
  "data": {
    "householdId": 123457,
    "profileId": "feeffe88-3d15-488a-a576-ch50a2d1b728",
    "address": "20 Aviemore Drive",
    "members": [
      {
        "id": "5d4be998-9c5c-4e27-aff7-bb3dedfe0c71",
        "name": "Member A"
      },
      {
        "id": "5d4be998-9c5c-4e27-aff7-cc3dedfe0c72",
        "name": "Member B"
      }
    ]
    // Other data
  }
}

Case 3: Adding Fact Find information for a new contact and opportunity​

Finally, your business may be using a different system to collect fact find information from your clients, if this is the case then adding that into Trail to ensure you have up to date records, and can make use of Trail’s application and servicing processes is crucial. This example will only add a small amount of fact find data into the system, but the same process applies to add more.

In this example a client has completed an initial qualifying fact find where they are requesting a KiwiSaver review.

In a case like this, the first thing we want to check is whether the client from the external system already exists in Trail. To do that we can search for them, for best results use their email address to avoid results of people with similar names. We can use the Search Contacts endpoint for this.

Example request:

https://api.gettrail.com/api/v1/contacts/search?searchString=Joana&page=1&pageSize=10

Example response:

{
  "status": "Success",
  "message": "No matching contacts",
  "data": {
    "items": [],
    "totalItems": 0,
    "page": 1,
    "pageSize": 10,
    "totalPages": 1
  }
}

It looks like this is a new contact, so we will be adding them fresh into Trail. The first step is to create a profile to contain all the information for this person. This can be done with the Create Profile endpoint.

Example request:

https://api.gettrail.com/api/v1/profiles

// Request body
{
  "adviserId": "ad794dfd-a59d-4e17-87be-2176ee880011",
  "profileName": "Ben",
  // Other data
}

Example response:

{
  "status": "Success",
  "message": "Profile created successfully.",
  "data": {
    "profileId": "feeffe88-3d15-488a-a576-ch50a2d1b728",
    "adviserId": "ad794dfd-a59d-4e17-87be-2176ee880011",
    "profileName": "Ben"
    // Other data
  }
}

Now that we have a place to put information the next step is to create the contact via the Create Contact endpoint.

Example request:

https://api.gettrail.com/api/v1/contacts

// Request body
{
  "contactType": "Trust",
  "firstName": "Joana",
  "lastName": "Davis",
  "profiles": [
    {
      "id": "feeffe88-3d15-488a-a576-ch50a2d1b728",
      "relationship": "Group Scheme"
    },
  ],
  // Other data
}

Example response:

{
  "status": "Success",
  "message": "Contact created successfully.",
  "data": {
    "firstName": "Joana",
    "lastName": "Davis",
    "profiles": [
      {
        "id": "feeffe88-3d15-488a-a576-ch50a2d1b728",
        "relationship": "Group Scheme",
        "profileName": "Ben"
      }
    ]
    // Other data
  }
}

Next is creating the opportunity, again we need to know where to put this opportunity in the pipelines so we will first get the pipelines and stages. We can use the Search Pipelines endpoint for this.

Example request:

https://api.gettrail.com/api/v1/pipelines/search?searchString=Mortgage Advice&page=1&pageSize=10

Example response:

{
  "status": "Success",
  "message": "Pipeline retrieved successfully.",
  "data": {
    "items": [
      {
        "id": 33,
        "name": "Mortgage Advice",
        "service": "Mortgage",
        "stages": [
          {
            "id": 201,
            "name": "New Lead",
            "order": 0
          },
          {
            "id": 202,
            "name": "Qualifying Call",
            "order": 1
          }
          // Other stages
        ]
      }
    ],
    "totalItems": 1,
    "page": 1,
    "pageSize": 10,
    "totalPages": 1
  }
}

The client is undergoing their Qualifying Call, so we will be adding them to the ‘Qualifying Call’ stage. Let's create an opportunity using the Create Mortgage Opportunity endpoint.

Example request:

https://api.gettrail.com/api/v1/opportunities/mortgage

// Request body
{
  "profileId": "feeffe88-3d15-488a-a576-ch50a2d1b728",
  "adviserId": "ad794dfd-a59d-4e17-87be-2176ee880011",
  "pipelineId": 33,
  "stageId": 202,
  "opportunityType": ["New Purchase"]
  // Other data
}

Example response:

{
  "status": "Success",
  "message": "Opportunity created successfully.",
  "data": {
    "opportunityId": 50,
    "pipelineName": "Mortgage Advice",
    "stageName": "Qualifying Call",
    "profileId": "feeffe88-3d15-488a-a576-ch50a2d1b728",
    "adviserId": "ad794dfd-a59d-4e17-87be-2176ee880011",
    "opportunityType": ["New Purchase"]
    // Other data
  }
}