Create Submission

Purpose

To create a submission record, i.e., submit a candidate to the client/hiring manager through an API request.

Submissions sub-module

The Submissions sub-module is a sort of intermediary module that exists to store information related to each candidate submission made to Clients-contacts/Hiring Managers. When a candidate is submitted, a record is automatically created in the submissions sub-module and the client-contact's/hiring manager's review is stored within it contextually.

Request URL

https://recruit.zoho.com/recruit/v2/Submissions

Note: To create a single record, include just one JSON object in your input with the necessary keys and values.

Request Method

POST

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 DELETE - Delete records in the module

Parameters

Parameter Name	Data Type	Description	Possible Values
Candidate_Name*	String	The unique ID of the Candidate who is being submitted to the Client (or) Hiring Manager.	100001000000043143
Client_Name* (or) Department_Name*	String	The unique ID of the Client or Department for which the Candidate is being submitted.	100001000000042459
Job_Opening_Name*	String	The unique ID of the Job Opening for which the Candidate is being submitted.	100001000000046547
Submitted_To*	JSONArray	Staffing Agency edition: List of contacts the candidate is being submitted to. Corporate HR edition: The hiring manager the candidate is being submitted to.	Staffing Agency Edition "Submitted_To": [{ "name": "Graham Hancock", "id": "100001000000026793" }, { "name": "Robert Wilson", "id": "100001000000026794" }] Corporate HR Edition "Submitted_To": "100001000000042433"
Application_Name (optional)	String	The name of the application for which you wish to create a submission. If the Application_Name parameter is passed in the request, then both Job_Opening_Name and Candidate_Name parameters become optional.	100001000000042437
$medium*	String property	This value denotes the medium through which the submission was made, i.e, whether the submission was made via email or shared to the contact's client portal account. Note: The value of the $medium parameter can be passed as Share only if you are using the Staffing Agency edition of Zoho Recruit as it shares the candidate to the contact's client portal account. The $description parameter can be used to provide additional details/context to the contact you are sharing the candidate with.	Email/Share
$mail_content (if $medium = Email)	JSONObject property	The following properties can be included to this parameter; from_address reply_to_address cc_address bcc_address subject description template_id * editor_mode isSeparatEmail Note: If you are submitting candidates in bulk and the isSeparateEmail property is included under the $mail_content parameter, then each submission is sent as a separate email.	{ "from_address": "robert.bauer@zylker.com", "subject": "Candidate Submission for Accountant \| Zylker", "description": "Please find the candidate's details attached with this email.", "template_id": "100001000000021175" }
Description (if $medium = Share)	String	The comments provided while submitting candidates via the Share option. Character Limit: 32000	"Please consider these 3 candidates for the Accountant position."

Click here to see the list of Standard Fields for the Submissions sub-module.

Possible Errors

HTTP Status	Error Code	Message	Reason
400	RECORD_LOCKED	Actions aren't allowed for locked records. Unlock the record and try again	This error is thrown if the associated candidate (or) job opening is locked.
400	NOT_APPROVED	record not approved	This error is thrown if the associated candidate (or) job opening is involved in an approval process.
400	RECORD_LOCKED	Record has been locked from processing	This error is thrown if the associated candidate (or) job opening is locked from processing based on GDPR guidelines.
400	INVALID_DATA	You cannot add submission record since it is locked in blueprint.	This error is thrown if the associated candidate (or) job opening is involved in a blueprint process.
400	INVALID_DATA	api_name: Client_Name/Candidate/Job Opening message: invalid data	This error is thrown if the Candidate, Client or Job Opening name included in your request is invalid.
400	INVALID_DATA	api_name: template_id message: invalid data	This error will be thrown if the template_id included in your request is invalid.
400	UNCONFIRMED_USER	unconfirmed from address	This error will be thrown if the From address used to submit candidates is unconfirmed.
400	INVALID_DATA	api_name: Submitted_To message: invalid data	This error is thrown if the value passed for the Submitted_To parameter is invalid.
400	MANDATORY_NOT_FOUND	required field not found	This error is thrown if not all mandatory parameters are included in your request.
403	FEATURE_NOT_SUPPORTED	your edition doesn't support this feature	This error is thrown if you pass $medium as Share in your request and your edition is Corporate HR.
403	FEATURE_DISABLED	client portal disabled	This error is thrown if you pass Share as the value for the $medium parameter in your request but Client portal is disabled.

Sample Request

Copiedcurl "https://recruit.zoho.com/recruit/v2/Submissions" 
-X POST
-d "@create_submission.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

In the request, "@create_submission.json" contains the input data.

Sample Input - Submit to Client (Email)

Copied{
    "data": [{
        "Submitted_To": [{
                "name": "Graham Hancock",
                "id": "100001000000026793"
            },
            {
                "name": "Robert Wilson",
                "id": "100001000000026794"
            }
        ],
        "Job_Opening_Name": "100001000000049655",
        "Candidate_Name": "100001000000046266",
        "Client_Name": "100001000000026759",
        "$medium": "Email",
        "$mail_content": {
            "from_address": "patricia.b@zylker.com",
            "subject": "Candidate Submission | Accountant",
            "description": "Greetings, I've attached the profile of a potential candidate for the Accountant position in your company. Regards, Patricia Boyle",
            "template_id": "100001000000000025"
        }
    }]
}

Sample Input - Submit to Client (Share)

Copied{
    "data": [{
        "Submitted_To": [{
                "name": "Natasha Palmer",
                "id": "100001000000026793"
            },
            {
                "name": "Samuel Pearce",
                "id": "100001000000026794"
            }
        ],
        "Job_Opening_Name": {
            "name": "Accountant",
            "id": "100001000000049653"
        },
        "Candidate_Name": {
            "name": "Daniel Brady",
            "id": "100001000000046266"
        },
        "Client_Name": {
            "name": "Zylker",
            "id": "100001000000026759"
        },
        "$medium": "Share",
        "description ": "Please review this candidate 's profile for accountant role.",
    }]
}

Sample Input - Submit to Hiring Manager (Email)

Copied{
    "data": [{
        "Submitted_To": "20174000000424001",
        "Job_Opening_Name": "20174000000429954",
        "Candidate_Name": "20174000001736004",
        "Department_Name": "20174000000429807",
        "Description": "Please review this candidate submitted for the System Administrator role.",
        "$medium": "Email",
        "$mail_content": {
            "from_address": "aaron.browm@zylker.com",
            "subject": "Candidate Submission | System Administrator",
            "template_id": "20174000001767010"
        }
    }]
}

Sample input

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "details": {
                "Modified_Time": "2024-12-07T16:34:58+05:30",
                "Modified_By": {
                    "name": "Robert Bauer",
                    "id": "100001000000021522"
                },
                "Created_Time": "2024-12-07T16:34:58+05:30",
                "id": "100001000000069054",
                "Created_By": {
                    "name": "Robert Bauer",
                    "id": "100001000000021522"
                }
            },
            "message": "record added",
            "status": "success"
        }
    ]
}