In December 2017, we proudly released our new action-based API V2, based on an RPC structure. Developers looking to build an integration with Teamleader could now do so in a more user friendly way, using OAuth2 authentication. The goal is to allow developers to retrieve any type of information from Teamleader to apply in another tool, or let them trigger certain actions in Teamleader via webhooks.
This article explains what to keep in mind setting up your new integration using V2, or when making the switch from V1 to API V2 if you have an existing integration.
Building a new integration?
Finalizing API V2
As we are still in the process of adding endpoints to V2, chances are you won’t find some of the features you’re looking for. Among these are ticketing, product and subscription endpoints. For now, these are only available in V1. Bear with us as we add them over the coming months.
If you need access to any of these, we don’t recommend working with API V1 only. Instead, go for V2 from the get-go, but apply V1 endpoints where needed. Your integration will be future proof.
Why? If you start out using V2, you can still use API v1 endpoints in the OAuth2 flow of API v2. In other words, it's no longer needed to pass the 'api_group' and 'api_secret' parameters to every API V1 endpoint if they are authenticated with OAuth 2.
The first step will be implementing OAuth2.
1. Navigate to the Build page on our Marketplace, where you can create your integration and find all the required documentation needed to proceed.
A. Build page
Click ‘Create new integration’
Provide redirect URI
Check your OAuth2 scopes
Provide short and long English description
B. Check OAuth2 documentation
2. Check V2 endpoints
Important to know is that, for now, you cannot skip user login. V2 will always need to be authenticated using OAuth2. However, we are looking into a way to make machine-2-machine calls possible in the future.
Changing your existing integration to V2?
If you have an existing integration, we strongly recommend making the switch to V2 as soon as possible in order to make your integration entirely future-proof. Here’s what you do:
- Implement OAuth2 as described in the first section (you can still use V1 endpoints in the OAuth2 flow)
- Fetch new UUID’s (migrating V1 endpoints) via migration endpoint: https://developer.teamleader.eu/#/reference/other/migrating/migrate.id.
- If you use webhooks, register the webooks via API V2: https://developer.teamleader.eu/#/reference/other/webhooks/webhooks.register. Do note that the webhooks can only be created via the API, not via the user interface as was the case in V1.
- Migrate to new API endpoints, make sure to check the data we provide in the new responses, so everything is covered.
Is your existing integration on API V1 still missing endpoints needed to make the switch to API V2? Let us know via email@example.com.
When will the API V1 be deprecated?
We don’t want you to worry. If you’ve built an integration based on V1, you’ll be given plenty of time to make the switch. For now, there’s no expiration date before which you should have everything ready, but we’ll give you a heads-up when most endpoints are added to V2.
At that point, you should definitely start looking to make the necessary changes to your code. Rest assured, we will not make any plans towards deprecating V1 before at least 95 percent of the endpoints are added to V2. For now, all we ask is that you look out for available V2 endpoints when making updates. This way, you’ll make it easy on yourself when a deadline is set.
Do you have further questions on making the transition? Feel free to contact our support team via firstname.lastname@example.org