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.

Show Subscription

GET /

Access to your subscription

200 OK

Subscription response

401 Unauthorized

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

Update Subscription

PUT /

Change the name of the subscription

Subscription update object

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

Subscription successfully updated

400 Bad Request

Invalid request

401 Unauthorized

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

Credentials

Credential methods provide access to the subscription credentials.

Show Credential

GET /credentials/{id}

Show credentials for a specified id

200 OK

Credentials detail

400 Bad Request

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

Update Credential

PUT /credentials/{id}

Update the username and password of a specified id

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

Credentials successfully updated

400 Bad Request

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

Remove Credential

DELETE /credentials/{id}

Remove credentials of a specified id

204 No Content

Credentials successfully removed

400 Bad Request

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

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

Credentials List Index

401 Unauthorized

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

Create Credential

POST /credentials

Create new credentials

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

Credentials successfully created

400 Bad Request

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

401 Unauthorized

Invalid X-Api-Key

403 Forbidden

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

Users

Subscription methods provide access to the subscription 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

User List Index

400 Bad Request

Invalid request

401 Unauthorized

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

Show User

GET /users/{threemaId}

Show a user, selected by threemaId

200 OK

User detail

400 Bad Request

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

Revoke User

DELETE /users/{threemaId}

Revoke a user(Threema ID), selected by threemaId

204 No Content

Threema ID successfully revoked

400 Bad Request

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

Unlink User

POST /users/{threemaId}/detach

Detach a user (Threema ID) from subscription

204 No Content

Threema ID successfully detached

400 Bad Request

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

Contacts

Show Contact

GET /contacts/{threemaId}

Show a contact, selected by threemaId

200 OK

Contact detail

400 Bad Request

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

Update Contact

PUT /contacts/{id}

Change the information of a contact, selected by threemaId

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

Contact successfully updated

400 Bad Request

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

Remove Contact

DELETE /contact/{threemaId}

Revoke a custom contact, selected by threemaId

204 No Content

Contact successfully removed

400 Bad Request

Invalid request

401 Unauthorized

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

404 Not Found

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

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

Subscription contact index response

401 Unauthorized

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

Create Contact

POST /contacts

Create a new custom contact

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

Contact successfully created

400 Bad Request

Invalid request (invalid threemaId or already exists)

401 Unauthorized

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

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)

MDM value

400 Bad Request

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

Credential: Update

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

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

MDM value

400 Bad Request

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

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

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

Credential: List

GET /credentials/{id}/mdm

Show all credential mdm properties

MDM index of the credential

401 Unauthorized

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

Credential: Create

POST /credentials/{id}/mdm

Create or modify a credential mdm property value

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

Value successfully updated

400 Bad Request

Invalid request

401 Unauthorized

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

Global: Show

GET /mdm/{property_id}

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

MDM value

400 Bad Request

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

Global: Update

PUT /mdm/{property_id}

Update a mdm value of a subscription

MDM value

400 Bad Request

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

Global: Remove

DELETE /mdm/{property_id}

Remove a subscription MDM value, selected by property_id

204 No Content

Value successfully removed

400 Bad Request

Invalid request

401 Unauthorized

Invalid X-Api-Key

404 Not Found

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

Global: List

GET /mdm

Show all subscription mdm properties

MDM index of the subscription

401 Unauthorized

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

Global: Create

POST /mdm

Create or modify a subscription mdm property value

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

Value successfully updated

400 Bad Request

Invalid request

401 Unauthorized

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

Logos

Show Logos

GET /logos

Access to your In-app logos

200 OK

Subscription In-app logo response

401 Unauthorized

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

Update Logos

PUT /logos

Update the URLs of the subscriptions in-app-logos

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

Invalid request

401 Unauthorized

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

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."
    }
  ]
}