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 (Max. 50 chars)	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 (Max. 2000 chars)	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"
        }]
    ]
}