Threema Work API (1.3.0)

Download OpenAPI specification:Download

Threema Work API is designed to let 3rd-party applications communicate with Threema Work subscriptions. *

All requests are authenticated using an X-API-Key which can be obtained from your management cockpit.
An X-API-Key HTTP header must be sent to indicate which API key is to be used with the request.
The API key must match the remote IP (if specified for the given API key) of the connected HTTP client.

Authentication

apiKey

Security scheme type:	API Key
Header parameter name:	X-Api-Key

Subscription

Subscription methods provide access to the subscription.

Subscription: Detail

Access to your subscription

Authorizations:

apiKey

Responses

200

Subscription response

Response Schema: application/json

_links	Array of objects <application/json> (Link)
name	string Short description name of the subscription
validUntil	dateTime Period of validity of the subscription * Format: iso8601 Example: `2018-02-28T22:20:04+0100`
type	string Enum: "basic" "business" "enterprise" Chosen subscription type
licenseAmount	int32 Number of purchased licenses

401

Invalid X-Api-Key

get /

Threema Work API V1

https://work.threema.ch/api/v1/

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"_links":
[
- {
  - "ref": "detail",
  - "link": "https://work.threema.ch/api/v1"
  },
- {
  - "ref": "credentials",
  - "link": "https://work.threema.ch/api/v1/credentials"
  },
- {
  - "ref": "users",
  - "link": "https://work.threema.ch/api/v1/users"
  },
- {
  - "ref": "logos",
  - "link": "https://work.threema.ch/api/v1/logos"
  },
- {
  - "ref": "contacts",
  - "link": "https://work.threema.ch/api/v1/contacts"
  }
],
"name": "My Threema Work subscription",
"validUntil": "2018-02-28T22:20:04+0100",
"type": "enterprise",
"licenseAmount": 400

}

Subscription: Update

Change the name of the subscription

Authorizations:

apiKey

Request Body schema: application/json

name

required

string [ 1 .. 256 ] characters

New name of the subscription

Responses

204

Subscription successfully updated

400

Invalid request

401

Invalid X-Api-Key

422

Unprocessable Entity

put /

Threema Work API V1

https://work.threema.ch/api/v1/

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"name": "My very nice Threema Work subscription"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"message": "Detailed error message"

}

Credentials

Credential methods provide access to the subscription credentials.

Credentials: List

List all credentials of the package

Authorizations:

apiKey

query Parameters

pageSize	any Set to limit the filter result. (`0` will ignore the limit and return ALL records)
page	any Set to page offset the filter result to a particular record count.

Responses

200

Credentials List Index

Response Schema: application/json

_links	Array of objects <application/json> (Link)
credentials	Array of objects (Credential) Credential List
paging	object

401

Invalid X-Api-Key

get /credentials

Threema Work API V1

https://work.threema.ch/api/v1/credentials

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"_links":
[
- {
  - "ref": "subscription",
  - "link": "https://work.threema.ch/api/v1"
  }
],
"credentials":
[
- {
  - "_links":
    [
    {
    "ref": "detail",
    "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa"
    }
    ],
  - "id": "LAow0Rksa",
  - "username": "alice",
  - "password": "3mawrk",
  - "licenseAmount": 0
  },
- {
  - "_links":
    [
    {
    "ref": "detail",
    "link": "https://work.threema.ch/api/v1/credentials/pwq4Kslw"
    }
    ],
  - "id": "pwq4Kslw",
  - "username": "bob",
  - "password": "verySecret",
  - "licenseAmount": 0
  }
],
"paging":
{
- "count": 20,
- "total": 400,
- "page": 5,
- "_links":
  [
  - {
    "ref": "next",
    "link": "https://work.threema.ch/api/v1/credentials?page=6&pageSize=2"
    },
  - {
    "ref": "previous",
    "link": "https://work.threema.ch/api/v1/credentials?page=4&pageSize=2"
    }
  ]
}

}

Credentials: Create

Create new credentials

Authorizations:

apiKey

