Data formats


JSON (application/json) is the content type of both requests and responses if not otherwise specified. Requests with invalid JSON will be rejected.


Timestamps are represented using the ISO-8601 standard.

All timestamps returned will be in UTC with millisecond precision.

The time zone can be specified in accordance with ISO-8601. If no time zone offset is specified (local time in ISO-8601) then UTC will be used.


The REST API returns the appropriate HTTP status codes for the request made. Such as 200 OK, 401 Unauthorized or a 400 Bad Request.

When an 4XX HTTP error is returned the response body also contains an error object with more information.

Error handling

Token Expiration

Since the JWT token has an expiry time - see Requesting an Access Token - it can expire in the middle of user conversation. When that happens, a different process in the background should be triggered.

API Errors

If Your.MD has some technical issues, the API will return error messages. The response, returned by Your.MD is a valid conversation response HTTP response with status 200 OK. JSON object messages.value contains a message, that needs to be displayed to the user in the conversation flow window.