Skip to Content

Employee Central Entities and Interfacing

Through this blog I intend to cover some of the basic concepts for SuccessFactors Employee Central integration, such as entities and objects, API, load type processing parameter and other features. I won’t touch on strategy for Integration i.e. Platforms (Dell Boomi, SAP PI et al) as Integration Strategy is dependent on System landscape and it’s more of the customer IT team’s prerogative, although I hope this blog will help customers in decision-making.

What is Employee Central?

As the SuccessFactors website says it’s the next-generation core HR system (HRIS) is designed for the global enterprise workforce delivered over Cloud.

At an Object level, Employee Central broadly maintains two kind of information:

  • Organization, Pay and Job Structure Details – in Successfactors terminology this is called Foundation Objects
  • Employee Details – This covers Personal and Employment Details for Employees, known as Personal and Employment Objects respectively

There is another category of Objects, which were added recently to provide flexibility in a scenario where standard delivered Foundation Objects are not sufficient to meet customer requirements. These are known as Generic or Custom Foundation Objects, e.g. Positions for Position Management. As per their current status, generic objects are not “Integration ready” i.e. it’s not possible to import or export generic objects in an automatic manner

Update – as per the Metadata Framework (MDF) Configuration guide, MDF Objects (Generic Objects are part of MDF) are exposed through REST Based Common Object OData API. However, at this time, there is not sufficient documentation available to add details and provide reference about this feature. Never the less it shows SAP’s commitment towards making their products more open and extensible to developer community. More information on Metadata Framework can be found at Luke Marson’s blog –

What is an Entity in Employee Central?

EC stores data in multiple table structures, which are commonly known as EC Entities. There are various entities for Foundation as well as Personal/Employment Objects. The concept of entities can be best understood by relating them to SAP HCM Infotypes.

Common Foundation Objects Entities Available for Integration – Company/ Legal Entity, Business Unit, Location Group, Geozone, Location, Division, Department, CostCenter, JobCode, JobFunction, PayGroup, PayGrade, PayRange, PayComponent, PayComponentGroup, PayCalendar, EventReason, and Frequency.

Here is an example of Legal Entity Object:


Common Personal and Employment Objects Available for Integration – User, PerAddress, PerDirectDeposit, PerEmail, PerEmergencyContacts, PerNationalId, PerPerson, PerPersonal, PerPhone, PerSocialAccount, EmpCompensation, EmpEmployment, EmpEmploymentTermination, EmpJob, EmpJobRelationships, EmpPayCompNonRecurring, and EmpPayCompRecurring.

An example of EmpJob or JobInformation Object:


Properties of Entities

Effective Date and Effective Sequence – Those with some ERP experience would already be familiar with this concept. A majority of the Employee Central entities are effective dated. Effective date is a date when a given record becomes effective. It helps Employee Central track historical data accurately. Similarly there might be a scenario where multiple events are required to be recorded on same effective date for e.g. Transfer and Promotion. There is a field called Sequence Number, available in Job and Compensation Entities, which is used to identify such changes. Sequence Number should always by greater than 0

Business Keys – Each entity identifies its record uniquely by business key, which is a composite key or combination of various fields of that entity. For more details about this concept, refer Employee Central Configuration guide and Employee Central Entity Guide on the SuccessFactors Partner Portal

Purge Type – Employee Central supports two types of load: FULL and INCREMENTAL. When purgeType is set to ‘FULL’ during entity record update, Employee Central overwrites historical data for that record and inserts a new record. For ‘INCREMENTAL’ purge type, only those records that have same Effective Date and Sequence Numbers are overwritten

What is Employee Central API?

The Employee Central API is library of Employee Central entity structures exposed to the outside world. The Employee Central API covers Foundation Objects and Personal and Employment Objects. Those who don’t have programming background, a quick glance on wiki page about API would be useful – The Employee Central API allows various data manipulation and query operation on Employee Central entities.

Supported Operations – Each entity supports some or all of the following Data Manipulation and Retrieval operations through API:

  • Insert (insert) – Insert the record for specified Entity Type
  • Update (update) – Update the record for specified Entity Type
  • Upsert (upsert) – First try to update record, if record doesn’t exists (identified by Business Keys) then Insert record
  • Query (query) – Retrieve records based on Successfactors query language (SFQL). For details about SFQL refer SFAPI documentation. For now just assume that SFQL is weaker cousin of SQL
  • QueryMore (queryMore) – Query can support retrieval of only fixed number of records as specified in batchSize parameter. If there are more records then QueryMore has to be used (following Query operation).
  • Delete (delete) – Deletes the record identified by Entity Type and Business Keys

