^
Login

API Locations

The Location actions read and write an account's Locations: the sites staff are rostered and clock on at. get_locations returns every Location with its ID (LID). upsert_locations adds Locations or updates them, matched by Microkeeper's LID or by your software's own ID (third_ID).

Actionsget_locations, upsert_locations
Business key accessAccount: Read Only to get, Read/Write to upsert

Before you start, make your keys and test your connection: see Microkeeper API.

Get the Locations with get_locations

FieldValue
mk_actionget_locations
mk_data{"status":"all"}

Response

Every Location is returned, active and inactive:

{
  "success": "1",
  "authenticated": "1",
  "message": "Location data",
  "data": {
    "locations": [
      {
        "LID": "14227",
        "third_ID": "MEL-01",
        "title": "Melbourne Restaurant",
        "lon": "144.970700",
        "lat": "-37.814100",
        "JID": "0",
        "manager_eusername": ["sophie_brown", "mia_chen"],
        "GID": "59467",
        "CID": "0",
        "hours_goal": "100.00",
        "cost_goal": "10000.00",
        "color": "#FF80EA",
        "active": "1",
        "address1": "1 Collins Street",
        "address2": "",
        "city": "Melbourne",
        "state": "VIC",
        "postcode": "3000",
        "country": "Australia"
      }
    ]
  }
}
FieldWhat it is
LIDThe Location's ID in Microkeeper
third_IDYour software's ID for the Location, or null if none is set
titleThe Location's name
lon, latThe Location's longitude and latitude, for GPS clocking
JIDThe Location's default Job, or 0
manager_eusernameA list of the Location's managers, by username
GIDThe Group of staff who work at the Location
CIDThe client the Location belongs to, or 0
hours_goal, cost_goalThe Location's budgeted hours and labour cost
colorThe Location's colour on the roster, as a hex code
active"1" active, "0" inactive
address1, address2, city, state, postcode, countryThe Location's address

Errors

  • The status variable must be included, Location API field status must be set to all: send "status":"all".
  • There are no Locations in Microkeeper yet

Add or update Locations with upsert_locations

Each Location you send is added or updated. Locations you don't send are left as they are.

Example

{
  "config": { "write_list": "all" },
  "locations": [
    {
      "LID": 0,
      "third_ID": "GEE-01",
      "title": "Geelong Cafe",
      "active": "1",
      "manager_eusername": ["mia_chen"],
      "lat": "-38.147800",
      "lon": "144.360700",
      "address1": "20 Moorabool Street",
      "city": "Geelong",
      "state": "VIC",
      "postcode": "3220"
    },
    {
      "LID": 14228,
      "title": "Sydney Restaurant",
      "active": "0"
    }
  ]
}

The first Location is added, or updated if GEE-01 is already in Microkeeper. The second makes the Sydney Location inactive.

How each Location is matched

  • A known LID updates that Location.
  • LID 0, or no LID, with a third_ID already in Microkeeper, updates that Location.
  • Otherwise a new Location is added.

Use third_ID to match by your own IDs, so you don't need to store Microkeeper's. Send LID 0 with it.

Fields

FieldRequiredWhat it is
config.write_listYesall
LID or third_IDOne of themMicrokeeper's ID, 0 for a new Location, or your software's ID
titleYesThe Location's name
activeYes"1" active, "0" inactive
manager_eusernameNoA list of managers' usernames. It replaces the Location's managers; send [] to remove them all
lon, latNoLongitude and latitude
JIDNoThe default Job
GIDNoThe Group of staff who work at the Location
CIDNoThe client
hours_goal, cost_goalNoBudgeted hours and labour cost
colorNoA hex colour, such as #FF80EA
address1, address2, city, state, postcode, countryNoThe address

On an update, fields you leave out keep their values. Managers are given access to the Location, and lose it when you take them off the list.

Response

{ "success":"1", "authenticated":"1", "message":"Locations updated", "data":{"LID":[14229,14228]} }

LID lists the Location IDs added or updated, in the order you sent them. Store them if you match by LID.

Errors

An error stops the request, and nothing is changed.

  • The write_list field must be set, Status must be set to all: send "config":{"write_list":"all"}.
  • A list of locations was not supplied
  • Each location must include LID or third_ID as unique ID
  • LID 14300 does not exist: send 0 to add a Location.
  • Duplicate third_ID GEE-01 present: each third_ID appears once in a request.
  • The Location Title must be set
  • active must be set and be either 1 or 0
S2