Request one-time consent of peer

With the ConsentRequest it is possible to request a consent of the peer to an arbitrary text and thus reach agreement on a certain non machine-processable context.

To request an accept/reject decision from a peer to a free text, the ConsentRequestItem is used.

Check the Request’s validity

At first you should check if your Request is valid. You can do this by calling the POST /api/v2/Requests/Outgoing/Validate route on the Sender Connector with the following body. For the one-time consent request we use the ConsentRequestItem. Even though the peer property is optional, it is recommended to specify it whenever possible. This allows additional validation rules to execute. When you are sending a Request via Messages you always know your peer.

{
  "content": {
    "items": [
      {
        "@type": "ConsentRequestItem",
        "mustBeAccepted": true,
        "title": "The Sender is asking for an one time consent",
        "consent": "I hereby confirm that I have read the privacy terms of this cloud service and agree to them.",
        "link": "privacy.demo"
      }
    ]
  },
  "peer": "<the address of the Recipient Connector>"
}

Examples

• “I hereby confirm the login to the website”
• “I confirm my presence in the course”

Please do not use the ConsentRequest to submit tons of text to the peer Identity. It is meant to be a short consent or summary the user agrees to. Please move longer text to external websites. The ConsentRequest is also not meant for contractual agreements.

Create the Request

To create the Request you have to call the POST /api/v2/Requests/Outgoing route on the Sender Connector. Use the following JSON in the Request body:

{
  "content": {
    // the content property of the payload in the step before
  },
  "peer": "<the address of the Recipient Connector>"
}

Note that the Request is currently in status Draft.

Save the complete content of the response. You will need it in the sending Request step.

Example response:

{
  "id": "REQ...",
  "status": "Draft",
  // ...
  "content": {
    "@type": "Request",
    "id": "REQ...",
    "items": [
      {
        "@type": "AuthenticationRequestItem",
        "mustBeAccepted": true,
        "title": "The Sender is asking for an authentication"
      }
    ]
  }
}

Sending Request

There are 2 ways to send the request to the user. Either when creating a RelationshipTemplate or with a contact who already has a relationship, via a message.