✅ Purpose

This guide provides job board platforms with clear instructions on integrating with PeopleForce using only an API key. It outlines the required API endpoints, integration workflows, and best practices for synchronizing job postings and candidate applications.

This is different from career site integration. This guide will be interesting for local and international job board sites like indeed.com, where different companies can post their job opening and candidates can apply.

If you a company who has their own career site as a part of their company website to show their job openings and you would like to integrate it, please refer to Own career site integration

⚙️ Integration workflow

Customer essential tasks:

• Publishing a job from PeopleForce to your platform.
• Receive candidate applications and sync them back to PeopleForce.

Suggested customer setup flow:

1. Add an input field in your platform settings where customers can insert their PeopleForce API key.
2. When a customer creates a job posting, allow them to select from open PeopleForce vacancies. Pre-fill job details using PeopleForce data.
3. After publishing, route the applicant data back to the correct PeopleForce vacancy and mark the source accordingly.

🔑 Getting started: API Key generation

1. Log in to PeopleForce and go to Settings ➔ Security ➔ API keys.
2. Generate a new API key.
3. Copy and store the key securely.

Note: One API key can be used across multiple accounts of one customer (e.g., different departments or business units).
➡️ View the authentication guide: https://developer.peopleforce.io/v3.0/docs/authentication

Importing job data from PeopleForce

1. Prompt the customer to enter their API key in settings to connect their PeopleForce account.
2. When opening or creating a new vacancy, suggest selecting from existing PeopleFoce vacancies
3. Use the endpoint /api/public/v3/recruitment/vacancies to retrieve all open vacancies. + links
4. Display the job list for customer selection in published state: state=opened
5. Then, call get the selected vacancy details using /v3/recruitment/vacancies/{id} endpoint
6. When customer confirms their selection, perform full import of job details (title, description, recruiter, salary, etc.).

Vacancy data mapping.

You can either:

• Auto-fill your job form using the imported vacancy data. This will require pre-mapping of Vacancy data fields between your system and PeopleForce.
• or allow customers to manually map job fields to existing PeopleForce data.

Submitting candidates to PeopleForce

When a candidate applies:

1. Collect candidate information: name, email, phone, CV file, cover letter text etc.
2. Send data to PeopleForce using the /api/public/v3/recruitment/candidates endpoint, linking it to the correct vacancy.
3. Include source=platform_name for tracking in reports.
4. Use applications parameter to specifically assign candidate to the vacancy stage.
5. When the same candidate applies to another vacancy at the same company, assign it to another vacancy with
6. Update candidate API method api/public/v3/recruitment/candidates/{id} using the same candidate ID and updating the applications section

Candidate data handling

• Duplicate detection: PeopleForce auto-checks for duplicates by email and CV file (phone number support coming soon).
• If a duplicate is found, candidate information is automatically updated.
• Manual updates via UI are also possible.

🔍 Supported fields: https://developer.peopleforce.io/v3.0/reference/post-recruitment-candidates

What to do if a candidate exists?

You can update it or assign it to a vacancy.
To update a candidate use Update a candidate.
To assign candidate to a vacancy use Create a vacancy application.

🚀 Test environment

To ensure a smooth rollout:

1. Request access to the PeopleForce Test environment.
2. Use test data to simulate job sync and candidate submissions.
3. Once integration is complete:
   1. Schedule a live demo with the PeopleForce team.
   2. Share access to sandbox in your system for QA review.

ℹ️ Best practices

• Validate the API key before initiating syncs.
• Clearly mark PeopleForce-originated jobs in your interface.
• Require applications to be submitted via your forms (not via email or redirects) to ensure complete data capture.
• Log API errors and retry failed requests automatically.

✏️ Contact & support

For test access, technical support, or feedback, contact us https://peopleforce.io/partners

Happy integrating! ✨