Beebole GraphQL Mutations: Log Time, Approve, Manage Data

Mutations are the GraphQL write operations of the Beebole API. They create, update, archive, or delete data in your Beebole account — logging time and expenses, running the timesheet approval workflow, and managing people, projects, tasks, billing and cost rates, and organization settings. Send every mutation as a POST request to https://app.beebole.com/graphql with your key in the apikey HTTP header (see Introduction). Each mutation returns the affected object so you can read back fields in the same request. Object IDs are exposed as id (not _id). For read-only operations, see Queries.

Time durations in Beebole are expressed in milliseconds. To log 2 hours, pass 7200000 (2 × 60 × 60 × 1000), not 120.

Time records

A time record is one logged entry for a person on a given day, linked to projects, a task, or an absence type. Durations are in milliseconds.

Mutation	Key arguments
`addTimeRecord`	`startTime`, `duration`, `personId`, optional `endTime`, `taskId`, `absenceId`, `projectIds`
`editTimeRecordStartTime`	`id`, `startTime`
`editTimeRecordEndTime`	`id`, `endTime`
`editTimeRecordDuration`	`id`, `duration` (milliseconds)
`editTimeRecordProjects`	`id`, `projectIds`
`editTimeRecordTask`	`id`, `taskId`
`editTimeRecordAbsence`	`id`, `absenceId`
`editTimeRecordComment`	`id`, `comment`
`editTimeRecordNonBillable`	`id`, `nonBillable`
`editTimeRecordWfh`	`id`, `wfh`
`deleteTimeRecords`	`ids` (array)
`cloneTimeRecords`	`personId`, `sourceStartTime`, `sourceEndTime`, `targetStartTime`, `targetEndTime`, optional `replaceExisting`

startTime and endTime are Unix timestamps in milliseconds. duration is an integer count of milliseconds.

Log a time entry

This logs 2 hours (7200000 milliseconds) for a person against a task:

mutation {
  addTimeRecord(
    startTime: 1717200000000
    duration: 7200000
    personId: "64a1b2c3d4e5f6a7b8c9d0e1"
    taskId: "64a1b2c3d4e5f6a7b8c9d0e3"
  ) {
    id
    duration
    startTime {
      ts
      iso
    }
  }
}

Clone a week of time records

cloneTimeRecords copies a person’s entries from a source period to a target period. Set replaceExisting: true to clear the target period first.

mutation {
  cloneTimeRecords(
    personId: "64a1b2c3d4e5f6a7b8c9d0e1"
    sourceStartTime: 1717200000000
    sourceEndTime: 1717718400000
    targetStartTime: 1717804800000
    targetEndTime: 1718323200000
    replaceExisting: true
  ) {
    id
    startTime {
      ts
      iso
    }
    duration
  }
}

Expense records

An expense record is an actual expense logged against a person and/or a project. The amount is sent as value with an optional currency; if you omit the currency, Beebole uses the person’s or organization’s default.

Mutation	Key arguments
`addExpenseRecord`	`date`, `expenseTypeId`, `value`, optional `currency`, `personId`, `projectId`, `comment`
`deleteExpenseRecord`	`id`
`editExpenseRecordDate`	`id`, `date`
`editExpenseRecordExpense`	`id`, `expenseTypeId`
`editExpenseRecordPerson`	`id`, `personId` (null to remove)
`editExpenseRecordProject`	`id`, `projectId` (null to remove)
`editExpenseRecordAmountValue`	`id`, `value`
`editExpenseRecordAmountCurrency`	`id`, `currency`
`editExpenseRecordComment`	`id`, `comment`

At least one of personId or projectId is required on addExpenseRecord — both are otherwise optional.

Log an expense

mutation {
  addExpenseRecord(
    date: 1717200000000
    expenseTypeId: "64a1b2c3d4e5f6a7b8c9d0e4"
    value: 4250
    currency: "EUR"
    personId: "64a1b2c3d4e5f6a7b8c9d0e1"
  ) {
    id
    amount {
      value
      currency
    }
    date {
      ts
      iso
    }
  }
}

Timesheets and approvals

The approval workflow runs through three mutations. There is no single “add approval event” call — submitting, approving, and rejecting are distinct operations that return a BeeboleApprovalEvent.

Mutation	Key arguments
`submitTimesheet`	`personId`, `startTime`, `endTime`
`approveTimesheet`	`id` (the submit event ID)
`rejectTimesheet`	`id` (the submit event ID), `stage`, `comment`
`sendTimesheetReminder`	`personIds` (array), `startTime`, `endTime`

