Threema Work API API Reference

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.

API Endpoint
https://work.threema.ch/api/v1/
Contact: support-work@threema.ch
Request Content-Types: application/json
Response Content-Types: application/json
Schemes: https
Version: 1.2.0

Authentication

apiKey

name
X-Api-Key
in
header

Subscription

Subscription methods provide access to the subscription.

Subscription

Show Subscription

GET /

Access to your subscription

200 OK
Subscription

Subscription response

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

Response Content-Types: application/json
Response Example (200 OK) 
{
  "_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
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
apiKey
Subscription

Update Subscription

PUT /

Change the name of the subscription

SubscriptionUpdate

Subscription update object

Request Example
{
  "name": "My very nice Threema Work subscription"
}
204 No Content

Subscription successfully updated

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

422 Unprocessable Entity

Unprocessable Entity

Response Content-Types: application/json
Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
apiKey

Credentials

Credential methods provide access to the subscription credentials.

Credentials

Show Credential

GET /credentials/{id}

Show credentials for a specified id

200 OK
Credential

Credentials detail

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

Credentials not found

Response Content-Types: application/json
Response Example (200 OK) 
{
  "_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"
}
Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Credentials

Update Credential

PUT /credentials/{id}

Update the username and password of a specified id

CredentialUpdate
Request Example
{
  "username": "bob",
  "password": "3mawrk"
}
204 No Content

Credentials successfully updated

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

Credentials not found

Response Content-Types: application/json
Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Credentials

Remove Credential

DELETE /credentials/{id}

Remove credentials of a specified id

204 No Content

Credentials successfully removed

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

Credentials not found

Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Credentials

List Credentials

GET /credentials

List all credentials of the package

pageSize

Set to limit the filter result. (0 will ignore the limit and return ALL records)

type
number 20
in
query
page

Set to page offset the filter result to a particular record count.

type
number 0
in
query
200 OK
CredentialIndex

Credentials List Index

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

Response Content-Types: application/json
Response Example (200 OK) 
{
  "_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"
      }
    ]
  }
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
apiKey
Credentials

Create Credential

POST /credentials

Create new credentials

CredentialUpdate
Request Example
{
  "username": "bob",
  "password": "3mawrk"
}
201 Created

Credentials successfully created

400 Bad Request
ErrorResponse

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

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

403 Forbidden
ErrorResponse

No more credentials credits left

Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (403 Forbidden) 
{
  "message": "Detailed error message"
}
apiKey

Users

Subscription methods provide access to the subscription users.

Users

List Users

GET /users

List all users of the package

filterCredential

Filter the users by the id of the used Credential

type
string
in
query
filterQuery

Search the users

type
string
in
query
pageSize

Set to limit the filter result. (0 will ignore the limit and return ALL records)

type
number 20
in
query
page

Set to page offset the filter result to a particular record count.

type
number 0
in
query
200 OK
UserIndex

User List Index

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

Response Content-Types: application/json
Response Example (200 OK) 
{
  "_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"
      }
    ]
  }
}
Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
apiKey
Users

Show User

GET /users/{threemaId}

Show a user, selected by threemaId

200 OK
User

User detail

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

User not found

Response Content-Types: application/json
Response Example (200 OK) 
{
  "_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"
}
Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Users

Revoke User

DELETE /users/{threemaId}

Revoke a user(Threema ID), selected by threemaId

204 No Content

Threema ID successfully revoked

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

User not found

Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Users

Unlink User

POST /users/{threemaId}/detach

Detach a user (Threema ID) from subscription

204 No Content

Threema ID successfully detached

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

User not found

Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey

Contacts

Contacts

Show Contact

GET /contacts/{threemaId}

Show a contact, selected by threemaId

200 OK
Contact

Contact detail

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

Contact not found

Response Content-Types: application/json
Response Example (200 OK) 
{
  "_links": [
    {
      "ref": "detail",
      "link": "https://work.threema.ch/api/v1/contact/ECHOECHO"
    },
    {
      "ref": "subscription",
      "link": "https://work.threema.ch/api/v1"
    }
  ],
  "threemaId": "ECHOECHO",
  "type": "auto",
  "firstName": "Echo",
  "lastName": "Ohce",
  "enabled": "true"
}
Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Contacts

