post https://{subdomain}.pinpointhq.com/api/v1/jobs
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
These are all possible attributes available when creating a job
| Attribute | Data type | Required | Default | Additional information |
|---|---|---|---|---|
| title | string | Yes | The job title shown internally and externally | |
| employment_type | string | Yes | Must be one of the following options: full_time, part_time, contract_temp, freelance, internship, permanent, fixed_term_contract, zero_hours, permanent_full_time, permanent_part_time, flexible, seasonal_full_time, seasonal_part_time, volunteer, apprentice | |
| reporting_to | string | No | Shown on the job pages on your careers site | |
| is_compensation_visible | boolean | No | false | Do you wish to show compensation information on the public job posting |
| compensation_currency | string | Only if compensation_maximum, compensation_minimum or compensation_frequency are provided | Must be a valid currency code (e.g. USD, EUR etc.) | |
| compensation_frequency | string | Only if compensation_maximum, compensation_currency or compensation_minimum are provided | Must be one of hour, day, week, two_weeks, month or year and represents the time unit the compensation is for | |
| compensation_minimum | number | Only if compensation_maximum, compensation_currency or compensation_frequency are provided | ||
| compensation_maximum | number | Only if compensation_minimum, compensation_currency or compensation_frequency are provided | ||
| deadline_on | date | No | The date that the job will automatically close. Must be in the future and must be in ISO8601 format (yyyy-mm-dd) | |
| workplace_type | string | No | onsite | Must be one of onsite, hybrid or remote |
| ask_for_address | boolean | No | true | Should applicants be forced to provide an address when applying? |
| ask_for_date_of_birth | boolean | No | false | Should applicants be asked their date of birth when applying (will never be required) |
| require_phone | boolean | No | false | Should applicants be forced to provide a phone number when applying |
| ask_for_linkedin_profile | boolean | No | false | Should applicants be asked for a linkedIn profile link when applying |
| blind_screening | boolean | No | false | Do you want to apply anonymised screening to this role and hide PII |
| resume_requirement | string | No | optional | Must be one of optional, required, not_required |
| personal_summary_requirement | string | No | optional | Must be one of optional, required or not_required |
| visibility | string | Yes | Must be one of external, internal or confidential | |
| diversity_monitoring | boolean | No | false | Do you want to ask additional equality monitoring questions on the jobs application form |
| headcount_maximum_enabled | boolean | No | false | Do you want to limit the number of people that can be hired for this role |
| headcount_maximum_enabled | number | Only if heacount_maximum_enabled is true | The maximum number of hires that can be made on this job | |
| selected_hiring_workflow_id | string | Yes | The ID of the hiring workflow this job is assigned to | |
| description | string | Yes | Public description for the job | |
| external_key_responsibilities_header | string | Yes | Header for the key responsibilities section of the job posting | |
| key_responsibilities | string | Yes | Key responsibilities section of the job posting | |
| external_skills_knowledge_expertise_header | string | No | Header for the skills sections of the job posting | |
| skills_knowledge_expertise | string | No | Skills section of the job posting | |
| external_benefits_header | string | No | Header for the benefits section of the job posting | |
| benefits | string | No | Benefits section of the job posting | |
| referrals_enabled | boolean | No | Do you want to enable referrals for this job? | |
| referral_details | string | No | Details of the referral scheme | |
| referral_amount | decimal | No | The referral amount | |
| referral_currency | string | No | Must be a valid currency code (e.g. USD, EUR etc.) | |
| hiring_manager_user_email | string | No | Email of the User which is a Hiring Manager for the job. The User must be an Employee of the Company. An external recruiter can't be assigned as a Hiring Manager. | |
| recruitment_manager_user_email | string | No | Email of the User which is a Recruitment Manager for the job. The User must be an Employee of the Company. An external recruiter can't be assigned as a Recruitment Manager. |
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"
}
}
}
}
]
}