API authentication

Generating an API key

PeopleForce supports two types of API key depending on what use case. It is very important to choose the type of API key that matches your goal.

Company API key - provides full access to the PeopleForce API and employee data with minimal restrictions.
Career API key - can be used to display vacancies on your public website. These API keys can be used on a public-facing website.

To create an API key, go to Settings → Open API keys (bottom of the page) → Generate API key.

Company API key

Creating a Company API key allows users with this key to retrieve or change data in your company account via PeopleForce API.

This API key can be used to create any kind of system integration to PeopleForce. Please be aware that this provides access to all data in PeopleForce with minimal limitations. Only use this as part of a system-to-system integration, and never use this on a public-facing website. Only give these API keys to trusted systems developers.

The following restrictions are possible:

People compensation: Limit users from viewing or editing people compensation
Vacancy salary range: Limit users from viewing or editing vacancy salary ranges
Candidate desired salary: Limit users from viewing or editing candidate desired salary
Candidate sensitive fields: Limit users from viewing or editing candidate sensitive fields
IP Addresses: Callers to the API can be limited to IP addresses on the allow-list. This allows only users from particular IP addresses such as office IT computers or home PCs.

Career API key

Creating a Career API key allows you to retrieve vacancies from PeopleForce to create a custom Careers page on your own website.

This API key can be added to your public-facing website and it is limited to non-sensitive vacancy specific information.

How to use key

To use API key you need to pass it as a part of the request.

Include the key in a header parameter called X-API-KEY.

Example: X-API-KEY: 123

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Disabling an API key

API keys can be disabled on the API key list page. This is useful in situations when you need to temporarily disable an API key from working without permanently deleting it.

Revoking key

If you no longer need an API key, it can be deleted. Warning: this is a one-way action. Once an API key is deleted it cannot be recreated. Any system integrations using that API key will no longer work. Be sure that all integrations are accounted for before deleting an API key.

To delete an API key go to Settings → Open API keys (bottom of the page) → Find your key in the list of keys and click Delete.

Key will be revoked immediately and access via API using this API key will immediately terminate.

Troubleshooting

401 Unauthorized

If you receive a response of 401 Unauthorized, please double-check that your API key was copied correctly and try again.

{
    "message": "Bad Credentials"
}

403 Forbidden

Your role doesn't have enough permission to perform this action. This usually will be only if you are restricted from receiving info about Compensations for employees.

404 Not Found

The resource could not be found. Please check that your request is referring to an existing object.

422 Unprocessable Entity

There are validation errors in some fields. Please refer to the documentation to check the required fields and validation rules.
The response body will include all errors:

{
  "success": false,
  "errors": [
    "Field name can't be blank",
  ]
}

500 Internal Server Error

There was a problem with our server. Try again later or contact support to learn more.