Back to top
Vastuu Group


Version: 1.0
Last updated: July 23, 2020
Reading time: 9 min


The message API provides means to create/send messages to identities. You can send a message to any identity, e.g. a housing company, where all users who have access to the housing company identity and its messages can read the message.

The message requires a "to" identity, the ID of the identity to which the message applies to. A message subject and its content should be added as well.

The cc is a list of user IDs to whom the message can be CC'd to. A notification about the message will be sent to these users.


  • Allows reading a message by its id.
  • Allows marking a message read by the currently logged-in user.
  • Allows listing messages sent to "to"-identity.
  • Allows creating a new message.
  • Allows updating a message by its id.
  • Allows deleting a message by its id.

You need to be logged in into Platform of Trust Sandbox and get your bearer token to execute the following cURL requests.

POST a message

curl -i -X POST \
   --url "" \
   --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf" \
   --header "Content-Type: application/json" \
   --data \
         \"toIdentity\": \"0920a84a-1548-4644-b95d-e3f80e1b9ca6\",
         \"subject\": \"Go to the grocery store\",
         \"content\": \"Remember to buy milk!\",
         \"cc\": [

GET a message with its {id}

curl -i -X GET \
   --url "{id}" \
   --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf"

POST request to mark a message "read" by the current user

curl -i -X POST \
   --url  "{id}/read" \
   --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf"

GET messages sent to an identity with {to_identity_id}

curl -i -X GET \
   --url "{to_identity_id}/list" \
   --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf"

NOTE: checkout to see more requests to the Message API and code samples in Java, Python and JavaScript.

API Specification

Download Open API Specification (OAS) for Message here

Download RESTful API Modeling Language (RAML) specifications for Message here

API Documentation

Checkout API endpoint, HTTP calls and associated parameters in details at

Developer Guides

Read on how to get your Bearer Token to start accessing and using Platform of Trust APIs in this Guide

Learn about identities from our Identites and Links guide

Profiles in Different Platforms


Questions and Feedback

Have a question on Message API? Shoot it in Platform of Trust Stack Overflow community page.

Did Message API miss some feature? Make a Wish in GitHub.

Did we miss something? Make a Wish!

tell us in Github

See all APIs