Beebole determines the current approval stage automatically. submitTimesheet returns the submit event whose id you pass to approveTimesheet or rejectTimesheet.

Submit a timesheet for a period

mutation {
  submitTimesheet(
    personId: "64a1b2c3d4e5f6a7b8c9d0e1"
    startTime: 1717200000000
    endTime: 1719792000000
  ) {
    id
    status
    stage
  }
}

Approve or reject

mutation {
  approveTimesheet(id: "64a1b2c3d4e5f6a7b8c9d0e5") {
    id
    status
  }
}

mutation {
  rejectTimesheet(
    id: "64a1b2c3d4e5f6a7b8c9d0e5"
    stage: 0
    comment: "Please add the client meeting on Tuesday."
  ) {
    id
    status
    comment
  }
}

People

Mutation	Key arguments
`addPerson`	`name`, `email`, `roleId`, optional `color`
`deletePerson`	`id`, optional `check` (dry-run)
`duplicatePerson`	`id`, `name`, optional `email`, `roleId`
`archivePerson` / `unarchivePerson`	`id`
`archivePersons` / `unarchivePersons`	`ids` (array)
`editPersonName`	`id`, `name`
`editPersonEmail`	`id`, `email`
`editPersonRole`	`id`, `roleId`
`editPersonStartDate`	`id`, `startDate`
`editPersonColor`	`id`, `color`
`editPersonLang`	`id`, `lang`

deletePerson accepts check: true to validate references without deleting.

Create a person

mutation {
  addPerson(
    name: "Alice Martin"
    email: "alice@example.com"
    roleId: "64a1b2c3d4e5f6a7b8c9d0e1"
  ) {
    id
    name
  }
}

Projects

Mutation	Key arguments
`addProject`	`name`, optional `categoryId`, `parentId`, `color`
`deleteProject`	`id`, optional `check` (dry-run)
`deleteProjects`	`ids` (array)
`duplicateProject`	`id`, `name`, optional `parentId`
`archiveProject` / `unarchiveProject`	`id`
`archiveProjects` / `unarchiveProjects`	`ids` (array)
`editProjectName`	`id`, `name`
`editProjectParent`	`id`, `parentId`
`editProjectColor`	`id`, `color`
`editProjectAvailability`	`id`, `availability`
`addProjectCategory`	`name`
`deleteProjectCategory`	`id`
`editProjectCategoryName`	`id`, `name`
`editProjectCategoryLevelNames`	`id`, `levelNames`

To create a subproject, pass the parent project’s parentId. The subproject inherits the parent’s category unless you set a different categoryId.

Create a project

mutation {
  addProject(
    name: "Website Redesign"
    categoryId: "64a1b2c3d4e5f6a7b8c9d0e2"
  ) {
    id
    name
  }
}

Tasks

Tasks are independent planning entities you create, schedule, and track time against. Task categories, the plannings of the Beebole app, organize tasks into workflow statuses.

Mutation	Key arguments
`addTask`	optional `name`, `categoryId`, `parentId`, `color`, `statusId`
`deleteTask`	`id`, optional `check` (dry-run)
`archiveTask` / `unarchiveTask`	`id`
`archiveTasks` / `unarchiveTasks`	`ids` (array)
`editTaskName`	`id`, `name`
`editTaskParent`	`id`, `parentId`
`editTaskColor`	`id`, `color`
`editTaskStatus`	`id`, `statusId`
`editTaskPeriod`	`id`, optional `startTime`, `endTime`, `effort`
`editTaskDuration`	`id`, `effort` (milliseconds)
`moveTasksToStatus`	`taskIds`, `targetStatusId`, `orderedTaskIds`

Task categories and their workflow statuses are managed with the category mutations:

Mutation	Key arguments
`addTaskCategoryStatus`	`categoryId`, `name`
`deleteTaskCategoryStatus`	`categoryId`, `statusId`
`editTaskCategoryStatusName`	`statusId`, `name`
`editTaskCategoryStatusColor`	`statusId`, `color`
`editTaskCategoryStatusMaxConcurrentTasks`	`statusId`, `maxConcurrentTasks`
`editCategoryTaskMove`	`categoryId`, `taskMove`

To move a task to another status, use editTaskStatus (single task) or moveTasksToStatus (one or more tasks). Both only move tasks between statuses of the same category: a status from another category is refused with CantAssignStatusFromOtherCategory, and no mutation moves a task to another category. editCategoryTaskMove sets the Dependent tasks option of the Gantt and Staffing views, which decides how dependent tasks follow when a task they depend on moves: 0 for Free, 1 for Pushing, 2 for Together. archiveTask and unarchiveTask (and their plural forms) are what the Beebole app shows as Done and Reopen on a task: a done task is an archived task. Archiving does not change the task’s status. addTask without a name creates a nameless task, whose displayed name comes from its owner or project. In a planning set to Bookings, a name is refused with CantNameTaskInBookingsPlanning, since a booking is always named after its project and person.