Request Body schema: application/json

username required	string [ 1 .. 256 ] characters Unique username
password required	string [ 1 .. 256 ] characters Password of the credential
licenseCount	int License count

Responses

201

Credentials successfully created

400

Invalid request (username already in use or invalid request values)

401

Invalid X-Api-Key

403

No more credentials credits left

post /credentials

Threema Work API V1

https://work.threema.ch/api/v1/credentials

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"username": "bob",
"password": "3mawrk",
"licenseCount": "2"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"message": "Detailed error message"

}

Credentials: Detail

Show credentials for a specified id

Authorizations:

apiKey

Responses

200

Credentials detail

Response Schema: application/json

_links	Array of objects <application/json> (Link)
id	string
username	string
password	string
licenseAmount	int32

400

Invalid request

401

Invalid X-Api-Key

404

Credentials not found

get /credentials/{id}

Threema Work API V1

https://work.threema.ch/api/v1/credentials/{id}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"_links":
[
- {
  - "ref": "detail",
  - "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa"
  },
- {
  - "ref": "subscription",
  - "link": "https://work.threema.ch/api/v1"
  }
],
"id": "LAow0Rksa",
"username": "alice",
"password": "3mawrk",
"licenseAmount": "1"

}

Credentials: Update

Update the username and password of a specified id

Authorizations:

apiKey

Request Body schema: application/json

username required	string [ 1 .. 256 ] characters Unique username
password required	string [ 1 .. 256 ] characters Password of the credential

Responses

204

Credentials successfully updated

400

Invalid request

401

Invalid X-Api-Key

404

Credentials not found

put /credentials/{id}

Threema Work API V1

https://work.threema.ch/api/v1/credentials/{id}

Request samples

Payload

Content type

application/json

Copy

Expand all Collapse all

{

"username": "bob",
"password": "3mawrk"

}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"message": "Detailed error message"

}

Credentials: Remove

Remove credentials of a specified id

Authorizations:

apiKey

Responses

204

Credentials successfully removed

400

Invalid request

401

Invalid X-Api-Key

404

Credentials not found

delete /credentials/{id}

Threema Work API V1

https://work.threema.ch/api/v1/credentials/{id}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"message": "Detailed error message"

}

Users

Subscription methods provide access to the subscription users.

Users: List

List all users of the package

Authorizations:

apiKey

query Parameters

filterCredential	any Filter the users by the `id` of the used `Credential`
filterUsername	any Filter the users by the `username` of the used `Credential`
filterQuery	any Search the users
pageSize	any Set to limit the filter result. (`0` will ignore the limit and return ALL records)
page	any Set to page offset the filter result to a particular record count.

Responses

200

User List Index

Response Schema: application/json

_links	Array of objects <application/json> (Link)
users	Array of objects (User) User List
paging	object

400

Invalid request

401

Invalid X-Api-Key

get /users

Threema Work API V1

https://work.threema.ch/api/v1/users

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"_links":
[
- {
  - "ref": "subscription",
  - "link": "https://work.threema.ch/api/v1"
  }
],
"users":
[
- {
  - "_links":
    [
    {
    "link": "https://work.threema.ch/api/v1/users/USER001",
    "ref": "detail"
    },
    {
    "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa",
    "ref": "credential"
    }
    ],
  - "id": "USER001",
  - "lastCheck": "2017-01-01T14:20:00+0100",
  - "nickname": "Alice",
  - "firstName": "Al",
  - "lastName": "Ice",
  - "csi": "AI000001",
  - "category": "Marketing",
  - "version": "android - 3.1k"
  },
- {
  - "_links":
    [
    {
    "link": "https://work.threema.ch/api/v1/users/USER002",
    "ref": "detail"
    },
    {
    "link": "https://work.threema.ch/api/v1/credentials/Kpsow3lSdf",
    "ref": "credential"
    }
    ],
  - "id": "USER002",
  - "lastCheck": "2017-02-01T04:45:00+0100",
  - "nickname": "Bob",
  - "firstName": "B",
  - "lastName": "Ob",
  - "csi": "AI000002",
  - "category": "IT",
  - "version": "ios - 2.9k"
  }
],
"paging":
{
- "count": 20,
- "total": 400,
- "_links":
  [
  - {
    "ref": "prev",
    "link": "https://work.threema.ch/api/v1/users?page=40&pageSize=20"
    },
  - {
    "ref": "next",
    "link": "https://work.threema.ch/api/v1/users?page=42&pageSize=20"
    }
  ]
}

}

