Submit Explanation

Submits an employee explanation or a manager or auditor review comment for a specified explanation request and updates the request status. The type parameter determines who is recorded as the author.

Required Permissions

Requires the MEMBER role or higher. Guests can also call this endpoint without logging in by passing a valid explanation token in the token parameter.

HTTP Request

POST /api/sonar/explanation-requests/:request_guid

cURL Example

curl -H "Authorization: Bearer <API_KEY>" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '{
       "type": "EXPLANATION",
       "status": "SUBMITTED",
       "result": 0,
       "content": "Performed during the scheduled maintenance window."
     }' \
     https://HOSTNAME/api/sonar/explanation-requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Request Parameters

Path Parameters

Key	Type	Description	Note
request_guid	String	Explanation request identifier	36-char GUID

Request Body Parameters

Key	Required	Type	Description
type	Yes	String	Explanation type. One of `EXPLANATION`, `MANAGER_COMMENT`, or `AUDITOR_COMMENT`
status	Yes	String	Target status. One of `SUBMITTED`, `MANAGER_REJECTED`, `MANAGER_CLOSED`, `AUDITOR_SUBMITTED`, `AUDITOR_REJECTED`, or `AUDITOR_CLOSED`
result	Yes	Integer	Review result. `0` for normal, `1` for violation
content	Yes	String	Explanation or comment text
token	No	String	Explanation token used for guest access. Token issued by email to the employee or the manager

Success Response

{}

Error Responses

Missing required parameter

HTTP status code 400

{
  "error_code": "null-argument",
  "error_msg": "content should be not null"
}

Explanation request does not exist

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "no-permission"
}

Submission is not allowed in the current state

HTTP status code 500. The error_msg is one of the reason codes returned by Check Explanation Submittability.

{
  "error_code": "illegal-state",
  "error_msg": "after-expired-at"
}

Caller is not assigned as the reviewer

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "not-employee"
}

Permission denied or invalid token

HTTP status code 500

{
  "error_code": "illegal-state",
  "error_msg": "no-permission"
}