onboarding

Add a new hire and return its H-NNNN id: a name, a role and the day they start. The role is a grouping key, lower-cased and hyphenated. Add tasks with onboarding_task_add, or apply a role template with onboarding_template_apply.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 200,
      "description": "The hire's name, e.g. Ada Lovelace"
    },
    "role": {
      "type": "string",
      "maxLength": 60,
      "description": "The role, e.g. engineer or sales. Lower-cased and hyphenated"
    },
    "start_date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day they start, YYYY-MM-DD. Task due dates are counted from here"
    }
  },
  "required": [
    "name",
    "role",
    "start_date"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Every hire with their role, start date, task counts, percent complete and overdue count. Filter by role or by a word in the name. Returns at most 500 rows, newest change first.

{
  "type": "object",
  "properties": {
    "role": {
      "type": "string",
      "maxLength": 60,
      "description": "Only hires in this role, matched after the same lower-case hyphenation applied on add"
    },
    "contains": {
      "type": "string",
      "maxLength": 200,
      "description": "Only hires whose name contains this text, matched case-insensitively"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Add one task to a hire's plan and return its K01-style id: the text, who owns it (hr, manager or it) and how many days after the start date it is due. The due date is counted from the hire's start date.

{
  "type": "object",
  "properties": {
    "hire": {
      "type": "string",
      "maxLength": 200,
      "description": "The hire id, e.g. H-0001, or the name when only one carries it"
    },
    "text": {
      "type": "string",
      "maxLength": 2000,
      "description": "The task, as the person doing it will read it, e.g. Issue laptop and security badge"
    },
    "owner": {
      "type": "string",
      "enum": [
        "hr",
        "manager",
        "it"
      ],
      "description": "Who owns the task: hr, manager or it"
    },
    "due_offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 365,
      "description": "Days after the hire's start date the task is due. 0 is day one"
    }
  },
  "required": [
    "hire",
    "text",
    "owner",
    "due_offset"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Mark one task on a hire done or skipped, with the day it happened. done counts toward the percent complete; skipped is a deliberate dismissal and never counts as done. A task can be set back to todo to reopen it.

{
  "type": "object",
  "properties": {
    "hire": {
      "type": "string",
      "maxLength": 200,
      "description": "The hire id, e.g. H-0001, or the name when only one carries it"
    },
    "task": {
      "type": "string",
      "maxLength": 16,
      "description": "The task id, e.g. K03, as shown by onboarding_progress"
    },
    "status": {
      "type": "string",
      "enum": [
        "todo",
        "done",
        "skipped"
      ],
      "description": "done, skipped, or todo to put it back to outstanding"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day it was completed, YYYY-MM-DD. Default today"
    }
  },
  "required": [
    "hire",
    "task",
    "status"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Apply a role template to one hire (free) or many (Pro), copying the template's tasks into each hire with the template's version recorded. Editing the template afterwards never changes a hire already under way. If no template exists for the role, one is created from the tasks you pass.

{
  "type": "object",
  "properties": {
    "hire": {
      "type": "string",
      "maxLength": 200,
      "description": "The hire to apply the template to. Pro: pass a comma-separated list of hire ids or names to apply to many at once"
    },
    "role": {
      "type": "string",
      "maxLength": 60,
      "description": "The role template to apply, by id (T-0001) or role. If omitted, the hire's own role is used"
    },
    "tasks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "maxLength": 2000
          },
          "owner": {
            "type": "string",
            "enum": [
              "hr",
              "manager",
              "it"
            ],
            "default": "manager"
          },
          "due_offset": {
            "type": "integer",
            "minimum": 0,
            "maximum": 365,
            "default": 0
          }
        },
        "required": [
          "text"
        ],
        "additionalProperties": false
      },
      "maxItems": 500,
      "description": "When no template exists for the role, create one from these tasks and apply it. Pro only when applying to more than one hire"
    }
  },
  "required": [
    "hire"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

One hire's whole plan: every task with its owner, due date and status, plus the percent complete, the overdue count and what is still outstanding. Pass as_csv for a Pro-only CSV export of the plan.

{
  "type": "object",
  "properties": {
    "hire": {
      "type": "string",
      "maxLength": 200,
      "description": "The hire id, e.g. H-0001, or the name when only one carries it"
    },
    "as_csv": {
      "type": "boolean",
      "description": "Return the plan as CSV. Pro only. Default false"
    }
  },
  "required": [
    "hire"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Every task that is still outstanding past its due date, across all hires or one hire, with how many days late. Returns at most 500 rows, most overdue first.

{
  "type": "object",
  "properties": {
    "hire": {
      "type": "string",
      "maxLength": 200,
      "description": "Only this hire's overdue tasks. Omit for every hire"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Report this endpoint's licence state for your token as JSON: the product, the tier free or pro, why it is not Pro, and the checkout URL. Call it to explain a free-tier refusal. No arguments, nothing changes.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Turn Pro on for this connection with key, an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. Data under your token stays; a wrong or expired key changes nothing. license_status confirms it.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "License key from checkout, MCPL1.<payload>.<signature>"
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}