| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Status
Jobs can be one of several statuses
draft- Unpublished and still being actively worked onpending_approval- In process in a sign off workflowopen- Open and accepting applicationsclosed- Created but not accepting new applicationsarchived- Closed to new applications, and no longer relevant
You can pass any of these values for the status. If you create a job with the status of open it will skip any sign off workflow that it would have gone through had you created the job directly in the UI. If you create the job with a status of pending_approval it will trigger a sign off workflow if one should apply, otherwise the job will immediately be moved to open
Required attributes
The attributes required to create a job change depending on the status of the created job. A draft job requires less information than an open job
Required attributes
All jobs being created require a title, status and selected_hiring_workflow_id you can get a list of your hiring workflows along with their ID from the hiring workflow endpoint.
Open job attributes
In addition to the above when creating an open job you must also provide description, employment_type,external_key_responsibilities_header, key_responsibilities and visibility
Required relationships
When creating a new job the only required relationship is the structure_link this represents the part of the company that the job is associated with (the location, department etc.). You can get a list of available structure links from the structure link endpoints in the API
All attributes
Please refer to the Request Body Params section below to see all available fields.
Job-specific visibilities
If you want to define the users that will have direct visibility over the job you can provide an array of user emails for users_emails_with_job_level_visibility. This sets job visibility to exactly the list of emails provided. This is a full replacement - you must include every user who should have job level visibility, not just new additions. You can use the GET endpoint and include users_emails_with_job_level_visibility as an extra attribute to get the list of current users with job level visibility.
⚠️ Any user whose email is omitted from the array will have their job level visibility removed.
Note that this does not impact the visibility users inherit over the job via the assigned structure link.
Submitting custom attributes along with an application
Custom attributes are this jobs answers to any custom fields that have been defined. Each custom attribute relates to a specific custom field, all of which can be retrieved using the custom field endpoint.
A temp-id field is required when detailing the answer under the relationships key of the POST body. This temp-id can be any UUID and will help to:
- Connect relevant sections of the payload.
- Associate in-memory objects with the ids returned from the server.
- Make it easy to associate any errors returned from failed requests.
See the Draft Job (with custom fields) example for more details on how to create a custom attribute along with the job.
Examples
{
"data": {
"type": "jobs",
"attributes": {
"title": "Assistant to the Regional Manager",
"status": "draft",
"selected_hiring_workflow_id": "1"
},
"relationships": {
"structure_link": {
"data": {
"type": "structure_links",
"id": "1"
}
},
}
}
}{
"data": {
"type": "jobs",
"attributes": {
"title": "Assistant to the Regional Manager",
"status": "open",
"description": "Seeking an enthusiastic and dedicated individual to assist the Regional Manager in daily office duties at a leading paper supply company.",
"employment_type": "full_time",
"external_key_responsibilities_header": "Key Assistant Duties",
"key_responsibilities": "Supporting the Regional Manager in daily operations, coordinating office activities, ensuring efficient workflow, and liaising between departments.",
"visibility": "external",
"selected_hiring_workflow_id": "2"
},
"relationships": {
"structure_link": {
"data": {
"type": "structure_links",
"id": "2"
}
},
}
}
}{
"data": {
"type": "jobs",
"attributes": {
"ask_for_address": true,
"ask_for_date_of_birth": true,
"ask_for_linkedin_profile": false,
"ask_for_middle_name": true,
"benefits": "Health insurance, paid vacation, company discount on paper products",
"blind_screening": true,
"company_name_override": "Dunder Mifflin",
"compensation_currency": "USD",
"compensation_frequency": "year",
"compensation_maximum": 60000.00,
"compensation_minimum": 40000.00,
"cover_letter_requirement": "optional",
"custom_country": "United States",
"custom_county": "Lackawanna",
"custom_town": "Scranton",
"deadline_on": "2024-05-01",
"description": "Sales position at a leading paper company with a focus on client management and team collaboration.",
"diversity_monitoring": true,
"draft_job_additional_information": "Familiarity with paper products is a plus",
"employment_type": "full_time",
"experience_level": "director",
"external_benefits_header": "Dunder Mifflin Employee Benefits",
"external_key_responsibilities_header": "Primary Sales Responsibilities",
"external_skills_knowledge_expertise_header": "Required Skills and Expertise",
"facebookjobs": true,
"headcount_maximum": 5,
"headcount_maximum_enabled": true,
"hiring_manager_user_email": "[email protected]",
"include_in_indeed": true,
"include_in_linkedin_rss": false,
"is_compensation_visible": true,
"is_remote_with_location_restrictions": false,
"key_responsibilities": "Developing new client relationships, maintaining existing accounts, achieving sales targets",
"linkedin_company_id": "99999",
"monster": true,
"notify": true,
"personal_summary_requirement": "optional",
"recruitment_manager_user_email": "[email protected]",
"referral_amount": 500.00,
"referral_currency": "USD",
"referral_details": "Referral bonus for introducing new talents",
"referrals_enabled": true,
"reporting_to": "Regional Manager",
"require_phone": true,
"requisition_id": "3",
"resume_requirement": "required",
"selected_hiring_workflow_id": "3",
"skills_knowledge_expertise": "Excellent communication and negotiation skills, self-motivated",
"status": "open",
"talentdotcom": false,
"title": "Paper Sales Representative",
"visibility": "external",
"workplace_type": "hybrid",
"ziprecruiter": true
},
"relationships": {
"structure_link": {
"data": {
"id": "1",
"type": "structure_links"
}
}
}
}
}{
"data": {
"type": "jobs",
"attributes": {
"title": "Regional Manager",
"status": "draft",
"selected_hiring_workflow_id": "1"
},
"relationships": {
"structure_link": {
"data": {
"type": "structure_links",
"id": "1"
}
},
"custom_attributes": {
"data": [
{
"type": "custom_attributes",
"method": "create",
"temp-id": "1"
}
]
}
}
},
"included": [
{
"type": "custom_attributes",
"temp-id": "1",
"attributes": {
"text_value": "World's Best Boss Mug"
},
"relationships": {
"custom_field": {
// Custom field must already exist. You can create custom fields
// in the application, or via the API:
// https://developers.pinpointhq.com/reference/post-custom-fields
"data": {
"id": "1",
"type": "custom_fields"
}
}
}
}
]
}