This article is intended for anyone creating a 3rd party integration with ServiceTrade. This is list of frequently asked questions about integration development, but you have questions that aren't covered here, please contact support@servicetrade.com and we'll help you out!
How do I use your API?
Begin at the beginning, young Padawan.
How do I access your API on behalf of separate customers of ours that each have their own ServiceTrade accounts?
Access to our API is done via credentials (username and password) for a user in a ServiceTrade account. We usually recommend that the user account you use to access the API be assigned the Role of "Account Admin" so that your integration will have full access to the associated account. Your customer must be the one to create this user account for you inside of their ServiceTrade account, as ServiceTrade support will not create admin user accounts for 3rd party integrators. If your integration needs to work for multiple separate ServiceTrade customers, then you will need separate user authentication credentials for each of those customer accounts. To learn more about using our API with user credentials, please see this.
Can I keep using the same session ID (authentication token) forever?
No. ServiceTrade will keep a certain number of active session tokens for a single user, but once you get too many, the oldest ones will start getting deleted to make room for new ones. The best process is to simply generate an auth token at the start of an API transaction, perform all your necessary actions, and then delete that auth token at the end of that transaction. That way you don't build up old tokens and you are never at risk for having a token deleted in the middle of using it. To delete an old token, you simply perform a DEL on the /api/auth endpoint as outlined here.
If I get stuck, will you help me out?
If you send us edible arrangements, yes. Seriously though, our Premium and Enterprise customers do have support for using the API included in their subscription. We would prefer that a designated contact for the ServiceTrade customer account be the one to reach out to us for support requests, though in some cases we may be willing to work with 3rd party developers to work through issues. At the end of the day, our goals are aligned with yours: happy customers using even more of what we have to offer!
I created a webhook subscription, but how I can filter it so that I'm not getting a flood of notifications from ServiceTrade?!
You can't! Well, at least not on our side. A webhook subscription is a firehose of information; we'll send you all the Create, Update, and Delete notifications for supported entities to the destination address you specified when you created the webhook subscription. Filtering that firehose is intended to be done on the receiving end (that's you). Ultimately, this gives you a lot of programmatic flexibility as you can change your integration's webhook receiving code at any time without having to worry about modifying the underlying webhook subscription information inside of ServiceTrade.
It seems like whenever a user makes a single change to an entity in ServiceTrade, like a Job, I'm getting multiple webhook notifications about the Job being updated instead of just one. What's up with that?
Sometimes what looks like a single update inside of ServiceTrade results in multiple entities and properties being changed and saved in our database. Each save transaction fires a webhook notification. An example would be editing a Job item on a Job. That action will save the Job Item itself, which prompts a webhook notification for the jobitem, but since the list of Job Items has changed, a webhook notification will be sent for the Job as well, and then the total cost of the Job has likely changed, so another webhook notification for that property change will be sent. In some cases this may seem (and may be) excessive. If you find that to be the case, we recommend implementing a debouncing function in your code so that you can consolidate webhook notifications that might happen in rapid succession for a single entity into a single actionable event.