^
Login

API Jobs

The Job actions read and write an account's Jobs: the work staff clock their hours to, such as projects, sites or functions. get_jobs returns the Jobs, for software that copies them from Microkeeper. update_jobs adds and updates Jobs from your software, for when your software manages them and Microkeeper keeps a copy.

Actionsget_jobs, update_jobs
Business key accessAccount: Read Only to get, Read/Write to update

This guide covers how to:

  1. Get the Jobs.
  2. Send Jobs as they change.
  3. Send your full list of active Jobs.

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

Get the Jobs with get_jobs

Choose which Jobs with status:

mk_dataReturns
{"status":"all"}Every Job that isn't Finished
{"status":"finished"}Finished Jobs
{"status":"JID","JID":["1100","1103"]}The Jobs with these Microkeeper IDs
{"status":"JobID","JobID":["STK-2026"]}The Jobs with these IDs from your software

Response

{
  "success": "1",
  "authenticated": "1",
  "message": "Job data",
  "data": {
    "jobs": [
      {
        "JID": "1100",
        "CID": "0",
        "title": "Restaurant Service",
        "startdate": "2026-06-01",
        "enddate": "0000-00-00",
        "job_access": "1",
        "status": "Active",
        "JobID": ""
      }
    ]
  }
}

Jobs are listed by title:

FieldWhat it is
JIDThe Job's ID in Microkeeper
JobIDYour software's ID for the Job, or blank
CIDThe client the Job is for, or 0 for an in-house Job
titleThe Job's name
startdate, enddateYYYY-MM-DD, or 0000-00-00 if not set
job_accessWho can clock onto the Job: 1 All employees, 2 Location Proximity, 0 Individual
statusQuoted, Pending, Active or Finished. Staff can clock onto Active Jobs

Errors

  • The status variable must be included, The status variable must be set to either all or finished
  • A list of JID must be passed, An list of JobID must be passed: send the IDs as a list.
  • There are no Jobs in Microkeeper yet: no Jobs match.

Send Jobs with update_jobs

Set config.status_set to choose what happens to the Jobs you don't send:

  • skip: they're left as they are. Use it to send Jobs as they're added or changed in your software.
  • finish_all: they're marked Finished. Use it to send your full list of active Jobs on a schedule, such as nightly.

Use skip while you test, so a short list doesn't finish the account's other Jobs.

Example

{
  "config": { "status_set": "skip" },
  "jobs": [
    { "JobID": "STK-2026", "title": "December Stocktake", "startdate": "2026-12-01", "enddate": "2026-12-31", "job_access": "1", "status": "Active" },
    { "JobID": "FN-118", "title": "Smith Wedding", "CID": "52", "job_access": "2", "status": "Active" },
    { "JobID": "FN-097", "title": "Jones Birthday", "status": "Finished" }
  ]
}

How each Job is matched

Choose one way to match Jobs, and use it every time:

  • By your software's ID: send JobID and leave out JID. A known JobID updates that Job, including its title; a new one adds a Job.
  • By Microkeeper's ID: send the Job's JID to update it, or JID 0 to add one. With 0, a Job with the same title is updated instead. Store the JIDs the response returns.

Fields

FieldRequiredWhat it is
JobID or JIDOne of themSee above
titleYesThe Job's name. Titles match exactly, including capitals. Quotes, ampersands, commas and % are removed, so match on JobID if your titles use them
statusSend it every timeActive or Finished, or Quoted or Pending. A Job sent without it becomes Active
CIDNoThe client's ID, or 0 for an in-house Job
startdate, enddateNoYYYY-MM-DD
job_accessNo1 All employees, 2 Location Proximity, 0 Individual. New Jobs default to 1

On an update, CID, the dates and job_access keep their values if you leave them out.

Jobs aren't deleted, so their hours stay on record. Send a Job with Finished to stop staff clocking onto it, and with Active to reopen it.

Response

{
  "success": "1",
  "authenticated": "1",
  "message": "Jobs updated",
  "data": {
    "update": { "STK-2026": 1104, "FN-118": 1105, "FN-097": 1090 }
  }
}

data can hold four lists. Each is there only when it has something in it:

ListWhat it holds
updateThe Jobs added or updated
finishedWith finish_all: the JIDs of Jobs marked Finished because they weren't sent
not_foundJIDs that aren't in Microkeeper. Fix these in your software
duplicateJobs not updated because another Job already has the title. Fix these in your software

When you send a JobID, the lists are keyed by it, with the JID as the value. Otherwise they're lists of JIDs.

Errors

These stop the request, and nothing is changed:

  • The status_set field must be set, status_set must be set to either finish_all or skip
  • A list of jobs was not supplied
  • The title and (JID or JobID) fields are required
  • The title for job FN-118 is blank
  • The status for job FN-118 is Closed which is not allowed
  • No jobs updated no errors found: nothing was sent to update.
M2