SAP SuccessFactors

What this connects to: the OData V2 API of SAP SuccessFactors (Employee Central and the platform), https://<api-server>/odata/v2. Every call runs as the API user the SAML assertion names, so SuccessFactors role-based permissions decide what is visible.

Start with sap_successfactors_guide (free), then the ready tools: sap_successfactors_list_users to find people and their userId, sap_successfactors_list_employee_jobs for company, department, position and manager, sap_successfactors_list_time_off for absences. For any other entity, sap_successfactors_get_entity_metadata lists its fields and sap_successfactors_query reads it.

Authentication (OAuth 2.0 SAML bearer)

1. Admin Center > Manage OAuth2 Client Applications > Register Client Application. Generate an X.509 certificate there (or upload your own), download the private key, and copy the API Key.
2. Create a SAML assertion for the API user with SAP's offline SAML assertion generator (SAP Note 3031657): token URL <api-server>/oauth/token, the API key as client id, the API user, the private key, and expireInMinutes set to how long the assertion should stay usable.
3. Fill in SF_API_URL (API server of your data center), SF_COMPANY_ID, SF_CLIENT_ID (the API key) and SF_SAML_ASSERTION. The connector exchanges the assertion at /oauth/token for an access token valid 24 hours and renews it automatically while the assertion is valid. When the assertion expires, generate a new one and paste it in. SAP retires HTTP Basic authentication for these APIs on 20 November 2026, so it is not offered.

Permissions: the API user needs Employee Central API permissions (Role-Based Permissions > Employee Central API: OData API access) and read permission on the entities and fields the agent should see.

Effective dating: EmpJob, PerPersonal, foundation objects and Position return the record valid today. Pass as_of_date, or from_date and to_date for history.

Paging and limits: a page holds at most 1000 rows; pass skip for the next page and narrow with filter and select. SAP throttles heavy API use per tenant; avoid scanning all users repeatedly, filter by lastModifiedDateTime instead.

Pitfalls: field names are case-sensitive; inactive users are excluded from User unless the filter names a status; picklist fields return codes (expand the ...Nav navigation for labels); sap_successfactors_describe_service loads the complete tenant metadata, which is large and slow the first time.