On the morning of Sunday the 10th this year I sent SalesTrekker an email after experiencing issues with their RESTful API. The support response came shortly after advising that the API has been completely depreciated in favour of the newer GraphQL service. There was no notification, no transition, no warning, and no mention of the imminent change in the email reply I'd received a few days earlier regarding another issue. With the weeks of works we'd put into building a full and complete library for integration into mortgage broker businesses one would be forgiven if we were upset (our ST integration included everything from basic queries all the way up to full-featured online applications). However, the truth is that despite SalesTrekker's occasional (and costly) shortcomings it's still the leading platform for Mortgage Broker growth. We'll work with anything and everything in the market but it's ST that we see consistently delivering better broker and consumer outcomes.
The GraphQL query and manipulation language - the API query language now used by SalesTrekker - was first used by Facebook in 2012 before it was released 
to the general market in September of 2015. If you're interested in learning more about the advantages (and disadvantages) you should check out GraphQL.org 
for detailed documentation.
There are some clear advantages in using SalesTrekker's V2 GraphQL API over the now retired RESTful service, such as the ability to return large amounts of necessary data via a single query when multiple slow queries were previously necessary (there's an example of this below). While we would have liked a depreciation timeline on Version 1 of ST's API, it might have been advantageous that we were forced into a new product.
This article builds upon documentation made available on the ST website 
and will show you how to authenticate a user in the ST system, and how to make simple requests. Quoting from ST's developer website, "... due to the strongly typed, enforceable, self explanatory nature of GraphQL schema, as well as the opportunity to test API directly within the playground, there is no other backing documentation to the API". Given that there's no documentation, and since migrating over to GraphQL does introduce various challenges, we figured that we'd share some basic articles for DIY brokers that are simply looking to see how the API works (when documentation otherwise wouldn't be available). We've also scheduled a number of posts that provide some basic functionality made available via the ST webhooks. Nothing we're providing on this page is suitable for a production environment.
Authentication
You can authenticate yourself with SalesTrekker via one of two means:
- Via your account API Key (provides full administrative privileges).
- Via your Username and Password. Privileges are assigned to the logged-in user.
If you plan on authenticating via your account API Key you'll have to retrieve it by navigating your way to your Settings menu (top right), and then to the API menu in the left menu. Hidden for privacy reasons, you're required to first click 'Reveal API Key'.
Unlike most traditional REST APIs your API key cannot be used to directly access SalesTrekker resources. Instead, you'll have to use your API Key to validate against the system and return a JavaScript Web Token (JWT).
Note: If you refresh or change your API key without consideration to attached third-party systems (including ours), those connected systems will cease to work.
Before we have a look at a function that'll actually query ST data, it's worth mentioning that you can interact and play directly with the API via the GraphQL Playground . It's an essential tool for visually building your queries without using the Schema directly. Shown below is the query necessary to validate using your API Key.
The JWT token is shown in the right-hand panel.
The query used was as follows:
If we were to authenticate with a username and password we would use the following:
Of course, you'll want to retrieve and renew your token programmatically; the following example is a non-production example of what might be used.
Usage is as follows:
Alter the header origin to your own secure URL. Requests cannot be made from a non-secure domain.
Once we've retrieved the token there are a couple of steps necessary to retrieve information from the JWT string.
The JavaScript Web Token
JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA. Basically, what this means is that we can use a secret key to validate the data returned to us.
The JWT takes on three parts: the Header, Payload, and Signature. Each part is separated by a period sign. While far from best practice we can return each part by exploding the JWT string as shown below.
The JWT parts will be returned as follows:
The Header includes the encryption type, the Payload includes relevant data, and the Signature contains a string that we use to validate the response. All of this is outside the scope of this article... although if you're interested in pursuing the code into something workable you'll want to read JWT.io 
.
The Payload will often contain an Access Key. However, in the case of SalesTrekker, the entire JWT string is used as a token while the Payload returns the iat (issued at time) and the JWT exp (expiry time).
If you use an invalid token (JWT) in your requests you'll normally have an array returned with details of the error.
So, skipping the validation of the signature we'll look at just a few basic requests. The following function is for demonstration purposes only, it uses a fixed JSON string, and it shouldn't be used in any production tool.
The $accesstoken variable should be replaced with a function that retrieves a valid token or obtains a new token. The library we've written for SalesTrekker obviously does this both in the client application and on our Platform.
If we were to request the various workflows associated with token privileges we would use the following:
A snapshot of the response array is as follows:
The workflow query is one where the advantages of GraphQL become more evident. If we were querying all the workflows associated with a user via the depreciated API (V1) it wouldn't be uncommon to return at least 10 or 12 individual workflow IDs. We'd then have to query the stages of each workflow separately resulting in as many requests. Using GraphQL it's just one simple and fast request to return all data.
The contacts request is useful for a number of reasons, not the least of which is compiling necessary data for SMS messages. While text messages can be sent through SalesTrekker for a fee, there may be times when we'll have to segregate audiences in a manner that the platform doesn't provide. We retrieved about 4500 contacts from the development platform in a little over 5 seconds. In reality you'll want to apply your own style of pagination via the API.
Our demonstration function is rather clumsy in nature and was only used to illustrate a concept. We've pre-formatted various JSON strings which negate the effectiveness of the query language; however, there are times - such as some of the features we include in our Client Plugin 
- where queries are always the same. In reality you'll likely create an array of data, check for required fields, and parse them into a formatted request.
Conclusion
The code on this page was provided for information purposes only. It's far from best practice and simply demonstrates the beginnings of a bigger-picture solution.
Many "marketers" talk about automation but very few know what it actually means. A CRM and your marketing tools should be seamlessly integrated in manner that eliminates double data entry and removes manual actions when automation provides a solution. Sadly, we're the only finance marketing company that manages leads in a manner that resembles anything resembling best-practice; most brokers that have sought the advice of "gurus" are left with little to no business automation to show for their investment.
As with all our integrated software, all our clients receive a lifetime licence for any and all updates to our web-based SalesTrekker features. Whenever an update is made in the future the new product is immediately made available to clients.
