Create Candidate

Create a new candidate profile.

External Documentation

To learn more, visit the Greenhouse documentation.

​

Basic Parameters

Parameter	Description
Company	The company of the candidate.
First Name	The first name of the candidate.
Last Name	The last name of the candidate.
Preferred Name	The preferred or chosen name of the candidate, when different from their legal first name.
Time Zone	The Rails-style timezone identifier of the candidate. For example: Eastern Time (US & Canada).
Title	The title of the candidate.

​

Advanced Parameters

Parameter	Description
Addresses	A json array of addresses. For example: [ { “value”: “123 Fake St.”, “type”: “home” } ]
Application	A json object creating an application for the candidate. Provide job_id to apply the candidate to a job, or prospect: true with prospect_pool_id to add them as a prospect instead. For example: { “job_id”: 12345, “source_id”: 1 }
Can Email	Select to indicate the candidate has consented to email communication.
Custom Fields	A json array of custom field objects, identified by custom_field_id or name_key, with the new value. For example: [ { “name_key”: “single_select_field_name”, “value”: 12345 } ]
Email Addresses	A json array of email addresses. For example: [ { “value”: “[e-mail]”, “type”: “work” } ]
Linked User IDs	A comma-separated list of user IDs to link to the candidate.
Phone Numbers	A json array of phone numbers. For example: [ { “value”: “222-555-4608”, “type”: “home” } ]
Social Media Addresses	A json array of social media addresses. For example: [ { “value”: “linkedin.example.com/john.locke” } ]
Tags	A comma-separated list of tags to associated with the candidate.
Website Addresses	A json array of website addresses. For example: [ { “value”: “johnlocke.example.com”, “type”: “personal” } ]

​

Example Output

{
	"candidate": {
		"id": 53883394,
		"first_name": "John",
		"last_name": "Doe",
		"preferred_name": null,
		"company": null,
		"title": null,
		"created_at": "2024-01-01T00:00:00.000Z",
		"updated_at": "2024-01-01T00:00:00.000Z",
		"can_email": true,
		"time_zone": null,
		"last_activity_at": "2024-01-01T00:00:00.000Z",
		"private": false,
		"tags": [],
		"linked_user_ids": [],
		"phone_numbers": [],
		"addresses": [],
		"email_addresses": [],
		"website_addresses": [],
		"social_media_addresses": [],
		"custom_fields": {}
	},
	"application": {
		"id": 2,
		"candidate_id": 53883394,
		"job_id": 12345,
		"status": "in_process",
		"created_at": "2024-01-01T00:00:00.000Z"
	}
}