Integrating SAP Successfactors with Peoplebox

Overview

This integration pulls employee and organizational data from SAP SuccessFactors using OData v2 APIs. The integration relies on two endpoints:

1. EmpEmployment API

2. User API

API Endpoints Used

All API calls should be made against your company-specific SuccessFactors base URL:

https://<your-successfactors-api-host>/odata/v2/

1. EmpEmployment API

GET /odata/v2/EmpEmployment

Full Query Used:

<https://apiXX.sapsf.com/odata/v2/EmpEmployment>
?$expand=userNav/manager,jobInfoNav/departmentNav
&$select=
userNav/userId,
userNav/firstName,
userNav/lastName,
userNav/email,
userNav/title,
userNav/hireDate,
userNav/department,
userNav/manager/userId,
userNav/manager/email,
jobInfoNav/departmentNav/externalCode,
empJobRelationshipNav/relationshipNav/externalCode,
empJobRelationshipNav/relUserNav/email

Purpose

• Primary employee data source

• Department mapping via departmentNav.externalCode

• Employee relationship mapping via empJobRelationshipNav/relationshipNav

2. User API

GET /odata/v2/User

Full Query Used

<https://apiXX.sapsf.com/odata/v2/User>
?$select=
userId,
firstName,
title,
hireDate,
lastName,
email,
department,
division,
manager
&$expand=manager

Purpose

• Manager hierarchy mapping

Permissions

Ensure the API user configured in SuccessFactors has the following permissions:

Required Permissions:

• Employee Central API (OData)

• Read access to:

  • Employee Employment (EmpEmployment)

  • User entity (User)

  • Job Information

  • Department data

• Permission to access:

  • Manager relationships

IP Whitelisting (Optional)

In case you have enabled IP whitelisting in your SuccessFactors instance, you must whitelist Peoplebox servers to allow secure access.

Steps

1. Go to Admin Center.

2. Navigate to:

Manage OAuth2 Client Applications (if OAuth used)

OR

API Center / Integration Settings

1. Locate Allowed IP Addresses / IP Restriction Settings.

2. Add your Peoplebox server IP to the whitelist.

   Contact Peoplebox support to obtain the latest list of static IPs.

Notes

• Ensure no wildcard blocking rules override these entries.

• If using VPN or proxy restrictions, allow outbound access to `apiXX.sapsf.com

Client Application Setup

Step 1: Create a client

1. Log in to your SAP SuccessFactors account as an administrator.

2. Go to Admin Center and navigate to API Center > OAuth Configuration for OData.

3. Select Register Client Application.

4. Fill in the following details on the application registration page:

   • Company: Your organization’s name.

   • Application Name: Assign a unique identifier for your OAuth client.

   • Application URL: Provide a URL that can direct users to additional details about the application. This is primarily for 3-legged OAuth, which isn’t currently supported.

   • X-509 Certificate: Upload the certificate that aligns with the private and public keys used in the OAuth 2.0 process. Details on how to generate certificate

5. Click Register to save your application.

6. Once registered, you can view the generated API key by selecting the View option in the application list.

Step 2: Share Required Details

After completing the client application setup, share the following details with support@peoplebox.ai to enable the integration:

• Client ID: The API key created during the client application registration.

• Client Secret: The private key content (from the .pem file) generated during the setup.

• API Server: The URL for your account’s API server. [List of API server URLs here].

• Company ID: This can be found by clicking your profile picture in SAP SuccessFactors and selecting Show version information. Look for the “Company ID” in the popup.

• Username: Your username, shown in parentheses beside your profile image.

Once you provide these details, the Peoplebox team will set up the connection for you. 🎉