Business systems

The SAP SuccessFactors OData API

How SAP SuccessFactors' OData API works and how to test it — API servers and company IDs, Basic and OAuth SAML bearer sign-in, the entities HR integrations use, effective dating with asOfDate, paging, upsert answers that hide errors, and testing safely.

SAP SuccessFactors holds a company's people: who works there, in which job, for which manager, on what pay. Payroll, IT accounts, learning systems and reports all read it, and a few write back. They do it through its OData API. If you've read OData, the API of business systems, you know the shape already. This lesson is what SuccessFactors adds: where its API lives, how it signs in, effective dating, and an answer that says 200 while a record failed.

Where the API lives

Each SuccessFactors customer has a company ID and lives in a data center. The API is on that data center's API server, not the address you log in to in a browser:

https://<api-server>/odata/v2/

SAP publishes the list of API servers; your SuccessFactors administrator knows which one is yours and which is your test instance. Most of the API is OData v2. Some newer areas are v4, each with its own address.

Signing in

  • Basic: the user name is user@companyID, with the user's password. It's simple for a first look, but SAP is retiring Basic sign-in for its APIs, so don't build on it.
  • OAuth 2.0 with a SAML bearer assertion: the way SAP recommends. An administrator registers your client in Admin Center → Manage OAuth2 Client Applications, with an X.509 certificate. Your test makes a SAML assertion for the API user, signed with that certificate, and exchanges it at https://<api-server>/oauth/token (with grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer, client_id, company_id and the assertion). You get a Bearer token back. APITestCenter does this for you: pick OAuth 2.0 → SAML 2.0 bearer.

The API user's permissions (role-based permissions) decide which entities and fields come back. A field the user may not see is left out, not refused, so a test run as an admin passes and the integration user's run doesn't.

The entities HR integrations use

EntityHolds
Userthe basic profile: user ID, name, email, manager, department
PerPerson, PerPersonalthe person, and their personal details over time
EmpEmploymentan employment: start date, end date
EmpJobthe job: position, department, manager, location, over time
FODepartment, FOCompany, FOLocationthe organization: departments, legal companies, locations

$metadata describes them all, and the full one is very large, so ask for one entity's: GET /odata/v2/EmpJob/$metadata. Admin Center → OData API Data Dictionary shows the same, readably.

Add $format=json (or the header Accept: application/json): without it, SuccessFactors answers in XML.

GET /odata/v2/User?$select=userId,firstName,lastName,department&$top=100&$format=json

Effective dating: which version of the truth?

Jobs, personal details and the organization change over time, and SuccessFactors keeps every version, each valid from one date to another. These entities are effective-dated. Ask for EmpJob and you get each person's job as of today. To see a different day, or the history:

GET /odata/v2/EmpJob?asOfDate=2025-01-31&$filter=userId eq '1001'
GET /odata/v2/EmpJob?fromDate=2024-01-01&toDate=2024-12-31&$filter=userId eq '1001'

This is where tests of HR integrations most often go wrong:

  • A test that passes today can fail next month, when a future-dated change (a promotion entered in advance) becomes today's version. Fix the date with asOfDate when the test needs a stable answer.
  • A payroll sync for last month should ask for last month, not for today.
  • A new hire with a start date next week isn't in today's EmpJob yet.

Paging

Answers come a page at a time, with the next page's address in __next (d.__next in v2 JSON). Follow it until there's none. Ask for $inlinecount=allpages to get the total in __count, as text. For large reads, SuccessFactors also offers snapshot paging (paging=snapshot) on entities that support it, so records that change while you read don't shift between pages.

Writing, and the 200 that hides an error

Changes are usually sent to one function, upsert (create, or change if it exists):

POST /odata/v2/upsert?$format=json
{ "__metadata": { "uri": "User('1001')" }, "email": "new.address@example.com" }

It answers 200 even when the record failed. The real result is in the body, one entry per record:

{ "d": [ { "key": "User/userId=1001", "status": "ERROR", "message": "Invalid email address", "httpCode": 400 } ] }

So never test an upsert by its status code alone. Check that every entry's status is "OK", and that the record reads back changed.

Testing safely

  • Use the test instance. SuccessFactors holds personal data, and a test that writes to production changes real people's records.
  • Agree load tests with the administrator (and SAP, for anything large). The instance is shared by the whole company, and heavy API use slows it for everyone.
  • Keep personal data out of test files and reports: read IDs and counts, not names and salaries, unless the test needs them.

What to test

  • Sign-in as the integration's API user, with its permissions, and a 401 with a wrong password or assertion.
  • The fields you read are still there: check the entity's $metadata, and that a field the user can't see is handled when it's missing.
  • Effective dating: asOfDate on the date your integration means, including future-dated changes and new hires.
  • Paging: the count from $inlinecount matches what you read through __next.
  • Upserts: every entry's status is "OK", not just the 200.
  • v2 shapes: rows in d.results, dates as /Date(…)/, numbers as text.

Key takeaways

  • The API is on your data center's API server at /odata/v2; the user name for Basic is user@companyID, but use OAuth 2.0 SAML bearer.
  • Add $format=json, and ask one entity for its $metadata.
  • Jobs and personal details are effective-dated: you get today's version unless you say asOfDate, or fromDate and toDate.
  • Upsert answers 200 even when a record fails. Check each entry's status.
  • Test in the test instance: it's people's personal data.

In the app: Connect SuccessFactors and browse its entities · Templates · Checks on JSON fields

SAP and SuccessFactors are trademarks of SAP SE. APITestCenter works with its API and isn't endorsed by SAP.

Next: Glossary, A to Z

A question these lessons don’t answer? Write to support@apitestcenter.com — we add lessons for the questions people ask.