Create a task

mutation {
  addTask(
    name: "Write copy"
    categoryId: "64a1b2c3d4e5f6a7b8c9d0e3"
  ) {
    id
    name
  }
}

Billing and cost rates

A billing or cost rate is a dated amount set on the organization, a tag, a person, or a project. It takes effect on its startTime, the From date in Beebole, and applies until a rate with a later date takes over. Rates cascade from the organization, tags, and parent projects to the people and projects that have none of their own. How Beebole picks the rate of each time entry is described in Billing and Costs. A time record carries no amount, only its nonBillable flag. Beebole computes billing and cost in reports from the rates, so to value time entries, including entries you import, set rates whose dates cover them.

Mutation	Key arguments
`addOrganisationBilling` / `addOrganisationCost`	`startTime`, `amount`, `method`, optional `splitType`, `repeatEnabled`
`addTagBilling` / `addTagCost`	`tagId`, `startTime`, `amount`, `method`, optional `splitType`, `repeatEnabled`
`addPersonBilling` / `addPersonCost`	`personId`, `startTime`, `amount`, `method`, optional `splitType`, `repeatEnabled`
`addProjectBilling` / `addProjectCost`	`projectId`, `startTime`, `amount`, `method`, optional `splitType`, `repeatEnabled`
`editBillingAmount` / `editCostAmount`	`id`, `amount`
`editBillingStartTime` / `editCostStartTime`	`id`, `startTime`
`editBillingMethod` / `editCostMethod`	`id`, `method`
`deleteProjectBilling` / `deleteProjectCost`	`projectId`, `billingId` or `costId`
`duplicateProjectBilling` / `duplicateProjectCost`	`projectId`, `billingId` or `costId`
`localizeProjectBilling` / `localizeProjectCost`	`projectId`, `rateIds` (array)

The arguments of the add mutations:

startTime is a BeeboleTimestamp in milliseconds. Pass midnight UTC of the From date (1735689600000 for January 1, 2025): a rate applies to the entries that start at or after it. A record can’t hold two billing rates, or two cost rates, with the same startTime: the second is refused with RateWithSameDateAlreadyExists.
amount is a BeeboleInputAmount { value, currency }. value is an integer in the currency’s smallest unit (15000 with "USD" is $150.00), and currency is an ISO 4217 code.
method is hourly, daily, fixed, or nonBillable: the Hourly rate, Daily rate, Fixed fee, and Non-billable methods (No cost on a cost rate).
splitType is persons, projects, or tags, to give each person, project, or tag its own amount. Fill the split with addBillingSplit (rateId, entityId, amount, nonBillable), and adjust it with editBillingSplitAmount, editBillingSplitNonBillable, and removeBillingSplit, or their Cost twins.
repeatEnabled makes a fixed fee recur. The editBillingRepeat… and editCostRepeat… mutations set the recurrence.

The delete, duplicate, and localize mutations exist for each kind of record (deleteOrganisationBilling, deleteTagBilling, deletePersonBilling, and so on), with the record’s ID argument except on the organization. A duplicate is dated one day after the record’s latest rate. A localize mutation copies the inherited rates you list in rateIds onto a record that has no rates of its own, so you can then change them for that record only. Every rate mutation returns a BeeboleBilling or a BeeboleCost. Read rates and their id through the billings and costs fields, as shown under Billing and cost rates on the Queries page. An inherited rate’s id belongs to the record it is set on, so editing it changes the rate for everything that inherits it. Use the Billing mutations on billing rates and the Cost mutations on cost rates: a cost rate passed to editBillingAmount fails with InvalidRateType. Adding a billing rate needs a plan that includes billing rates, and adding a cost rate one that includes costs; otherwise the call fails with SubscriptionFeatureRequired:billing or SubscriptionFeatureRequired:costs.

Add a rate and change its amount

This sets an hourly billing rate of $150.00 on a project, from January 1, 2025:

mutation {
  addProjectBilling(
    projectId: "64a1b2c3d4e5f6a7b8c9d0e2"
    startTime: 1735689600000
    amount: { value: 15000, currency: "USD" }
    method: "hourly"
  ) {
    id
    method
    startTime {
      ts
      iso
    }
    amount {
      value
      currency
    }
  }
}

