Migrating from v1 to v2
TeamUp's original developer APIs — the parallel Business API and Customer API, collectively referred to as "v1" — have been replaced by a single unified v2 API. v1 is deprecated and closed to new integrations: all new API Applications receive v2 credentials only.
This guide explains what changed, how authentication moved, and how to recognize the errors that migrating integrations most often run into.
What Changed Conceptually
In v1 you had to decide up front whether you were calling the Business API or the Customer API, even though both operated on the same underlying objects. In v2 there is one set of endpoints and one data model, and the identity behind your credentials (business staff vs. customer) determines what you can see and do.
See What happened to the Business and Customer APIs? in the FAQ for the full explanation of this model.
| v1 | v2 | |
|---|---|---|
| Endpoints | Two parallel APIs: /api/business/v1/… and /api/customer/v1/… | One unified API: https://goteamup.com/api/v2/… |
| Permissions | Determined by which API you called | Determined by the authenticated identity, plus the TeamUp-Request-Mode header |
| Business selection | Business-ID header | TeamUp-Provider-ID header |
| Documentation | Deprecated — no longer available | docs.goteamup.com |
Each v2 endpoint's reference page lists which request modes (Provider, Customer, Unregistered Customer) can perform which actions, so "which API do I call?" becomes "which identity am I authenticated as?"
Authentication Changes
The OAuth endpoints moved
The v1 OAuth endpoints were replaced by new URLs under /api/v2/:
| Step | v1 (legacy) | v2 |
|---|---|---|
| Authorization | https://goteamup.com/api/auth/authorize | https://goteamup.com/api/v2/auth/oauth/authorize |
| Token exchange | https://goteamup.com/api/auth/access_token | https://goteamup.com/api/v2/auth/oauth/token |
| Token refresh | Not available (v1 tokens were long-lived) | https://goteamup.com/api/v2/auth/refresh_access_token |
The legacy URLs still exist, but they only serve legacy v1 Applications. A v2 Application's client_id is not recognized there — requests fail in confusing ways (see Common Migration Errors) rather than redirecting you to the right place.
Follow the OAuth Integration Guide for the complete v2 flow, including PKCE and refresh-token rotation. Note that v2 access tokens expire after 2 hours and must be refreshed — unlike long-lived v1 tokens, so a stored-token strategy that worked on v1 will not work unchanged on v2.
The v2 token endpoint supports the authorization_code grant type only. There is no client_credentials grant and no static API key — for server-to-server integrations, use an M2M token instead.
M2M tokens work on v2 only
Machine-to-machine (M2M) tokens are the v2 replacement for server-to-server access. They authenticate requests to /api/v2/ endpoints only: v1 endpoints reject M2M tokens with 403 permission errors, no matter how valid the token is. If your integration still calls v1 endpoints, migrate those calls to their v2 equivalents before switching to an M2M token.
Request headers
v2 requests use different headers than v1 — see Making Requests for details:
Authorization: Bearer <TOKEN>for both OAuth access tokens and M2M tokens.TeamUp-Request-Mode: providerorcustomerto disambiguate when one user holds both roles.TeamUp-Provider-ID: <ID>replaces the v1Business-IDheader for selecting a business.
Common Migration Errors and What They Mean
| Symptom | What it means | Fix |
|---|---|---|
404 Not Found from /api/auth/… variants or guessed URLs like /oauth/authorize | You are using a stale link or a guessed OAuth URL. | Use the v2 URLs from the OAuth guide. |
A CloudFront-branded 403/400 error page (HTML, not the API's JSON error format) | The URL you requested doesn't exist on v2 — a retired v1 path, or an invented host (for example, api.goteamup.com has never existed). | The base URL is https://goteamup.com/api/v2/. Check every URL against the endpoint reference. |
| The authorization page renders but shows "This field is required" and no business to select | You sent a v2 Application's client_id to the legacy /api/auth/authorize endpoint, which doesn't recognize it. | Use https://goteamup.com/api/v2/auth/oauth/authorize. |
Token endpoint returns field errors when sent grant_type=client_credentials | v2 supports the authorization_code grant only. | Use an M2M token for server-to-server access. |
403 on every v1 endpoint despite a freshly issued M2M token | M2M tokens are not valid on v1. | Call the v2 equivalents of those endpoints. |
Errors about a missing or invalid Business-ID header | You are calling a v1 endpoint, or sending v1 headers to v2. | On v2, use TeamUp-Provider-ID (and TeamUp-Request-Mode) instead. |
As a general rule: if an error response is not JSON in the documented error format, you are probably not talking to the v2 API at all — recheck the URL before debugging anything else.
Is Everything from v1 in v2?
v2 covers nearly all customer-facing use cases and is the only API that receives new features. A small number of provider-side v1 capabilities arrived in v2 later or initially behaved differently, and remaining differences are treated as gaps to close rather than intentional omissions.
If your v1 integration relies on something you can't find in v2:
- Check the endpoint reference — every v2 endpoint documents which request modes can perform which actions, and the capability may exist under a different resource name.
- If it's genuinely missing, report it (see below) so it can be prioritized.
Where to Get Help
- For how to create and configure an API Application, see the help guide.
- For questions or to report a v1 capability missing from v2, contact TeamUp support through the help center or your usual support channel.