How to get Employee names

Peter_Lay
Peter_Lay Expensify Customer Posts: 38 Expensify Newcomer

I'm currently working on an integration between our SAP and Expensify. I'm conducting this via an API Post as per the documentation stated. However, I am unable to locate where or how to pass the user's first/last names in the API post.

In our current set up with NetSuite, the user's first/last name as well as their email is being transferred over.

However, with the new API for SAP, only the email is being transferred. How can I update the API post to include the first/last name?

Thank you ahead of time,

Peter. L.

Best Answer

Answers

  • Jeremy Boniface
    Jeremy Boniface Expensify Team Posts: 202 Expensify Team

    This requires special access, setup, and data formatting. Basically, you need to send us JSON formatted employee data, and we would set it up on our side to receive and parse that data ahead of time. Note that the integrations account (i.e. the account associated with the API credentials) would need to be a domain and policy admin in this case. This is a bit of a larger project (and I'm not totally sure it's worth it just for names -- we'd need to discuss the ROI of that with you), so I would recommend reaching out to concierge@expensify.com to get started with that conversation. If Concierge is unsure (as this is a little bit less common), feel free to let them know that you spoke with me in the Community.

  • Peter_Lay
    Peter_Lay Expensify Customer Posts: 38 Expensify Newcomer

    Hi @Jeremy Boniface

    Thanks for the response. To clarify, in order to integrate the names of the user via the API, it has to pass through to Expensify via another method using JSON format. Is this method self serving or will it require our data to be sent to Expensify via another methodology?

    According to the documentation on Expensify, CSV is the only acceptable data format for Employees, but to join the names against the email, it will require the data to be sent via JSON?

    The integration account that we've set up is a policy admin against the policies we want to update this to.

  • Jeremy Boniface
    Jeremy Boniface Expensify Team Posts: 202 Expensify Team

    You would adapt to serving this data via JSON. It would still be sent via the API. This method is not documented in the user-facing documentation, but it's the only way to update names that I'm aware of. Basically, to achieve this, you'd need to rework the way you're serving this data to us (by serving as JSON instead of CSV), and we'd need to whitelist the account to allow it to make changes on behalf of users.

  • Peter_Lay
    Peter_Lay Expensify Customer Posts: 38 Expensify Newcomer

    @Jeremy Boniface

    So then if we were to update our code to be JSON format, all that needs to be done on Expensify's side is to whitelist the account that's making the changes and we would be able to update the user name and email?

    Or does our JSON payload have to get passed to Expensify staging of sorts before it gets updated in our Expensify instance?

  • Jeremy Boniface
    Jeremy Boniface Expensify Team Posts: 202 Expensify Team

    Nope, you've got it. I'm gathering some more info for you now. There's a specific format for the employee object that you need to send.

  • Jeremy Boniface
    Jeremy Boniface Expensify Team Posts: 202 Expensify Team

    I actually found some documentation -- what we're doing is essentially based on this, but it's not exactly the same. We now have a generic importer that we can use, which requires a specific format but is easier to set up.

  • Jeremy Boniface
    Jeremy Boniface Expensify Team Posts: 202 Expensify Team

    The request would look like this (IMPORTANT: this is set to dry-run : true, which means it doesn't actually take action -- this is for testing. Set this value to false when its time to go to production):

    {
        "type": "update",
        "credentials": {
            "partnerUserID": "XX",
            "partnerUserSecret": "XX"
        },
        "dry-run": true,
        "dataSource": "request",
        "inputSettings": {
            "entity": "generic",
            "type": "employees"
        },
        "onFinish": []
    }
    

    The data would look like this:

    {
      "Employees": [
        {
          "employeeID": "1",
          "employeeEmail": "employee1@domain.com",
          "managerEmail": "manager1@domain.com",
          "firstName": "Employee",
          "lastName": "One",
          "policyID": "B97922A66956B2F4"
        },
        {
          "employeeID": "2",
          "employeeEmail": "employee2@domain.com",
          "managerEmail": "manager2@domain.com",
          "firstName": "Employee",
          "lastName": "Two",
          "policyID": "B97922A66956B2F4"
        },
        {
          "employeeID": "3",
          "employeeEmail": "employee3@domain.com",
          "managerEmail": "manager3@domain.com",
          "firstName": "Employee",
          "lastName": "Three",
          "policyID": "B97922A66956B2F4"
        }
      ]
    }
    

    Note that all fields are required.

    If you need help understanding how to append the data (it sounds like you don't, but just in case), check out the curl examples in the shell side of the docs.

  • Peter_Lay
    Peter_Lay Expensify Customer Posts: 38 Expensify Newcomer

    @Jeremy Boniface

    So aside from the whitelisting, it seems like the majority of the legwork is done on our side.

    Regarding your previous message of level of effort, what are we looking at from the Expensify team?

  • Jeremy Boniface
    Jeremy Boniface Expensify Team Posts: 202 Expensify Team

    I learned today that if you follow the generic implementation presented above we no longer need to configure nor whitelist -- it should "just work". I did get word from Engineering that we're waiting for an update to be deployed to the generic importer, so I'm not 100% that it will work prior to that occurring. I'm still checking with Engineering regarding the implications of that update and will report back to our thread in Concierge once I find out.

  • Peter_Lay
    Peter_Lay Expensify Customer Posts: 38 Expensify Newcomer

    Thanks Jeremy.

    What is the generic importer that you're referring to? I'm going to update our API post in our sandbox to test out what you've just sent.

    I have a policy just for testing, does that mean I can set production to true? Furthermore, we currently have multiple policies, do you recommend sending multiple payloads or just a singular payload with every employee/attributes?

    Thanks,

    Peter. L.

  • Jeremy Boniface
    Jeremy Boniface Expensify Team Posts: 202 Expensify Team

    By generic, I mean sending the request with entity set to "generic" using the the standard JSON format I sent. A single payload should work. When a user is in multiple policies, I assume they approve in multiple policies, but only submit in one -- is that correct? As a note, the managerEmail field in the JSON should correspond to their "Submits to" field in Expensify.

  • Peter_Lay
    Peter_Lay Expensify Customer Posts: 38 Expensify Newcomer

    Hi Jeremy,

    Here's what I wrote:

    {

    "type": "update",

    "credentials": {

    "partnerUserID": "XX",

    "partnerUserSecret": "XX"

    },


    "dry-run": true,

    "dataSource": "request",

    "inputSettings": {

    "entity": "generic",

    "fileType": "data",

    "type": "employees"

    },

    "onFinish": []

    }


    With the following JSON format:

    {

    "Employees": [

    {

    "employeeID": "1000",

    "employeeEmail": "juslaze+30@gmail.com",

    "managerEmail": "laypeter@twitch.tv",

    "firstName": "Jeffrey",

    "lastName": "Ricardo",

    "policyID": "2A29DC86CCE1BACE"

    }

    ]

    }


    I'm getting a response code 200, but I'm not seeing the update. Does that have to do with dry-run being set to True? Should I set it to false and see if it updates the names?

  • cchua613
    cchua613 Expensify Customer Posts: 1

    We are testing for the integration between Workday <> Expensify using JSON format and we are having issues passing the First and Last name fields to Expensify. When we send over the API we are not using a dry-run (dry-run set to false), the response code is 200 (success) and the JSON is pulling the firstName and lastName fields. 

    When I look into Expensify it doesn't appear to load the first and last names.

    Do we still need to contact concierge@expensify.com to whitelist our instance?

  • Conor Pendergrast
    Conor Pendergrast Expensify Success Coach - Admin, Expensify Team, Expensify Student Ambassador Posts: 175 Expensify Team

    @cchua613 Hey! I'd recommend speaking to Concierge through the web app or via email about this, as we'll need specific details to understand what's going on here and why - and those shouldn't be sent via the Community!

    In general though, I'd recommend following this basic guide, and this API documentation. Two top points I think are useful to remember from that:

    1. The API user will typically need to be a Policy Admin for your company's policies and a Domain Admin for your company's domain in Expensify
    2. If you are testing without using dry-run, do not send data for real employees (ie: real email addresses or employeeID in Workday that match to real employee profiles) because that will update those employees in Expensify (including, for example, changing the email addresses associated with their Expensify account)