Skip to Content

How to create an Employee using OData APIs

This blog explains how you can create or update an employee in Employee Central using OData APIs. To keep it simple, I will create an Employee with minimum possible fields.

The graphic below outlines the different Employee Central entities needed for employee creation, along with the corresponding minimal fields per entity, which are listed directly under the entity name.


The order in which you create the required minimum entities is critical. It should be in following order: User -> PerPerson -> EmpEmployment -> EmpJob -> PerPersonal as listed in graphic above.

The following table links the UI portlets with the respective OData entities.

UI name

OData Name



Biographical Information


Employment Details


Job Information


Personal Information


For this example I am using Advanced Rest Client Application, which can be installed as a chrome extension/app. This application provides an easy way to call the OData API. Once you have installed this app, you have to perform following basic steps before executing any OData query:

1. In the top URL text box provide your OData url in the following format:

https://<SF URL>/odata/v2/upsert, you can find further information about your ODATA API endpoint here: About HCM Suite OData APIs – SAP Library.

2. For this example we will use the basic authorization, in order to use the basic authorization you have to use following format:

Authorization: Basic <Base 64 encoded (“user@company:password”)>, for example, please refer to the graphic below:


In the next steps, I will provide the ODATA request for all the entities to create an employee. You can use these examples directly or extend it as per your requirement in order to create an employee in EC.To see the ODATA data dictionary for your company instance, please goto Admin Tools->OData API Data Dictionary.

1. User: After doing the above mentioned steps you can directly start with creation of user entity, by entering the following details in the payload section of Rest client


