Change Submission Status
Purpose
To add a review and change the status of a submission record through an API request.
Note:
You can only change the status of one submission at a time.
Request URL
https://recruit.zoho.com/recruit/v2/Submissions/{record_id}/actions/status
record_id - The unique ID of a submission record.
Request Method
PUT
Scope
Global Scope
scope=ZohoRecruit.modules.all
Specific Scope
scope=ZohoRecruit.modules.submission.{operation_type}
| Possible operation types |
|---|
| ALL - Create/Delete records in the module CREATE - Create records in the module |
Parameters
| Parameter Name | Data Type | Description | Possible Values |
|---|---|---|---|
Submission_Status | String | The status of the submission record | Corporate HR Edition: Approved by hiring manager (or) Rejected by hiring manager Staffing Agency Edition: Approved by client (or) Rejected by client |
Rating | Integer | The star rating given while reviewing a submitted candidate. | Value Range: [1 - 5] If the Rating is 3★ or above, you can only Approve the submission. If the Rating is 2★ or below, you can only Reject the submission. |
Reviewer_Comments | String | The comments entered while reviewing a submitted candidate. | "Candidate looks like a good fit for this job." |
| Reviewed_By | BigInt | The client-contact who reviewed your candidate submission. | 9245000006242040 |
Additional Details
The the Submission_Status parameter can only have one of two values;
Corporate HR Edition:Approved by hiring manager (or) Rejected by hiring manager.
Staffing Agency Edition:Approved by client (or) Rejected by client.The available values of the Rating parameter will change based on the value of the Submission_Status parameter.
If Submission_Status is Approved by hiring manager or Approved by client, then the allowed values for Rating are 3 to 5.
If Submission_Status is Rejected by hiring manager or Rejected by client, then the allowed values for Rating are 0 to 2.
The Reviewer_Comments parameter will become mandatory if Submission_Status is Rejected by hiring manager. The value of the Reviewer_Comments parameter can have up to 2000 characters.
If a submission has been Reviewed or Archived,then it's status cannot be changed.
Possible Errors
HTTP Status | Error Code | Message | Reason |
|---|---|---|---|
400 | INVALID_DATA | api_name: Rating message: invalid data | While reviewing a submission, the Approve and Reject options are made available based on the Rating you provide. This error is thrown if the Rating is 3★ or above and the candidate is Rejected (or) if the Rating is 2★ or below and the candidate is Approved. |
202 | RECORD_ARCHIVED | Record is archived | This error is thrown if the submission record included in your request has been archived. |
202 | STATUS_ALREADY_CHANGED | Status changed already for this Submission | This error is thrown if the status of the submission included in your request has already been changed. |
400 | INVALID_DATA | Out of range | This error is thrown if the value of the Rating parameter is not within the range of 0 to 5. |
Endpoints
CopiedPUT/{record_id}Sample Request
Copiedcurl "https://recruit.zoho.com/recruit/v2/Submissions/100001000000031070/actions/status"
-X PUT
-d "@change_submission_status.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"In the request, "@change_submission_status.json" contains the input data.
Sample Input - Corporate HR Edition
Copied{
"data": [{
"Submission_Status": "Approved by hiring manager",
"Reviewer_comments": "Looks like a great fit. Please go ahead with the hire.",
"Rating": 3
}]
}Sample Input - Staffing Agency Edition
Copied{
"data": [{
"Submission_Status": "Rejected by client",
"Reviewer_Comments": "Candidate's profile does not fit out requirements.",
"Rating": 2,
"Reviewed_By": "9245000006242040"
}]
}Sample Response
Copied{
"data": [
[{
"code": "SUCCESS",
"details": {
"Modified_Time": "2024-06-02T11:13:41+05:30",
"Modified_By": {
"name": "Robert Bauer",
"id": "100001000000026095"
},
"Created_Time": "2024-06-01T18:53:42+05:30",
"id": "100001000000031070",
"Created_By": {
"name": "Robert Bauer",
"id": "100001000000026095"
}
},
"message": "status changed",
"status": "success"
}]
]
}
