Overview

The TeamDynamix Web API provides a series of RESTful web services to facilitate integration with various areas of the TeamDynamix solution.

It is important to note that these web services have been designed to send and receive data in JSON (JavaScript Object Notation) format. Other formats, such as XML or plain text, are not supported. When calling the web API, requests must include Content-Type: application/json.

Authentication

Authentication for these API methods below is based on the inclusion of a Bearer token in the standard Authorization header of any HTTP requests. This token is in JSON Web Token (JWT) format, and such tokens can be retrieved though standard authentication methods.

For example, authentication may be performed like so: 

POST /api/auth HTTP/1.1
Content-Type: application/json; charset=utf-8

{"username": "user", "password": "password"}

When successful, that will result in a response like the following, which will return the full contents of the JWT: 

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1...

After this token has been retrieved, it can be included in any subsequent HTTP requests like so: 

GET /api/tickets/123456 HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1...

You can re-use this token for more than one request. The token will expire 24 hours after it has been issued. To determine the lifetime of a returned token, we recommend that you decode the JWT and verify the expiration date stored within it (stored as the exp claim).

Where noted, some actions require the use of a special key-based administrative account. For these actions, tokens obtained through the standard login methods will not work.

If you submit an HTTP request with the aforementioned header and still receive a 401 Unauthorized response, there are two typical causes:

  1. The user you are authenticated as lacks sufficient permissions to perform the requested action.
  2. Your authentication token has expired.

In the latter case, simply re-authenticate to obtain a new token.

Rate Limiting

To ensure continued availability of system resources for all users in a TeamDynamix environment, rate-limiting restrictions are enforced on many methods in the Web API. When a method is rate-limited, the limit is shown in its description. Exceeding the limit returns a 429 Too Many Requests response. See the Rate Limiting guide for details on limit types, response headers, and retry guidance.

Date and Time Fields

All dates in the Web API use ISO 8601 format and are returned in UTC. When submitting dates, you may use UTC directly or include a UTC offset. See the Date and Time Fields Guide for format details, date-only field handling, and examples.

Submitting Files

Endpoints that accept file uploads use Content-Type: multipart/form-data rather than Content-Type: application/json. These endpoints are noted in their descriptions. See the Submitting Files Guide for request structure details and an example.

HTTP PATCH

Where available, PATCH endpoints let you update only the fields that should change without loading a full item first. Requests use a JSON Patch document in the request body. See the HTTP PATCH Guide for supported operations, Custom Attribute handling, and an example.