“__metadata”: {

“uri”: “User(‘mhoff’)”


“username”: “markushoff”,

    “status”: “Active”,

    “userId”: “mhoff”


If the user is successfully created you should get a response back with the status OK and editstaus as INSERTED or UPSERTED, this behaviour will remain same for all the entities.

2. PerPerson

Similarly to user creation you can create perPerson by entering the following minimum details:


“__metadata”: {

“uri”: “PerPerson(‘mhoff’)”


“personIdExternal”: “hoffmarkus”,

“userId”: “mhoff”


The next step will be to create EmpEmployement, here you need to enter the start date, userID and PersonIDExternal

{“__metadata”: {

“uri”: “EmpEmployment(personIdExternal=’hoffmarkus’,userId=’mhoff’)”






Note: PerPerson will only appear in query after EmpEmployement is created

4. EmpJob: For creating EmpJob you will execute the following request, please note that fields below may change based on your own data-model configuration:

{“__metadata”: {

“uri”: “EmpJob”











5. PerPersonal: For creating the PerPersonal one needs following information:

{ “__metadata”:{







After successfuly calling the APIS for all the entities, you should be able to see the employee directly in the EC UI portlets.

In case if you need further information regarding ODATA, please refer to these resources:

ODATA Basics:


Looking forward to your questions and feedback in the comments section.

You must be Logged on to comment or reply to a post.
  • Great blog Naresh!  Full of useful information.  I used my favorite REST chrome extension (postman) and was able to follow your steps successfully.  Keep the blogs coming!

    • Hi Bradon,

      I am glad that you liked the blog and were able to use it directly. I just installed postman, looks like a cool extension :-),

      Best regards,


  • Great work Naresh - I was looking for something like this... will try it out and post my comments later.

    Is there any blog which has the consolidated list for pre-requisities before we can try the exercise in this blog.

    Cheers - Amit/-

    • Hi Amit,

      Glad that you liked the blog. As a pre-requisite you will need an EC Instance and an user with all the RBP permission to do a new hire and execute ODATA calls.

      Best regards,


  • Great blog Naresh.

    We have employed similar workflow in one of my projects with few variations.

    In our case we have to use System AUTO generated NEXT userId. From release b1505 SAP released new API to fetch next UserId from system. In our case it was AUTO generated numeric value.

    Here are API details:


    It is Post method and below is sample response.

    Response back from request:


    { "GenerateNextPersonIDResponse": { "personID":"80004203" }




  • Hi Naresh,

    I was trying to follow your steps but somehow it is not working.

    when i do a post to the SF i do not get any response back not even a faliure.

    Can you suggest.?

    Thanks ,


    • HI Luke,

      Thanks a lot for mentioning this, yes, our guides are improving very well, will be great to have further feedback/comments on the documentation.

      Best regards,


  • Thank you for this very nice blog.

    Actually you are more precise than the official documentation that presents examples of POST request not even working.

    This is very precious info! 5 stars.

    Thank you for sharing.

    Best regards.

    Jacques-Antoine Ollier

  • Hello Naresh,

    thanks a lot for your blog. I'm looking for a way to delete Cost Centers. In the API Data Dictionary in EC says the operation is supported but I'm not able to find documentation explaining how to perform a delete.

    Do you have any documentation or guideline to do this?

    Thanks a lot!

    • Hi Syed,


      You can trigger rules for job info, personal info, compensation entities and termination. Workflow can be trigerred for job and termination. Workflow will not be trigerred for new hire use case.

      Please refer to imports guide for more details.




      • Naresh,

        We are making an API call from a FIORI service to create an EmpJob record changing the employees working hours, e.g. below:

        The record is being created correctly, however the workflow is not triggered. We have looked at the import guide and enabled RBP for import however the workflow is still not triggering. Are you able to provide any further guidance on how to enable triggering of workflow.

        When I create the record through the UI the record triggers as expected.


        {"__metadata" : { "uri" : "EmpJob"},

        "startDate": "/Date(1501545600000)/",

        "userId": "u008161",


        "eventReason":"CHGHOURS" ,

        "workscheduleCode" : "0003",

        "workingDaysPerWeek": "4"






        • Hi John,


          If you have enabled rules and workflow in RBP(for imports), ideally it should trigger workflow. Please note that workflow is created only for incremental update and not created in case of new hire case.



  • Hi Naresh,

    thanks a lot for the blog.

    I tried it with our Successfactors Instance but always get this error:




    <?xml version="1.0" encoding="utf-8"?><error xmlns=""><code>MethodNotAllowedException</code><message lang="en-US">Method Not Allowed</message></error>

    Do we have to change something in the Successfactors configuration?

    Any ideas?








  • Hello Naresh,

    thanks for your post. For me who did never before something with SF, this is quite helpful. I have one suggestion: Could you put the code snippets in code blocks? As is, I can't just copy and paste the JSON snippets because there are typographic quotes instead of the required quote characters.

    This would also make the post easier to read.

    Best regards,


  • Hi Naresh,

    Excellent blog!

    Do you have any details on how to replace/delete information for employees?  Basically, I am able to create the employee in the system and also terminate them.  Now I need to change the start and end date.

    I am trying to replace the EmpEmployment information which has a start date - But I get the error "Start date cannot be greater than end date".  I am trying to change the employee start and end date to be later on - but I think the end date for the existing record does not like the new start date in the future that I am passing.

    I have created a question.  It would be great if you can take a look.

    SuccessFactors OData API purgeType=full not working. How to replace EmpEmployment/EmpJob entities



  • Hi Naresh,

    I am trying to post the request but always get below error. Have tried with different values but doesn't work. Can you please suggest what is wrong here?



    { "__metadata": {
    "uri": "User(‘207798’)"

    "username": "Test207798",
    "status": "Active",
    "userId": "207798"



    "d": [
    "key": null,
    "status": "ERROR",
    "editStatus": "UPSERTED",
    "message": "bad valueString [‘207798’] as part of keyString [‘207798’]",
    "index": 0,
    "httpCode": 400,
    "inlineResults": null




  • Hi Naresh,


    How can i fetch employee details like userId, name,phone,jobTitle and Photo(most important) via odata api in successfactors




  • Hi Naresh,


    I followed the sequence of the entities, Everything gets upserted successfully.

    However, the data does not reflect in the Job Information Portlet.

    I tried to query the EmpJob, the Job data I upserted is present.

    Can you give me some clues on what caused this issue ?




  • Dear experts
    We are trying to put an employee as a draft from a third party system, could you share which API we need use for this odata or protocol?
    Many thanks in advance

  • Hi @Naresh,


    Thanks for this post.

    But, it's possible to use this same logic to integration a hire information of third part system to Employee Central on Manage Pending Hire window?

    Or integrate only user informations to Employee Central and complete the register of new hire with business informations on Employee Central Profile?