Developer guide to get employee data from SAP Success Factors API

Introduction

This article is part of our in-depth series on the SAP SuccessFactors API, focusing on how to retrieve employee data efficiently and securely.
If you’re working with SAP SuccessFactors for HR management or employee records, understanding how to interact with its API is essential.

We’ll walk through authentication, fetching single or bulk employee data, common errors, and best practices.
You can also explore our comprehensive guide to the SAP SuccessFactors API here.

How to Get Employee Data from SAP SuccessFactors API

Prerequisites

Before you begin, ensure the following:

• Access to your SAP SuccessFactors instance.
• An OAuth client registered in SuccessFactors Admin Center, with an X.509 certificate uploaded for it (SuccessFactors does not support a plain client ID/secret credential flow for the OData API).
• A Python environment with the requests library installed.

API Endpoints

• Single Employee Data: /odata/v2/PerPerson({employeeId})
• All Employees Data: /odata/v2/PerPerson

Step-by-Step Guide

1. Authenticate Using OAuth 2.0

SuccessFactors' OData API does not accept a standard client_credentials request with a client ID and secret. It requires the SAML 2.0 bearer assertion grant: you sign a SAML assertion with the private key matching the X.509 certificate registered on your OAuth client, then exchange that signed assertion for an access token. There is no separate refresh token in this flow. When a token expires, you sign and exchange a new assertion.

import requests
 
token_url = 'https://your-instance.successfactors.com/oauth/token'
client_id = 'your_client_id'          # the OAuth client ID registered in Admin Center
company_id = 'your_company_id'
signed_saml_assertion = 'your_signed_saml_assertion'  # obtained from your IdP or a signing routine
 
response = requests.post(
    token_url,
    data={
        'client_id': client_id,
        'company_id': company_id,
        'grant_type': 'urn:ietf:params:oauth:grant-type:saml2-bearer',
        'assertion': signed_saml_assertion,
    }
)
 
access_token = response.json().get('access_token')

Generating and signing the SAML assertion itself typically means either pulling it from your identity provider or using a small XML-signing routine with your certificate's private key (SAP publishes a reference implementation for this). The snippet above assumes you already have a valid signed assertion string; it is not something a few lines of requests code can generate on its own.

2. Retrieve Data for a Specific Employee

Use the employee’s ID to fetch their details.

employee_id = '12345'
headers = {'Authorization': f'Bearer {access_token}'}
url = f'https://your-instance.successfactors.com/odata/v2/PerPerson({employee_id})'

response = requests.get(url, headers=headers)
employee_data = response.json()

3. Retrieve Data for All Employees

Fetch a list of all employees within your organization.

url = 'https://your-instance.successfactors.com/odata/v2/PerPerson'
response = requests.get(url, headers=headers)
all_employees_data = response.json()

Common Pitfalls to Avoid

1. Incorrect base URL or endpoint path: Always verify your regional endpoint.
2. Assuming a standard client_credentials flow works: SuccessFactors requires the SAML bearer assertion grant with a certificate-backed OAuth client, not a plain client ID and secret. Code copied from a generic OAuth 2.0 tutorial will not authenticate.
3. Expired access tokens: There is no refresh token in this flow. Sign and exchange a new SAML assertion when the current token expires.
4. Missing permissions: Ensure your API client has the right scopes to access employee data.
5. Incorrect employee ID format: Use the correct identifier as per your instance configuration.
6. Ignoring pagination: Large datasets require handling $top and $skip parameters.
7. Overlooking rate limits: SAP enforces API throttling; design retries with backoff.
8. JSON parsing issues: Validate responses before extracting nested data fields.

FAQs

1. What is the base URL for SAP SuccessFactors API?
The base URL depends on your instance and data center region, usually in the format:
https://<your-instance>.successfactors.com.

2. How do I obtain API credentials?
Register an OAuth client in SuccessFactors Admin Center and upload an X.509 certificate for it. SuccessFactors uses this certificate to verify signed SAML assertions rather than issuing a plain client secret for the OData API.

3. What data format does the API return?
The API returns data in JSON format, which is easy to parse in most programming languages.

4. Can I filter employee data?
Yes. Use OData query options like $filter, $select, and $orderby for granular results.

5. How do I handle pagination for large datasets?
Use $top and $skip parameters to fetch results in batches.

6. Is there a rate limit for API calls?
Yes. Rate limits vary by license type; refer to the official SAP SuccessFactors API documentation.

7. How do I refresh an access token?

There is no refresh token grant in the SAML bearer flow. Sign a new SAML assertion with your certificate's private key and exchange it at the token endpoint the same way you did to get the original token.

‍

Knit for SAP SuccessFactors API Integration

Integrating directly with SAP SuccessFactors can be time-consuming, from managing tokens to maintaining ongoing API updates.
With Knit, you can connect once and access SAP SuccessFactors data effortlessly through a unified, secure interface. Knit automates authentication, authorization, and ongoing maintenance, allowing your teams to focus on building experiences instead of managing integrations.

Explore how Knit simplifies SAP SuccessFactors integration here.