Own career site integration

Preconditions: you have generated API key.
If not, we suggest you start with API authentication

You don't have to use career site provided by PeopleForce . Whether you already have your own website with a career site or plan to build one - we've got you covered 🙌.

For the best integration, we suggest the following steps:

1. Retrieve the list of vacancies from PeopleForce
2. Create a candidate and pass it to PeopleForce
3. Assign application to a vacancy pipeline and stage
4. If the candidate already exists update the existing candidate card

Pull list of vacancies from PeopleForce

If you want to manage a list of active vacancies in one place, then it’s better to have it in PeopleForce.

To get the list of all vacancies, use https://app.peopleforce.io/api/public/v1/recruitment/vacancies You can additionally filter by vacancy status, for example, to only get open vacancies.

To learn more, check this endpoint in our API documentation: List all vacancies

Create a candidate in PeopleForce

To create an application, when a candidate applies to your career site, you will need to create a candidate first and after assign them to a vacancy. To create candidate, use following API endpoint:

https://app.peopleforce.io/api/public/v1/recruitment/candidates

Visit endpoint documentation page to learn more: https://developer.peopleforce.io/reference/post-recruitment-candidates

When an applicant is created, the applicant id will be returned. You will need it in the next step.

📘

Troubleshooting: Validation errors

Status 422 Unprocessable entity: Check response message. You might be missing required fields or passing invalid data, or data fails to be unique if required.
Email and resume file (files are checked by MDF5 hash) must be unique or empty.

What to do if a candidate exists?

You can update it or assign it to a vacancy.
To update a candidate use Create a candidate.
To assign use Create a vacancy application.
Take a look into using both in-depth below.

Assign application to a vacancy pipeline and stage

Once a candidate is created in your candidate's database, you might need to assign the candidate to a vacancy.

How do I know if I need to assign a candidate?

For example, if your candidate applied from your career site to a particular vacancy and you have a respective vacancy in PeopleForce and want to see the candidate as an applicant, then he must be additionally assigned to the vacancy.

In some cases, you might have a form like “Didn’t find the vacancy you could apply to? Send us your resume and we will contact you once we have an opening”. Such candidates don't need to be assigned to a vacancy and it’s enough for them to be just added to your candidate's database. You will be able to access and see them from the interface and can manually or via API assign if needed later. You can skip this step then.

Once you are sure that you need to assign a candidate to a vacancy, use:
https://app.peopleforce.io/api/public/v1/recruitment/vacancies/{vacancy_id}/applications
to create an application for candidates. You will have to pass candidate_id as a required field. We recommend you don’t provide applicant_state_id, then we will automatically assign candidates to the stage of your pipeline for a specified vacancy with the status “new”.
We do not recommend assigning candidates to other stages unless that is needed for the specific pipeline you are using, as it may cause unclear results for pipeline reports since some candidates will be skipping the beginning stages.

You can learn more about endpoint in our documentation: Create a vacancy application

Updating existing candidate

It could happen sometimes, that candidate that has applied via your career site is already in your candidate's database.

Upon submitting a candidate that already has the same email or resume file you will receive Status 422 Unprocessable entity as on the example below:

{
    "success": false,
    "errors": [
        "Email already exists for <a target=\"_blank\" href=\"https://test.peopleforce.io/recruitment/applicants/823535\">Hanna Polynkevych</a>"
    ]
}

In such a case, we advise you to update the existing candidate. This way you can update full name, email, source and other data to your liking or without any changes to profile assign candidate to a vacancy.

To assign a candidate to an existing vacancy follow Assign application to a vacancy pipeline and stage