If you have access to a SuccessFactors instance with necessary permissions, precise details can be found by going to Admin Tools -> API Dictionary. Personally I feel the API dictionary is great way to learn not just about integration, but about Employee Central in general.


Entities Related to Foundation Objects starts with prefix FO_

Here is one example:


As explained above, each Entity has a set of supported operations. Each field in an entity also has different set of properties. One more point worth noting is that custom fields added to the configuration are also visible and can be used by supported operations.

Similarly Personal and Employment Objects can be accessed through API. Person Entities start with the Per prefix and Employment Entities start with the Emp prefix. Examples of these can be seen below.



In the API dictionary you would also find API(s) for Picklists, Background Objects, Adhoc Reports and a few other general objects that are part of Employee Central and the SuccessFactors BizX suite as a whole.

Let’s see one example now –

Let’s try to retrieve Personal Details (PerPersonal API Entity) for Carla Grant. For simplicity I am using soapUI to trigger the request.

Request Message. Check the SFQL, where we are retrieving fields in PerPersonal entity, filtered by “where” clause on person_id_external

Response Message

Here we have SOAP response with Personal Details about Carla Grant.


A quick note, here we see only those fields, which were in SFQL query. Your (custom) application can consume this response as needed.


As mentioned in prologue, the weblog covered some of the basic concepts about Employee Central. The Entities forms core of EC, knowing about entities would also be useful in adhoc reports, advanced reporting and other tools.

I hope this blog is helpful for consultants and customers trying to understand, integrate and extend Employee Central.


Entity Type Guide

Entity Guide – User Object


Metadata Framework (MDF)

You must be Logged on to comment or reply to a post.
  • Hi Akhil,

    Great blog and very informative. I like that both standard and custom objects can be exposed via the API, particularly MDF objects. I think it’s quite important from an integration perspective to be able to leverage these objects and when the SAP HANA Cloud Platform is more widely available it will offer greater benefits for extending the Employee Central system.

    Best regards,


    • Thanks Luke :-). I ‘ll wait for August release for more details on Common Data/ MDF API. But yes OData is definitely a positive step, not just for integration but for custom development too. Let’s see how it goes. 

    • Hi Luke. When I’m trying to create an MDF object, the first field (externalCode) with the data type Auto Number is not accepted as a business key field below & gives an error stating that “Invalid data type: AUTO_NUMBER for business key field”.

      please give any hints on this issue

  • Great job Akhil and even more impressive given that is your first blog on SCN.  Look forward to your continued contributions as there is a lot of interest in Employee Central which I expect to grow by leaps and bounds given SAP/SF investment in the product and the leadership team involved.

  • Hi Akhil,

    Great blog with fine details about SF EC. The way you have described the core details of EC was really good and provide clear overview of EC. For me personally it gave me a clear snapshot about how EC differs to SAP PA.

    Thanks once again for taking efforts to write the blog.


  • Hi Akhil,

    Nice blog!! I have doubt here. Can we add operations to entity, like for entity ADHOC_HRIS I am getting error –


                   <ns2:errorMessage>Entity type ‘adhoc_hris’ doesn’t support QUERY operation!</ns2:errorMessage>

    Can we add operation here? I am trying to fetch data from this entity via SAP PI.

    Thanks & Regards,

    Rashmi Joshi

  • Hi Akhil,

    Very nice post, lot of helpful information here!

    I just have one question on which you may have the answer: by default when using SFAPI on compoundemployee, if there are records with the same start_date (on job_infirmation for example), SFAPI returns only the last record that was inserted. Do you know if there is a way to get all records back, even if they are on the same start_date?

    Thanks again for your post!


    • Hi,

      Kindly help me to join two entity EmpEmployment and PerPersonal.

      I am using success factor soap query api and  below join like Sql which is not working

      SELECT e.user_id, e.person_id, e.start_date, e.end_date, e. originalStartDate


      FROM EmpEmployment e join PerPersonal p on e.person_id=p.person_id

      and p.person_id =’XXXX’

  • Hi All,

    Kindly help me to join two entity EmpEmployment and PerPersonal.

    I am using success factor soap query api and  below join like Sql which is not working

    SELECT e.user_id, e.person_id, e.start_date, e.end_date, e. originalStartDate


    FROM EmpEmployment e join PerPersonal p on e.person_id=p.person_id

    and p.person_id =’XXXX’