paymo

Fetch the Paymo user the API key belongs to (id, name, type, timezone). Use the id as user_id for 'my' time entries and timers. A cheap way to confirm the key works. Paymo: GET /api/me.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch the company (account) info and settings: name, default currency, timezone, working days, invoice numbering. Paymo: GET /api/company.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List users in the company (id, name, email, type, hourly rate, assigned/managed projects). Paymo: GET /api/users.

{
  "type": "object",
  "properties": {
    "active": {
      "description": "true = active users only, false = retired users only.",
      "type": "boolean"
    },
    "type": {
      "description": "Only users of this type.",
      "type": "string",
      "enum": [
        "Admin",
        "Employee",
        "Guest"
      ]
    },
    "where": {
      "description": "Extra raw Paymo filter ANDed onto the typed ones, e.g. `billable=true` or `name like Website`. Operators: = > >= < <= != like, not like, in (a,b), not in (a,b).",
      "type": "string",
      "maxLength": 500
    },
    "limit": {
      "description": "Max items to return (default 100, max 500). Paymo has no pagination; results beyond this are truncated.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List clients (id, name, contact details, active flag). Paymo: GET /api/clients.

{
  "type": "object",
  "properties": {
    "active": {
      "description": "true = active clients only, false = archived only.",
      "type": "boolean"
    },
    "include": {
      "description": "Related objects to embed (Paymo `include`), comma-separated, e.g. client or tasklists.tasks.",
      "type": "string",
      "maxLength": 300,
      "pattern": "^[a-z_]+(\\.[a-z_]+)*(,[a-z_]+(\\.[a-z_]+)*)*$"
    },
    "where": {
      "description": "Extra raw Paymo filter ANDed onto the typed ones, e.g. `billable=true` or `name like Website`. Operators: = > >= < <= != like, not like, in (a,b), not in (a,b).",
      "type": "string",
      "maxLength": 500
    },
    "limit": {
      "description": "Max items to return (default 100, max 500). Paymo has no pagination; results beyond this are truncated.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List projects (id, name, code, client_id, active, billable, budget_hours, users, managers), optionally filtered. Paymo: GET /api/projects.

{
  "type": "object",
  "properties": {
    "active": {
      "description": "true = active projects, false = archived.",
      "type": "boolean"
    },
    "client_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only projects for this client."
    },
    "user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only projects this user is assigned to."
    },
    "manager_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only projects this user manages."
    },
    "billable": {
      "description": "Only billable (true) or non-billable (false) projects.",
      "type": "boolean"
    },
    "include": {
      "description": "Related objects to embed (Paymo `include`), comma-separated, e.g. client or tasklists.tasks.",
      "type": "string",
      "maxLength": 300,
      "pattern": "^[a-z_]+(\\.[a-z_]+)*(,[a-z_]+(\\.[a-z_]+)*)*$"
    },
    "where": {
      "description": "Extra raw Paymo filter ANDed onto the typed ones, e.g. `billable=true` or `name like Website`. Operators: = > >= < <= != like, not like, in (a,b), not in (a,b).",
      "type": "string",
      "maxLength": 500
    },
    "limit": {
      "description": "Max items to return (default 100, max 500). Paymo has no pagination; results beyond this are truncated.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch one project, optionally with related objects inline, e.g. include=tasklists.tasks for the whole task tree or include=client. Paymo: GET /api/projects/{id}.

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The project id."
    },
    "include": {
      "description": "Related objects to embed (Paymo `include`), comma-separated, e.g. client or tasklists.tasks.",
      "type": "string",
      "maxLength": 300,
      "pattern": "^[a-z_]+(\\.[a-z_]+)*(,[a-z_]+(\\.[a-z_]+)*)*$"
    }
  },
  "required": [
    "project_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List task lists (id, name, project_id, milestone_id), e.g. to pick a tasklist_id when creating a task. Paymo: GET /api/tasklists.

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only task lists from this project."
    },
    "include": {
      "description": "Related objects to embed (Paymo `include`), comma-separated, e.g. client or tasklists.tasks.",
      "type": "string",
      "maxLength": 300,
      "pattern": "^[a-z_]+(\\.[a-z_]+)*(,[a-z_]+(\\.[a-z_]+)*)*$"
    },
    "limit": {
      "description": "Max items to return (default 100, max 500). Paymo has no pagination; results beyond this are truncated.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List tasks (id, name, code, project_id, tasklist_id, complete, due_date, users, priority), filtered by project, task list, assignee or completion. my_tasks=true returns the caller's 'My Tasks'. Paymo: GET /api/tasks.

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only tasks from this project."
    },
    "tasklist_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only tasks from this task list."
    },
    "user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only tasks assigned to this user."
    },
    "complete": {
      "description": "true = completed tasks, false = open tasks.",
      "type": "boolean"
    },
    "my_tasks": {
      "description": "true = tasks assigned to the calling user or to nobody, in their projects.",
      "type": "boolean"
    },
    "include": {
      "description": "Related objects to embed (Paymo `include`), comma-separated, e.g. client or tasklists.tasks.",
      "type": "string",
      "maxLength": 300,
      "pattern": "^[a-z_]+(\\.[a-z_]+)*(,[a-z_]+(\\.[a-z_]+)*)*$"
    },
    "where": {
      "description": "Extra raw Paymo filter ANDed onto the typed ones, e.g. `billable=true` or `name like Website`. Operators: = > >= < <= != like, not like, in (a,b), not in (a,b).",
      "type": "string",
      "maxLength": 500
    },
    "limit": {
      "description": "Max items to return (default 100, max 500). Paymo has no pagination; results beyond this are truncated.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch one task, optionally with related objects: include=thread.comments for its comments, subtasks, entries (time logged), files, project. Paymo: GET /api/tasks/{id}.

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The task id."
    },
    "include": {
      "description": "Related objects to embed (Paymo `include`), comma-separated, e.g. client or tasklists.tasks.",
      "type": "string",
      "maxLength": 300,
      "pattern": "^[a-z_]+(\\.[a-z_]+)*(,[a-z_]+(\\.[a-z_]+)*)*$"
    }
  },
  "required": [
    "task_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List time entries (id, task_id, user_id, project_id, start_time/end_time or date, duration in seconds, description, billed). At least one filter is required. from/to filter by the entry's time interval; running_only=true returns running timers. Paymo: GET /api/entries.

{
  "type": "object",
  "properties": {
    "project_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only entries from this project."
    },
    "task_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only entries for this task."
    },
    "user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only entries for this user."
    },
    "client_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only entries for this client."
    },
    "from": {
      "type": "string",
      "description": "Interval start (YYYY-MM-DD = start of that day UTC). Requires `to`."
    },
    "to": {
      "type": "string",
      "description": "Interval end (YYYY-MM-DD = end of that day UTC). Requires `from`."
    },
    "billed": {
      "description": "true = already invoiced, false = unbilled.",
      "type": "boolean"
    },
    "running_only": {
      "description": "true = only running timers (no end_time yet).",
      "type": "boolean"
    },
    "include": {
      "description": "Related objects to embed (Paymo `include`), comma-separated, e.g. client or tasklists.tasks.",
      "type": "string",
      "maxLength": 300,
      "pattern": "^[a-z_]+(\\.[a-z_]+)*(,[a-z_]+(\\.[a-z_]+)*)*$"
    },
    "where": {
      "description": "Extra raw Paymo filter ANDed onto the typed ones, e.g. `billable=true` or `name like Website`. Operators: = > >= < <= != like, not like, in (a,b), not in (a,b).",
      "type": "string",
      "maxLength": 500
    },
    "limit": {
      "description": "Max items to return (default 100, max 500). Paymo has no pagination; results beyond this are truncated.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List invoices (id, number, client_id, status, currency, date, due_date, subtotal, total). Paymo: GET /api/invoices.

{
  "type": "object",
  "properties": {
    "client_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only invoices for this client."
    },
    "status": {
      "description": "Only invoices with this status.",
      "type": "string",
      "enum": [
        "draft",
        "sent",
        "viewed",
        "paid",
        "void"
      ]
    },
    "where": {
      "description": "Extra raw Paymo filter ANDed onto the typed ones, e.g. `billable=true` or `name like Website`. Operators: = > >= < <= != like, not like, in (a,b), not in (a,b).",
      "type": "string",
      "maxLength": 500
    },
    "limit": {
      "description": "Max items to return (default 100, max 500). Paymo has no pagination; results beyond this are truncated.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Fetch one invoice with totals, and (by default) its line items and payments. Paymo: GET /api/invoices/{id}?include=invoiceitems,invoicepayments.

{
  "type": "object",
  "properties": {
    "invoice_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The invoice id."
    },
    "include_items": {
      "description": "Include line items and payments (default true).",
      "type": "boolean"
    }
  },
  "required": [
    "invoice_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List expenses (id, client_id, project_id, user_id, amount, currency, date, notes, invoiced, tags). Paymo: GET /api/expenses.

{
  "type": "object",
  "properties": {
    "client_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only expenses for this client."
    },
    "project_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Only expenses for this project."
    },
    "invoiced": {
      "description": "true = already invoiced, false = not yet invoiced.",
      "type": "boolean"
    },
    "date_from": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Only expenses dated on/after this day."
    },
    "date_to": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Only expenses dated on/before this day."
    },
    "where": {
      "description": "Extra raw Paymo filter ANDed onto the typed ones, e.g. `billable=true` or `name like Website`. Operators: = > >= < <= != like, not like, in (a,b), not in (a,b).",
      "type": "string",
      "maxLength": 500
    },
    "limit": {
      "description": "Max items to return (default 100, max 500). Paymo has no pagination; results beyond this are truncated.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Create a project. Note: if client_id is omitted Paymo auto-creates a 'Sample Client'. Free plans have an active-projects limit (403). Paymo: POST /api/projects.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Project name."
    },
    "description": {
      "description": "Project description.",
      "type": "string"
    },
    "client_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Client the project is for."
    },
    "billable": {
      "description": "Whether the project is billable.",
      "type": "boolean"
    },
    "price_per_hour": {
      "description": "Hourly rate for time & materials projects.",
      "type": "number",
      "minimum": 0
    },
    "budget_hours": {
      "description": "Budget in hours.",
      "type": "number",
      "minimum": 0
    },
    "users": {
      "description": "User ids to assign.",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "managers": {
      "description": "User ids of managers (subset of users).",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Create a task in a task list (tasklist_id) or a project (project_id — goes to its 'Default Task List'). Paymo: POST /api/tasks.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Task name."
    },
    "tasklist_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Task list to add the task to."
    },
    "project_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Project to add the task to (used when tasklist_id is not given)."
    },
    "description": {
      "description": "Task description / notes.",
      "type": "string"
    },
    "users": {
      "description": "Assignee user ids.",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "due_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Due date."
    },
    "billable": {
      "description": "Whether the task is billable.",
      "type": "boolean"
    },
    "budget_hours": {
      "description": "Budget hours for the task.",
      "type": "number",
      "minimum": 0
    },
    "priority": {
      "description": "Priority: 25 low, 50 normal, 75 high, 100 critical.",
      "anyOf": [
        {
          "type": "number",
          "const": 25
        },
        {
          "type": "number",
          "const": 50
        },
        {
          "type": "number",
          "const": 75
        },
        {
          "type": "number",
          "const": 100
        }
      ]
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Update a task — rename, re-describe, reassign (users replaces the whole list), set due date or priority, mark complete/incomplete, move to another task list or workflow status. Only the fields given are changed. Paymo: PUT /api/tasks/{id}.

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The task id."
    },
    "name": {
      "description": "New name.",
      "type": "string",
      "minLength": 1
    },
    "description": {
      "description": "New description.",
      "type": "string"
    },
    "complete": {
      "description": "true = mark complete, false = reopen.",
      "type": "boolean"
    },
    "users": {
      "description": "New FULL list of assignee user ids.",
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "due_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "New due date."
    },
    "priority": {
      "description": "Priority: 25 low, 50 normal, 75 high, 100 critical.",
      "anyOf": [
        {
          "type": "number",
          "const": 25
        },
        {
          "type": "number",
          "const": 50
        },
        {
          "type": "number",
          "const": 75
        },
        {
          "type": "number",
          "const": 100
        }
      ]
    },
    "tasklist_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Move to this task list."
    },
    "status_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Workflow status id."
    },
    "budget_hours": {
      "description": "New budget hours.",
      "type": "number",
      "minimum": 0
    }
  },
  "required": [
    "task_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Log a completed time entry on a task, EITHER as date + duration_seconds OR as start_time + end_time (min 1 minute). To start a live timer use paymo_start_timer. Paymo: POST /api/entries.

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Task the time is for."
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Day of the entry (with duration_seconds)."
    },
    "duration_seconds": {
      "description": "Length in seconds (with date), e.g. 3600 = 1h.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "start_time": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2})$",
      "description": "Start (with end_time)."
    },
    "end_time": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2})$",
      "description": "End (with start_time)."
    },
    "description": {
      "description": "What was done.",
      "type": "string"
    },
    "user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "User to log the time for (default: the API key's user)."
    }
  },
  "required": [
    "task_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Edit a time entry: description, task, or its length. duration_seconds only applies to date+duration entries; for start/end entries change end_time instead. Paymo: PUT /api/entries/{id}.

{
  "type": "object",
  "properties": {
    "entry_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The time entry id."
    },
    "description": {
      "description": "New description.",
      "type": "string"
    },
    "task_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Move the entry to this task."
    },
    "duration_seconds": {
      "description": "New length in seconds (date+duration entries only).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "start_time": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2})$",
      "description": "New start (start/end entries only)."
    },
    "end_time": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2})$",
      "description": "New end (start/end entries only)."
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "New day (date+duration entries only)."
    }
  },
  "required": [
    "entry_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Start a running timer on a task (a time entry with a start_time and no end_time). A user can have only one running timer; if one is running Paymo returns 409. Paymo: POST /api/entries.

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Task to time."
    },
    "start_time": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2})$",
      "description": "When the timer started (default: now)."
    },
    "description": {
      "description": "What is being worked on.",
      "type": "string"
    },
    "user_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "User to start the timer for (default: the API key's user)."
    }
  },
  "required": [
    "task_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Stop a running timer by setting its end_time (default: now). The final duration must be at least 1 minute. Find running timers with paymo_list_time_entries running_only=true. Paymo: PUT /api/entries/{id}.

{
  "type": "object",
  "properties": {
    "entry_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "The running timer's time-entry id."
    },
    "end_time": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(Z|[+-]\\d{2}:\\d{2})$",
      "description": "When the timer stopped (default: now)."
    },
    "description": {
      "description": "Final description.",
      "type": "string"
    }
  },
  "required": [
    "entry_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Add a comment to a task's discussion thread (content may contain basic HTML). Read existing comments with paymo_get_task include=thread.comments. Paymo: POST /api/comments.

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Task to comment on."
    },
    "content": {
      "type": "string",
      "minLength": 1,
      "description": "Comment text."
    }
  },
  "required": [
    "task_id",
    "content"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}