Threema Work API

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:

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
{}

Subscription: Update

Change the name of the subscription

Authorizations:
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

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:
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
{}

Credentials: Create

Create new credentials

Authorizations:
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

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:

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
{}

Credentials: Update

Update the username and password of a specified id

Authorizations:
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

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:

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:
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
{}

User: Detail

Show a user, selected by threemaId

Authorizations:

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
{}

User: Remove

Revoke a user(Threema ID), selected by threemaId

Authorizations:

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:

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:

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:

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:
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