Update Contact

PUT /contacts/{id}

Change the information of a contact, selected by threemaId

ContactUpdate
undefined
Request Example
{
  "firstName": "Echo",
  "lastName": "Ohce",
  "enabled": "true"
}
204 No Content

Contact successfully updated

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

Contact not found

Response Content-Types: application/json
Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Contacts

Remove Contact

DELETE /contact/{threemaId}

Revoke a custom contact, selected by threemaId

204 No Content

Contact successfully removed

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

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

404 Not Found
ErrorResponse

Contact not found

Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Contacts

Show Contacts

GET /contacts

List custom contacts of your subscription

filterType

Filter the result by contact type

type
string custom, auto
in
query
pageSize

Set to limit the filter result. (0 will ignore the limit and return ALL records)

type
number 20
in
query
page

Set to page offset the filter result to a particular record count.

type
number 0
in
query
200 OK
ContactIndex

Subscription contact index response

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

Response Content-Types: application/json
Response Example (200 OK) 
{
  "_links": [
    {
      "ref": "subscription",
      "link": "https://work.threema.ch/api/v1"
    }
  ],
  "contacts": [
    {
      "_links": [
        {
          "ref": "detail",
          "link": "https://work.threema.ch/api/v1/contact/*THREEMA"
        }
      ],
      "threemaId": "*THREEMA",
      "type": "custom",
      "firstName": "Threema",
      "lastName": "Channel",
      "enabled": false
    },
    {
      "_links": [
        {
          "ref": "detail",
          "link": "https://work.threema.ch/api/v1/contact/ECHOECHO"
        }
      ],
      "threemaId": "ECHOECHO",
      "type": "auto",
      "firstName": "Echo",
      "lastName": "Ohce",
      "enabled": true
    }
  ],
  "paging": {
    "count": 2,
    "total": 400,
    "page": 5,
    "_links": [
      {
        "ref": "next",
        "link": "https://work.threema.ch/api/v1/contacts?page=6&pageSize=2"
      },
      {
        "ref": "previous",
        "link": "https://work.threema.ch/api/v1/contacts?page=4&pageSize=2"
      }
    ]
  }
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
apiKey
Contacts

Create Contact

POST /contacts

Create a new custom contact

ContactCreate
Request Example
{
  "threemaId": "ECHOECHO",
  "firstName": "Echo",
  "lastName": "Ohce",
  "enabled": "true"
}
201 Created

Contact successfully created

400 Bad Request
ErrorResponse

Invalid request (invalid threemaId or already exists)

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

Response Content-Types: application/json
Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
apiKey

Threema MDM

Threema MDM

Credential: Show

GET /credentials/{id}/mdm/{property_id}

Show a mdm value (property selected by the property_id) of a credential record (selected by the id)

200 OK
CredentialMdmProperty

MDM value

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

Contact not found

Response Content-Types: application/json
Response Example (200 OK) 
{
  "_links": [
    {
      "ref": "detail",
      "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa/mdm/th_disable_screenshots"
    },
    {
      "ref": "credential",
      "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa"
    }
  ],
  "id": "th_disable_screenshots",
  "value": "false"
}
Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Threema MDM

Credential: Update

PUT /credentials/{id}/mdm/{property_id}

Update a mdm value of a credential record (selected by the id field}

200 OK
MdmValueSimple

MDM value

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

Contact not found

Response Content-Types: application/json
Response Example (200 OK) 
{
  "value": "J.W."
}
Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Threema MDM

Global: Remove

DELETE /credentials/{id}/mdm/{property_id}

Remove a credential (selected by id) MDM value, selected by property_id

204 No Content

Value successfully removed

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

MDM value not found

Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Threema MDM

Credential: List

GET /credentials/{id}/mdm

Show all credential mdm properties

200 OK
CredentialMdmPropertyIndex

MDM index of the credential

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

Response Content-Types: application/json
Response Example (200 OK) 
{
  "_links": [
    {
      "ref": "detail",
      "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa/mdm"
    },
    {
      "ref": "credential",
      "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa"
    }
  ],
  "properties": [
    {
      "_links": [
        {
          "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa/mdm/th_disable_screenshots",
          "ref": "detail"
        }
      ],
      "property": "th_disable_screenshots",
      "value": true
    },
    {
      "_links": [
        {
          "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa/mdm/th_nickname",
          "ref": "detail"
        }
      ],
      "property": "th_nickname",
      "value": "J.W."
    }
  ]
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
apiKey
Threema MDM

Credential: Create

POST /credentials/{id}/mdm

Create or modify a credential mdm property value

MdmValue
undefined
Request Example
{
  "property": "th_nickname",
  "value": "J.W."
}
204 No Content

Value successfully updated

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

422 Unprocessable Entity

Unprocessable Entity

Response Content-Types: application/json
Response Example (400 Bad Request) 
[
  {
    "error": "Invalid logos"
  }
]
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
apiKey
Threema MDM

Global: Show

GET /mdm/{property_id}

Load a mdm value (selected by property_id) of a subscription

200 OK
SubscriptionMdmProperty

MDM value

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

Contact not found

Response Content-Types: application/json
Response Example (200 OK) 
{
  "_links": [
    {
      "ref": "detail",
      "link": "https://work.threema.ch/api/v1/mdm/th_disable_screenshots"
    },
    {
      "ref": "subscription",
      "link": "https://work.threema.ch/api/v1"
    }
  ],
  "id": "th_disable_screenshots",
  "value": "false"
}
Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Threema MDM

Global: Update

PUT /mdm/{property_id}

Update a mdm value of a subscription

200 OK
MdmValueSimple

MDM value

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

Contact not found

Response Content-Types: application/json
Response Example (200 OK) 
{
  "value": "J.W."
}
Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Threema MDM

Global: Remove

DELETE /mdm/{property_id}

Remove a subscription MDM value, selected by property_id

204 No Content

Value successfully removed

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

404 Not Found
ErrorResponse

MDM value not found

Response Example (400 Bad Request) 
{
  "message": "Detailed error message"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
Response Example (404 Not Found) 
{
  "message": "Detailed error message"
}
apiKey
Threema MDM

Global: List

GET /mdm

Show all subscription mdm properties

200 OK
SubscriptionMdmPropertyIndex

MDM index of the subscription

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

Response Content-Types: application/json
Response Example (200 OK) 
{
  "_links": [
    {
      "ref": "subscription",
      "link": "https://work.threema.ch/api/v1"
    }
  ],
  "properties": [
    {
      "_links": [
        {
          "link": "https://work.threema.ch/api/v1/mdm/th_disable_screenshots",
          "ref": "detail"
        },
        {
          "link": "https://work.threema.ch/api/v1",
          "ref": "subscription"
        }
      ],
      "property": "th_disable_screenshots",
      "value": true
    },
    {
      "_links": [
        {
          "link": "https://work.threema.ch/api/v1/mdm/th_nickname",
          "ref": "detail"
        },
        {
          "link": "https://work.threema.ch/api/v1",
          "ref": "subscription"
        }
      ],
      "property": "th_nickname",
      "value": "J.W."
    }
  ]
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
apiKey
Threema MDM

Global: Create

POST /mdm

Create or modify a subscription mdm property value

MdmValue
undefined
Request Example
{
  "property": "th_nickname",
  "value": "J.W."
}
204 No Content

Value successfully updated

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

422 Unprocessable Entity

Unprocessable Entity

Response Content-Types: application/json
Response Example (400 Bad Request) 
[
  {
    "error": "Invalid logos"
  }
]
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
apiKey

Logos

Logos

Show Logos

GET /logos

Access to your In-app logos

200 OK
Logos

Subscription In-app logo response

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

Response Content-Types: application/json
Response Example (200 OK) 
{
  "_links": [
    {
      "ref": "subscription",
      "link": "https://work.threema.ch/api/v1"
    }
  ],
  "dark": "https://path.to/the/logo_dark.png",
  "light": "https://path.to/the/logo_light.png"
}
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
apiKey
Logos

Update Logos

PUT /logos

Update the URLs of the subscriptions in-app-logos

LogosUpdate
undefined
Request Example
{
  "dark": "https://path.to/the/logo_dark.png",
  "light": "https://path.to/the/logo_light.png"
}
204 No Content

Logos successfully updated

400 Bad Request
ErrorResponse

Invalid request

401 Unauthorized
ErrorResponse

Invalid X-Api-Key

422 Unprocessable Entity

Unprocessable Entity

Response Content-Types: application/json
Response Example (400 Bad Request) 
[
  {
    "error": "Invalid logos"
  }
]
Response Example (401 Unauthorized) 
{
  "message": "Detailed error message"
}
apiKey

Schema Definitions

ErrorResponse: object

Error response

message: string
Example
{
  "message": "Detailed error message"
}

Subscription: object

_links: 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 basic, business, enterprise

Chosen subscription type

licenseAmount: int32

Number of purchased licenses

Example
{
  "_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
}

SubscriptionUpdate: object

name: string (1 to 256 chars)

New name of the subscription

Example
{
  "name": "My very nice Threema Work subscription"
}

Logos: object

_links: Link
dark: string

A valid https url to the dark logo

light: string

A valid https url to the light logo

Example
{
  "_links": [
    {
      "ref": "subscription",
      "link": "https://work.threema.ch/api/v1"
    }
  ],
  "dark": "https://path.to/the/logo_dark.png",
  "light": "https://path.to/the/logo_light.png"
}

LogosUpdate: object

dark: string,null (12 to 256 chars)

A valid https url to the dark logo

light: string,null (12 to 256 chars)

A valid https url to the light logo

Example
{
  "dark": "https://path.to/the/logo_dark.png",
  "light": "https://path.to/the/logo_light.png"
}

MdmValue: object

property: string (4 to 256 chars)

Key of the mdm value property

value: string,bool,int (up to 256 chars)

The value of the mdm value

Example
{
  "property": "th_nickname",
  "value": "J.W."
}

MdmValueSimple: object

value: string,bool,int (up to 256 chars)

The value of the mdm value

Example
{
  "value": "J.W."
}

Contact: object

_links: Link
threemaId: string
type: string custom, auto
firstName: string
lastName: string
enabled: boolean
Example
{
  "_links": [
    {
      "ref": "detail",
      "link": "https://work.threema.ch/api/v1/contact/ECHOECHO"
    },
    {
      "ref": "subscription",
      "link": "https://work.threema.ch/api/v1"
    }
  ],
  "threemaId": "ECHOECHO",
  "type": "auto",
  "firstName": "Echo",
  "lastName": "Ohce",
  "enabled": "true"
}

ContactCreate: object

threemaId: string (8 chars)
firstName: string,null (1 to 256 chars)
lastName: string,null (1 to 256 chars)
enabled: boolean
Example
{
  "threemaId": "ECHOECHO",
  "firstName": "Echo",
  "lastName": "Ohce",
  "enabled": "true"
}

ContactUpdate: object

firstName: string,null (1 to 256 chars)
lastName: string,null (1 to 256 chars)
enabled: boolean
Example
{
  "firstName": "Echo",
  "lastName": "Ohce",
  "enabled": "true"
}

ContactIndex: object

_links: Link
contacts: Contact

Contact List

paging: Paging
Example
{
  "_links": [
    {
      "ref": "subscription",
      "link": "https://work.threema.ch/api/v1"
    }
  ],
  "contacts": [
    {
      "_links": [
        {
          "ref": "detail",
          "link": "https://work.threema.ch/api/v1/contact/*THREEMA"
        }
      ],
      "threemaId": "*THREEMA",
      "type": "custom",
      "firstName": "Threema",
      "lastName": "Channel",
      "enabled": false
    },
    {
      "_links": [
        {
          "ref": "detail",
          "link": "https://work.threema.ch/api/v1/contact/ECHOECHO"
        }
      ],
      "threemaId": "ECHOECHO",
      "type": "auto",
      "firstName": "Echo",
      "lastName": "Ohce",
      "enabled": true
    }
  ],
  "paging": {
    "count": 2,
    "total": 400,
    "page": 5,
    "_links": [
      {
        "ref": "next",
        "link": "https://work.threema.ch/api/v1/contacts?page=6&pageSize=2"
      },
      {
        "ref": "previous",
        "link": "https://work.threema.ch/api/v1/contacts?page=4&pageSize=2"
      }
    ]
  }
}

Credential: object

_links: Link
id: string
username: string
password: string
licenseAmount: int32
Example
{
  "_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"
}

CredentialUpdate: object

username: string (1 to 256 chars)

Unique username

password: string (1 to 256 chars)

Password of the credential

Example
{
  "username": "bob",
  "password": "3mawrk"
}

Paging: object

count: int32
total: int32
page: int32
_links: Link
Example
{
  "count": 20,
  "total": 400,
  "page": 9,
  "_links": [
    {
      "ref": "detail",
      "link": "https://work.threema.ch/api/v1/link-to-resource"
    }
  ]
}

CredentialIndex: object

_links: Link
credentials: Credential

Credential List

paging: Paging
Example
{
  "_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"
      }
    ]
  }
}

UserIndex: object

_links: Link
users: User

User List

paging: Paging
Example
{
  "_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: object

_links: Link
id: string (8 chars)

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

Example
{
  "_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"
}

CredentialMdmProperty: object

_links: Link
id: string

Name of the mdm property Example: th_disable_screenshots

value: string|bool|int

Value of the mdm property (can be a number, string or a boolean value)

Example
{
  "_links": [
    {
      "ref": "detail",
      "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa/mdm/th_disable_screenshots"
    },
    {
      "ref": "credential",
      "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa"
    }
  ],
  "id": "th_disable_screenshots",
  "value": "false"
}

SubscriptionMdmProperty: object

_links: Link
id: string

Name of the mdm property Example: th_disable_screenshots

value: string|bool|int

Value of the mdm property (can be a number, string or a boolean value)

Example
{
  "_links": [
    {
      "ref": "detail",
      "link": "https://work.threema.ch/api/v1/mdm/th_disable_screenshots"
    },
    {
      "ref": "subscription",
      "link": "https://work.threema.ch/api/v1"
    }
  ],
  "id": "th_disable_screenshots",
  "value": "false"
}

SubscriptionMdmPropertyIndex: object

_links: Link
properties: SubscriptionMdmProperty

List of mdm properties

Example
{
  "_links": [
    {
      "ref": "subscription",
      "link": "https://work.threema.ch/api/v1"
    }
  ],
  "properties": [
    {
      "_links": [
        {
          "link": "https://work.threema.ch/api/v1/mdm/th_disable_screenshots",
          "ref": "detail"
        },
        {
          "link": "https://work.threema.ch/api/v1",
          "ref": "subscription"
        }
      ],
      "property": "th_disable_screenshots",
      "value": true
    },
    {
      "_links": [
        {
          "link": "https://work.threema.ch/api/v1/mdm/th_nickname",
          "ref": "detail"
        },
        {
          "link": "https://work.threema.ch/api/v1",
          "ref": "subscription"
        }
      ],
      "property": "th_nickname",
      "value": "J.W."
    }
  ]
}

CredentialMdmPropertyIndex: object

_links: Link
properties: CredentialMdmProperty

List of mdm properties (for the specific credentials)

Example
{
  "_links": [
    {
      "ref": "detail",
      "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa/mdm"
    },
    {
      "ref": "credential",
      "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa"
    }
  ],
  "properties": [
    {
      "_links": [
        {
          "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa/mdm/th_disable_screenshots",
          "ref": "detail"
        }
      ],
      "property": "th_disable_screenshots",
      "value": true
    },
    {
      "_links": [
        {
          "link": "https://work.threema.ch/api/v1/credentials/LAow0Rksa/mdm/th_nickname",
          "ref": "detail"
        }
      ],
      "property": "th_nickname",
      "value": "J.W."
    }
  ]
}
Documentation by Spectacle