API address structure (URLs)

Every resource of the teamspace API is addressed via a URL. Once you understand how these addresses are built, you can work out most requests yourself – the pattern is the same everywhere.

The five parts of an API address

A typical API address is made up of these parts:

server/api/collection;matrixparameter?query

server – the address of your teamspace installation, for example https://app1.teamspace.de.
api – everything that belongs to the API sits under the fixed path segment api.
collection – the type of resource you are addressing, for example project, time, contact, expense.
matrixparameter – optional switches placed directly on the path, separated by semicolons (for example to limit or sort the result set).
query – the classic query suffix after ?, used to filter the collection (for example ?name=alice&date=2000-01-01).

Addressing a collection

When you address a whole collection, the API lists its elements. Matrix parameters and the query control scope and filtering:

server/api/collection;matrixparameter?query
https://app1.teamspace.de/api/time;limit=10;sort=project?date=2022-01-31

This example reads the first 10 entries (limit=10) from the time collection, sorted by project (sort=project) and filtered to the date 2022-01-31.

Addressing a single element

You reach a single element by appending the element ID to the collection:

server/api/collection/itemid;matrixparameter
https://app1.teamspace.de/api/time/123;depth=0

Here the time element with ID 123 is read. The matrix parameter depth=0 controls how deeply nested/linked objects are included.

A collection’s response

When you query a collection, the API responds with an object that contains the matches as items – along with the total count and the page size:

{
  "size": 3,
  "offset": 0,
  "limit": 100,
  "items": [
    { "caption": "Example corp.", "href": ".../api/contact/3456", "value": 3456 }
  ]
}

Each element is a link object with caption, href and value (the ID). Via href you load the full element – you do not need to assemble the URL yourself (HATEOAS, see below).

Filtering collections (query)

You use the query part after ? to filter a collection. You combine several conditions with &:

Filter	Notation	Example
Equals (`=`, case-insensitive)	`?field=value`	`?name="bob ross"&car=volvo&age=3`
Contains	`?field*=val`	`?name*="bo"`
Range	`?field=1..3`	`?age=20..30`
Or (several values)	`?field=A,B,C`	`?name=alice,"bob ross",charlie`
Field not empty	`?field`	`?name=bob&car`
Field empty	`?!field`	`?name=bob&!car`

For values with spaces, use quotation marks ("bob ross"). Example: all contacts whose caption contains “examp”:

GET  https://app1.teamspace.de/api/contact?caption*=examp

Matrix parameters in detail

Matrix parameters sit on the path (separated by ;) and control the scope and shape of the response:

Purpose	Notation	Effect
Sort ascending	`;sort=name`	by field `name`, ascending
Sort descending	`;sort=!name`	by field `name`, descending
Result set	`;limit=100`	first 100 matches
Offset	`;offset=200`	skip the first 200 matches
Subtree	`;parent=1234`	children of element 1234 (tree structures only)
Nesting depth	`;depth=1`	resolve the first generation of linked references (can be slow)
Show hints	`;showhints=true`	display the available sort options

For single elements there is an additional caching parameter:

Purpose	Notation	Effect
Caching (7 days)	`;lck=value`	response with a 7-day caching header; `value` is a version identifier. As long as it does not change, the HTTP client uses its cache. Tip: use the `_lastModifiedDate` from the collection as the version.

HATEOAS: linked resources

When one element refers to another (for example a contact to its address), the API returns a link object rather than a bare ID:

"mainAddress": {
  "caption": ";;Examplestreet 7;Examplecity;;122456;Germany",
  "href": ".../api/contactfield/173880993",
  "rel": "contactfield",
  "value": 173880993
}

This is how you follow the chain: from the contact to the address, and on from there. When updating, only the value matters – you do not need to send the whole link object back (instead of subtype: {…}, subtype: "HOME" is enough).

Terms at a glance

Term	Meaning	Example
server	address of the installation	`https://app1.teamspace.de`
collection	type of resource	`time`, `project`, `contact`
id	ID of a specific element	`123`
matrix parameter	options on the path (`;`-separated)	`limit=10`, `sort=project`, `depth=0`
query	filter after `?`	`?date=2022-01-31`

Common problems

Why is a query with depth so slow? The depth matrix parameter resolves linked references as well – each generation adds another round of resolution. Even ;depth=1 can be noticeably slower. Set the depth only as high as you need, and when in doubt follow the href links in the response (HATEOAS) rather than loading everything in one call.

Why does my filter with spaces return nothing or an error? Values containing spaces belong in quotation marks: ?name="bob ross". Without them the value ends at the space, and the query filters on the wrong field.

Notes

The collection follows the functional area – the names match the teamspace objects (for example contact for contacts, expense for expense documents).
Matrix parameters sit on the path and are separated by semicolons; the query comes right at the end after ?. The two can be combined.
Concrete request and response examples for each resource are provided by the API Compact Guide (PDF & PowerPoint to download).

Introduction to the API API Introduction
Create and use a device password (API token) API How-to
Create a contact via the API API Exercises