User: Detail

Show a user, selected by threemaId

Authorizations:

apiKey

Responses

200

User detail

Response Schema: application/json

_links	Array of objects <application/json> (Link)
id	string 8 characters Threema ID of the user Example: `ECHOECHO`
nickname	string Nickname, chosen by the user in the Threema App
firstName	string First name of the user, configured by the MDM system.
lastName	string Last name of the user, configured by the MDM system.
csi	string Any value (e.g. internal username), configured by the MDM system.
category	string User category (e.g. group, department), configured by the MDM system.
version	string Used Version * Example: `android - 3.1k` \| OS \| Separator \| App Version \| \|---------\|-----------\|-------------\| \| `android` \| `-` \| `3.1k` \|
lastCheck	dateTime Period of validity of the subscription * Format: iso8601 Example: `2017-01-01T14:20:00+0100`

400

Invalid request

401

Invalid X-Api-Key

404

User not found

get /users/{threemaId}

Threema Work API V1

https://work.threema.ch/api/v1/users/{threemaId}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"_links":
[
- {
  - "ref": "detail",
  - "link": "https://work.threema.ch/api/v1/users/ECHOECHO"
  },
- {
  - "ref": "subscription",
  - "link": "https://work.threema.ch/api/v1"
  },
- {
  - "ref": "credential",
  - "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa"
  }
],
"id": "ECHOECHO",
"nickname": "Alice",
"firstName": "Al",
"lastName": "Ice",
"csi": "AI000001",
"category": "Marketing",
"version": "android - 3.1k",
"lastCheck": "2017-01-01T14:20:00+0100"

}

User: Remove

Revoke a user(Threema ID), selected by threemaId

Authorizations:

apiKey

Responses

204

Threema ID successfully revoked

400

Invalid request

401

Invalid X-Api-Key

404

User not found

delete /users/{threemaId}

Threema Work API V1

https://work.threema.ch/api/v1/users/{threemaId}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"message": "Detailed error message"

}

User: Unlink

Detach a user (Threema ID) from subscription

Authorizations:

apiKey

Responses

204

Threema ID successfully detached

400

Invalid request

401

Invalid X-Api-Key

404

User not found

post /users/{threemaId}/detach

Threema Work API V1

https://work.threema.ch/api/v1/users/{threemaId}/detach

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"message": "Detailed error message"

}

Contacts

Contact Categories: Show

Show a contact category (Directory Feature required)

Authorizations:

apiKey

Responses

200

Subscription contact category response

401

Invalid X-Api-Key

get /contact-categories/{threemaId}

Threema Work API V1

https://work.threema.ch/api/v1/contact-categories/{threemaId}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"message": "Detailed error message"

}

Contact: Remove

Revoke a custom contact, selected by threemaId

Authorizations:

apiKey

Responses

204

Contact successfully removed

400

Invalid request

401

Invalid X-Api-Key or contact not a custom contact

404

Contact not found

delete /contact/{threemaId}

Threema Work API V1

https://work.threema.ch/api/v1/contact/{threemaId}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"message": "Detailed error message"

}

Contact: List

List custom contacts of your subscription

Authorizations:

apiKey

query Parameters

filterCategory	any Filter the result by the category
pageSize	any Set to limit the filter result. (`0` will ignore the limit and return ALL records)
page	any Set to page offset the filter result to a particular record count.

Responses

200

Subscription contact index response

Response Schema: application/json

_links	Array of objects <application/json> (Link)
contacts