background

Staff Mapper API



Staff Mapper has a tiny API. Here's the documentation.

v1

API Reference

Authentication
Endpoint: /login

Before you can interact with our API, you'll need to authenticate with us. By doing so, you will be provided with an authentication token in the response back from our API. This authentication token is what you must pass on to each subsequent API request. Of course, this means you need to register with Staff Mapper before continuing.

Once you do, your request should look something like this:
curl -d "[email protected]&password=secretpass" -X POST https://staffmapper.com/login
Assuming you are successfully authenticated, Staff Mapper will provide a response that looks like this:

{
    "message": "Successfully Authenticated!",
    "data": [
        {
            "user_id": 1,
            "authentication_token": "xsQsWzDn_BWrvS1VwRATBzUB",
            "email": "[email protected]",
            "org_key": "fake"
        }
    ]
}
Save your authentication token. You'll need it if you want to retrieve and POST data to Staff Mapper.

Rosters
Endpoint: /api/v1/rosters

You can retrieve your entire roster by performing a GET request like so:
curl -d "authentication_token=xsQsWzDn_BWrvS1VwRATBzUB" -X GET https://org_key.staffmapper.com/api/v1/rosters
There are two things to note here: 1) All requests need to include your org_key as the subdomain and 2) all requests must include your authentication_token. The response will look like this:

[{
    "id": 325,
    "name": "Brice John",
    "role": "Analyst",
    "email": "[email protected]",
    "office": "Boston, MA",
    "onboard_date": "2017-01-01",
    "offboard_date": null,
    "created_at": "2017-02-01T00:18:40.249Z",
    "updated_at": "2017-01-03T00:18:40.249Z",
    "utilization": [
        0,
        1,
        2,
        3,
        4,
        5,
        6
    ],
    "availability": [
        8,
        7,
        6,
        5,
        4,
        3,
        2
    ],
    "skill": {
        "IOS": "10",
        "SAS": "5",
        "YOGA": "6",
        "EXCEL": "0",
        "MUSIC": "1",
        "NVIVO": "5",
        "STATA": "5",
        "CODING": "1",
        "SHORTHAND": "3",
        "RECRUITING": "0",
        "PHOTOGRAPHY": "6",
        "LEGAL ANALYSIS": "2",
        "NOODLE DANCING": "5",
        "TYPING REALLY, REALLY FAST": "5"
    },
    "time": {
        "01.29.18": "40",
        "02.05.18": "12",
        "02.12.18": "22",
        "02.19.18": "35"
    },
    "effort_by_project": {
        "16": {
            "02.05.18": 12
        }
    },
    "projected_hours": {
        "01.29.18": "",
        "02.05.18": "12",
        "02.12.18": "",
        "02.19.18": ""
    },
    "claimed": [
        8,
        null,
        null,
        null,
        null,
        null,
        null
    ],
    "pto": [02.02.18, 02.03.18]
}]
The time-series data is relevant to the week you pull it. Staff Mapper clears these dates sometime on Sunday in preparation for the upcoming week. We dump all historical data into another endpoint @ /api/v1/histories which you read about below. Couple of notes on these data points:

  • 👉 utilization: This is an ordered array representing each day of the week, and how busy or utilized that employee has indicated they will be. This is data that comes from the desktop app.
  • 👉 availability: This is an ordered array representing each day of the week, and how available that employee has indicated they will be. This is data that comes from the desktop app.
  • 👉 claimed: This is an ordered array representing each day of the week, and when an employee's time that day was claimed.
  • 👉 skill: This is a list of skills and proficiencies indicated by the employee.
  • 👉 time: This is self-estimated utilization on the Weekly Punchcard. The dates are always the beginning of the week and extends out for 3 additional weeks.
  • 👉 projected_hours: This is a Staff Mapper estimate of utilization based on collective projects that person has been assigned to (via effort_by_project, which includes details about which projects contribute to the level of effort). The dates are always the beginning of the week and extend out for 3 additional weeks.


  • Endpoint: /api/v1/rosters/update_pto

    You can also PUT PTO to Staff Mapper like so:
    curl -d "pto_date="2018-02-02"[email protected]&authentication_token=xsQsWzDn_BWrvS1VwRATBzUB" -X PUT https://org_key.staffmapper.com/api/v1/rosters/update_pto

    You can add PTO for anyone on your team: 1) If the PTO date already exists, then the PUT will return a message saying so. 2) If the PTO date doesn't exist, then it will be posted for the date you specify. We don't differentiate between 1, 4 or 8 hours of PTO on a given day, so you'll have to decide if it makes sense to add a PTO day for an employee on Staff Mapper because we will show it as a full blocked day on Staff Mapper regardless.

Histories
Endpoint: /api/v1/histories

You can retrieve historical data for your company by performing a GET request like so:
curl -d "authentication_token=xsQsWzDn_BWrvS1VwRATBzUB" -X GET https://org_key.staffmapper.com/api/v1/histories

There are two things to note here: 1) All requests need to include your org_key as the subdomain and 2) all requests must include your authentication_token. The response will look like this:

[{
    "id": 84,
    "roster_id": 31,
    "week_start": "2018-01-29",
    "self_time": "10.0",
    "est_time": "52.0",
    "effort_by_project": {
        "18": 10,
        "19": 2
    },
    "pto_days": 3,
    "created_at": "2018-02-02T19:05:11.808Z",
    "updated_at": "2018-02-02T19:05:11.808Z",
    "utilization": [
        "4",
        null,
        "2",
        null,
        null
    ],
    "availability": [
        "2",
        null,
        "6",
        null,
        null
    ],
    "claimed": [
        null,
        null,
        "1",
        null,
        null
    ],
    "name": "Brice John",
    "email": "[email protected]",
    "role": "Analyst",
    "office": "Boston, MA",
    "onboard_date": "2011-01-01",
    "offboard_date": null,
    "skill": {
        "IOS": "7",
        "PPT": "5",
        "SAS": "3",
        "RUBY": "8",
        "WORD": "3",
        "YOGA": "2",
        "EXCEL": "5",
        "MUSIC": "8",
        "NINJA": "2",
        "NVIVO": "1",
        "RAILS": "9",
        "STATA": "1",
        "XPATH": "10",
        "CODING": "7",
        "PYTHON": "7",
        "TWITCH": "2",
        "BOW STAFF": "2",
        "SHORTHAND": "4",
        "RECRUITING": "5",
        "PHOTOGRAPHY": "2",
        "CONSTRUCTION": "0",
        "WEB DEVELOPMENT": "10",
        "DATA WAREHOUSING": "6",
        "MACHINE LEARNING": "9",
        "MICROSOFT PROJECT": "2",
        "TYPING REALLY, REALLY FAST": "2"
    }]
The time-series data is based on the week_start. There should be any entry for every week, for every member on your team.