To change the amount to $165.00, pass the returned id to editBillingAmount:

mutation {
  editBillingAmount(
    id: "64a1b2c3d4e5f6a7b8c9d0e6"
    amount: { value: 16500, currency: "USD" }
  ) {
    id
    amount {
      value
      currency
    }
  }
}

editBillingAmount changes the rate for every entry it covers, past ones included. To raise a rate from a given date only, add a new rate with that startTime instead: entries before it keep the previous rate.

Custom fields

Custom field definitions and the values stored on records have separate mutations. Definitions are managed with addCustomField, duplicateCustomField, archiveCustomField / unarchiveCustomField (and their plural forms), deleteCustomField, editCustomFieldName, editCustomFieldType, a family of editCustomField…Option… mutations for each type’s options, and the editCustomFieldVisibility… mutations that decide where a field appears. Values are written with:

Mutation	Key arguments
`addCustomFieldValue`	`customFieldId`, `entityType`, `entityId`, and one of `textValue`, `numberValue`, `dateValue`, `dateTimeValue`, `urlValue`, `booleanValue`
`editCustomFieldValueText`	`id`, `textValue`
`editCustomFieldValueNumber`	`id`, `numberValue`
`editCustomFieldValueDate`	`id`, `dateValue`
`editCustomFieldValueDateTime`	`id`, `dateTimeValue`
`editCustomFieldValueUrl`	`id`, `urlValue`
`editCustomFieldValueBoolean`	`id`, `booleanValue`
`deleteCustomFieldValue`	`id`

entityType is one of Person, Project, Task, Tag, TimeRecord, or AbsenceType; dateValue and dateTimeValue are UTC timestamps. As in Beebole, deleteCustomField is refused while any value is stored on the field — delete or clear the values first, or archive the field.

Store an external identifier on a person

mutation {
  addCustomFieldValue(
    customFieldId: "64a1b2c3d4e5f6a7b8c9d0e1"
    entityType: "Person"
    entityId: "64a1b2c3d4e5f6a7b8c9d0e2"
    textValue: "HR-00421"
  ) {
    id
    textValue
  }
}

To find the record that carries a given identifier, read the field’s values with getCustomFieldValues — see Custom fields on the Queries page.

Organization

Organization settings are edited on the single current organization, so these mutations take no id. The GraphQL field names keep the British spelling Organisation.

Mutation	Key arguments
`editOrganisationName`	`name`
`editOrganisationColor`	`color`
`editGoogleSSO`	`google` (input)
`editMicrosoftSSO`	`microsoft` (input)
`editCustomSSO`	`customSSO` (input, null to clear)

Rename the organization

mutation {
  editOrganisationName(name: "Acme Corp") {
    id
    name
  }
}

Mutations that delete data cannot be undone through the API. Where a check argument is available (deletePerson, deleteProject, deleteTask), pass check: true first to validate references without deleting anything.

When creating records, store the returned id values so you can reference or update them in follow-up mutations. Batch mutations such as archivePersons, deleteProjects, and deleteTimeRecords accept arrays — prefer them over looping single-item calls.

API Introduction

Authenticate with your API key and send your first request.

Queries

Read time records, people, projects, and tasks over GraphQL.

Schema explorer

Browse the full GraphQL schema interactively.

GraphQL API

Examples

MCP & Webhooks

Legacy

GraphQL Mutations to Create and Update

Time records

Log a time entry

Clone a week of time records

Expense records

Log an expense

Timesheets and approvals

Submit a timesheet for a period

Approve or reject

People

Create a person

Projects

Create a project

Tasks

Create a task

Billing and cost rates

Add a rate and change its amount

Custom fields

Store an external identifier on a person

Organization

Rename the organization

API Introduction

Queries

Schema explorer

​Time records

​Log a time entry

​Clone a week of time records

​Expense records

​Log an expense

​Timesheets and approvals

​Submit a timesheet for a period

​Approve or reject

​People

​Create a person

​Projects

​Create a project

​Tasks

​Create a task

​Billing and cost rates

​Add a rate and change its amount

​Custom fields

​Store an external identifier on a person

​Organization

​Rename the organization

​Related content

API Introduction

Queries

Schema explorer

Time records

Log a time entry

Clone a week of time records

Expense records

Log an expense

Timesheets and approvals

Submit a timesheet for a period

Approve or reject

People

Create a person

Projects

Create a project

Tasks

Create a task

Billing and cost rates

Add a rate and change its amount

Custom fields

Store an external identifier on a person

Organization

Rename the organization

Related content