Monetize tracked time - get and set billing rates per task, per user, per task-user pair, and per group, and manage expenses through the v3 endpoints including expense categories, attachments, and assigning expenses to invoices.
openapi: 3.0.0
info:
title: TimeCamp API
version: '1.0'
contact:
email: support@timecamp.com
termsOfService: https://www.timecamp.com/terms-conditions/
description: |
Documentation for the TimeCamp system.
Get your API token here:
https://app.timecamp.com/app#/settings/users/me
Be aware that you can reach API calls limit. Once you do you will get HTTP code 429 response.
Request example:
```
GET https://app.timecamp.com/third_party/api/user?user_id=1234567
Headers:
Authorization: Bearer 87c21299960a88888888fe123
Accept: application/json
```
servers:
- url: https://app.timecamp.com/third_party/api
description: PRODUCTION
- url: https://v4.api.timecamp.com
description: PRODUCTION
tags:
- name: '[v1] User'
x-displayName: User
- name: '[v1] Entry'
x-displayName: Entry
- name: '[v1] Tags'
x-displayName: Tags
- name: '[v1] Group'
x-displayName: Group
- name: '[v1] Approvals'
x-displayName: Approvals
- name: '[v1] Computer Activities'
x-displayName: Computer Activities
- name: '[v1] Timer'
x-displayName: Timer
- name: '[v1] Task'
x-displayName: Task
- name: '[v1] Attendance'
x-displayName: Attendance
- name: '[v1] Roles & Permissions'
x-displayName: Roles & Permissions
- name: '[v1] Billing Rates'
x-displayName: Billing Rates
- name: '[v1] Userlog'
x-displayName: Userlog
- name: '[v1] Activity alert'
x-displayName: Activity alert
- name: '[v3] Timer'
x-displayName: Timer
- name: '[v3] Invoices'
x-displayName: Invoices
- name: '[v3] Computer Activities'
x-displayName: Computer Activities
- name: '[v3] Time Entry'
x-displayName: Time Entry
- name: '[v3] Time Entry Restriction'
x-displayName: Time Entry Restriction
- name: '[v3] Task Archive'
x-displayName: Task Archive
- name: '[v3] Expense'
x-displayName: Expense
- name: '[v3] Plan'
x-displayName: Plan
- name: '[v3] Storage'
x-displayName: Storage
- name: '[v3] Module'
x-displayName: Module
- name: '[v3] Marketplace'
x-displayName: Marketplace
- name: '[v3] Remote work detection'
x-displayName: Remote work detection
- name: '[v3] Data Export'
x-displayName: Data Export
- name: '[v3] Custom Fields'
x-displayName: Custom Fields
- name: '[v3] Approval'
x-displayName: Approval
- name: '[v3] Groups Stats'
x-displayName: Groups Stats
- name: '[v3] Location'
x-displayName: Location
- name: '[v3] Task Picker'
x-displayName: TaskPicker
- name: '[v3] Task'
x-displayName: Task
- name: '[v3] Tags'
x-displayName: Tags
- name: '[v3] Projects'
x-displayName: Projects
- name: '[v3] Pivot'
x-displayName: Pivot
- name: '[v3] Attendance'
x-displayName: Attendance
- name: '[v3] Attendance Requests'
x-displayName: Attendance Requests
paths:
/timer_running:
get:
summary: Get information about running timer
tags:
- '[v1] Timer'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
description: ''
minItems: 1
uniqueItems: true
items:
type: object
properties:
timer_id:
oneOf:
- type: string
- type: number
minLength: 1
user_id:
oneOf:
- type: string
- type: number
minLength: 1
task_id:
oneOf:
- type: number
- type: string
nullable: true
started_at:
type: string
minLength: 1
name:
type: string
nullable: true
required:
- timer_id
- user_id
- started_at
examples:
info about running timer with no task:
value:
- timer_id: '18'
user_id: '123'
task_id: null
started_at: '2021-03-05 14:52:06'
name: null
operationId: get-timer_running
description: Returns information about running timer.
security:
- api_key_in_header: []
/entries_merge:
post:
operationId: post--entries_merge
description: Merge two time entries into one.
tags:
- '[v1] Entry'
summary: Merge time entries
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: 'first entry id to merge '
to_id:
type: string
description: second entry id to merge
responses:
'200':
description: OK
content:
application/json:
schema:
description: ''
type: object
properties:
entry_id:
oneOf:
- type: string
- type: integer
user_id:
oneOf:
- type: string
- type: integer
minLength: 1
date:
type: string
minLength: 1
task_id:
oneOf:
- type: string
- type: integer
minLength: 1
time_span:
type: number
locked:
oneOf:
- type: string
- type: integer
minLength: 1
last_modify:
type: string
minLength: 1
note:
type: string
start_time_hour:
type: string
minLength: 1
end_time_hour:
type: string
minLength: 1
invoiceId:
oneOf:
- type: string
- type: integer
minLength: 1
billable:
oneOf:
- type: string
- type: integer
minLength: 1
examples:
merged two entries:
value:
entry_id: 105445325
user_id: '5252'
date: '2020-02-02'
task_id: '0'
time_span: 4857
locked: '0'
last_modify: '2021-03-10 09:08:30'
note: ''
start_time_hour: '13:05:47'
end_time_hour: '14:24:41'
invoiceId: '0'
billable: '0'
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
approval blocked:
value:
message: You can't edit time entry, because it is in approved or pending timesheet approval.
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
entry not found:
value:
message: Entry not found
'406':
description: Not Acceptable
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
provided same entries:
value:
message: You must provide different entries
different users:
value:
message: Both entries must belong to the same user
security:
- api_key_in_header: []
/entries_changes:
get:
operationId: get--entries_changes
description: Get time enties changes.
responses:
'200':
description: If task or tasks are not found then empty array is returned with 200 code.
content:
application/json:
schema:
type: array
items: {}
examples:
empty:
value: []
ok response:
value:
- old_time_span: 0
new_time_span: '0'
event_type: add
edited: '2020-02-10 05:05:05'
entry_id: '104950298'
duration: '0'
user_id: '5343'
description: ''
task_id: '77438101'
date: '2021-02-10'
start_time: '13:04:00'
end_time: '13:04:00'
locked: '0'
billable: 1
invoiceId: '0'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
dates not provided:
value:
message: 'you must provide "from" and "to" date like 2013-03-20 '
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
not permitted:
value:
message: you do not have permissions to get task with id {taskId} (you can set yourself as Time Tracking Administrator or Project Manager)
tags:
- '[v1] Entry'
summary: Get time entries changes
parameters:
- schema:
type: string
example: 12,13,32
in: query
name: task_ids
description: entry task id or ids
- schema:
type: string
example: 45,55,64
in: query
name: user_ids
description: entry user id or ids
- schema:
type: integer
in: query
name: limit
description: number of results to get, if empty then get all of them
- schema:
type: string
example: '2020-02-02'
in: query
name: from
description: date in `YYYY-MM-DD` format
- schema:
type: string
example: '2020-02-02'
in: query
name: to
description: date in `YYYY-MM-DD` format
security:
- api_key_in_header: []
/entries_deletions:
get:
operationId: get--entries_deletions
description: Get time enties deletions.
responses:
'200':
description: If task or tasks are not found then empty array is returned with 200 code.
content:
application/json:
schema:
type: array
items: {}
examples:
empty:
value: []
ok response:
value:
- old_time_span: 0
new_time_span: '0'
event_type: add
edited: '2020-02-10 05:05:05'
entry_id: '104950298'
duration: '0'
user_id: '5343'
description: ''
task_id: '77438101'
date: '2021-02-10'
start_time: '13:04:00'
end_time: '13:04:00'
locked: '0'
billable: 1
invoiceId: '0'
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
dates not provided:
value:
message: 'you must provide "from" and "to" date like 2013-03-20 '
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
not permitted:
value:
message: you do not have permissions to get task with id {taskId} (you can set yourself as Time Tracking Administrator or Project Manager)
tags:
- '[v1] Entry'
summary: Get time entries deletions
parameters:
- schema:
type: string
example: 12,13,32
in: query
name: task_ids
description: entry task id or ids
- schema:
type: string
example: 45,55,64
in: query
name: user_ids
description: entry user id or ids
- schema:
type: integer
in: query
name: limit
description: number of results to get, if empty then get all of them
- schema:
type: string
example: '2020-02-02'
in: query
name: from
description: date in `YYYY-MM-DD` format
- schema:
type: string
example: '2020-02-02'
in: query
name: to
description: date in `YYYY-MM-DD` format
security:
- api_key_in_header: []
parameters: []
/group:
get:
operationId: get--group
description: Get all groups.
responses:
'200':
description: OK - Array of groups
content:
application/json:
schema:
type: array
description: ''
minItems: 1
uniqueItems: true
items:
type: object
properties:
group_id:
oneOf:
- type: string
- type: integer
minLength: 1
name:
type: string
minLength: 1
parent_id:
oneOf:
- type: string
- type: integer
minLength: 1
required:
- group_id
- name
- parent_id
examples:
example response:
value:
- group_id: '530222'
name: People
parent_id: '0'
- group_id: '1764'
name: '[Inactive]'
parent_id: '1208'
tags:
- '[v1] Group'
summary: Get all groups
security:
- api_key_in_header: []
post:
operationId: post--group
description: |-
Modify existing group. Edit permission is required.
WARNING: backend might not return a response, but changes will be applied!
responses:
'200':
description: OK - returns empty response.
'400':
description: Bad Request
content:
application/json:
schema:
description: ''
type: object
properties:
message:
type: string
examples:
group fields not provided:
value:
message: 'You must send valid group fields to change: name, parent_id'
'403':
description: Forbidden
content:
application/json:
schema:
description: ''
type: object
properties:
message:
type: string
minLength: 1
required:
- message
examples:
group id not provided or you are not permitted:
value:
message: You can not change this group
tags:
- '[v1] Group'
requestBody:
content:
application/json:
schema:
description: ''
type: object
properties:
group_id:
oneOf:
- type: string
- type: integer
description: group id to modify
example: 421
name:
type: string
description: group name to set
example: NewName
parent_id:
type: string
description: parent_id to set
example: '11'
required:
- group_id
examples:
change group name:
value:
group_id: 390672
name: NewName
summary: Update group
security:
- api_key_in_header: []
delete:
operationId: delete--group
description: |-
Delete a group. Edit permission is required.
Root Group (`parent_id == 0`) cannot be deleted.
All subgroups of deleted group have their `parent_id` changed to `root_group_id`.
WARNING: backend might not return a response, but changes will be applied!
tags:
- '[v1] Group'
responses:
'200':
description: OK - empty response is returned.
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
not permitted to delete this group:
value:
message: You can not remove this group
requestBody:
content:
application/json:
schema:
description: ''
type: object
properties:
group_id:
type: number
description: group id to delete
example: 390673
required:
- group_id
examples:
example:
value:
group_id: 390673
summary: Delete group
security:
- api_key_in_header: []
put:
operationId: put--group
description: |-
Add new group. Edit permission is required.
There cannot be more than one root group (with parent_id = 0).
Maximum group tree depth is 4 levels.
If you get an error 403 `You can not change this group` try to wait about one minute and retry.
tags:
- '[v1] Group'
responses:
'200':
description: OK
content:
application/json:
schema:
description: ''
type: object
properties:
group_id:
oneOf:
- type: string
- type: integer
minLength: 1
name:
type: string
minLength: 1
admin_id:
oneOf:
- type: string
- type: integer
minLength: 1
parent_id:
oneOf:
- type: string
- type: integer
minLength: 1
root_group_id:
oneOf:
- type: string
- type: integer
minLength: 1
examples:
created group:
value:
group_id: '390673'
name: Name of New Group
admin_id: '0'
parent_id: '390672'
root_group_id: '390672'
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
not permitted to create group:
value:
message: You can not change this group
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
create group too far:
value:
message: You can create groups only up to level 4
requestBody:
content:
application/json:
schema:
description: ''
type: object
properties:
parent_id:
oneOf:
- type: string
- type: integer
description: group parent id
example: 421
name:
type: string
description: group name
example: NewName
required:
- name
examples:
create group:
value:
parent_id: 390672
name: Name of New Group
create root group:
value:
parent_id: 0
name: Name of New Root Group
summary: Create group
security:
- api_key_in_header: []
/group/{group_id}/setting:
get:
operationId: get--group-setting
description: Returns setting for given group_id.
responses:
'200':
description: OK
content:
application/json:
schema:
description: ''
type: object
properties:
groupId:
oneOf:
- type: string
- type: integer
minLength: 1
name:
type: string
minLength: 1
value:
type: string
minLength: 1
inherited:
type: boolean
inheritedFromGroup:
type: integer
examples:
companyAddress setting:
value:
groupId: '521'
name: companyAddress
value: |-
Some Street 24
51-521 City, Country
VAT EU: PL1231231212
inherited: true
inheritedFromGroup: 0
'404':
description: Not Found - returns empty array when setting not found.
content:
application/json:
schema:
type: array
items: {}
examples:
Example:
value: []
tags:
- '[v1] Group'
summary: Get group setting
parameters:
- schema:
type: string
example: companyAddress
in: query
name: name
description: name of setting to get
required: true
security:
- api_key_in_header: []
put:
operationId: put--group-setting
description: Update group setting.
tags:
- '[v1] Group'
responses:
'200':
description: OK
content:
application/json:
schema:
description: ''
type: object
properties:
groupId:
oneOf:
- type: string
- type: integer
minLength: 1
name:
type: string
minLength: 1
value:
type: string
minLength: 1
inherited:
type: boolean
inheritedFromGroup:
type: integer
examples:
changed company address:
value:
groupId: '521'
name: companyAddress
value: Some...new...adress
inherited: true
inheritedFromGroup: 0
'403':
description: Forbidden
content:
application/json:
schema:
type: object
properties:
message:
type: string
examples:
cannot change this setting:
value:
message: Setting [setting_name] cannot be changed
your plan limits you:
value:
message: You can't use this feature due to your plan.
summary: Update group setting
requestBody:
content:
application/json:
schema:
description: ''
type: object
properties:
name:
type: string
description: name of setting to be updated
example: companyAddress
value:
oneOf:
- type: string
- type: integer
description: new value
example: NewAddress
required:
- name
- value
examples:
change companyAddress:
value:
name: companyAddress
value: Some...new...adress
description: ''
security:
- api_key_in_header: []
delete:
operationId: delete--group-setting
description: Delete group setting.
tags:
- '[v1] Group'
responses:
'200':
description: OK
content:
application/json:
schema:
description: ''
type: object
properties:
groupId:
oneOf:
- type: string
- type: integer
minLength: 1
name:
type: string
minLength: 1
value:
type: string
minLength: 1
inherited:
type: boolean
inheritedFromGroup:
type: integer
examples:
deleted company address:
value:
groupId: '552'
name: companyAddress
value: ''
inherited: true
inheritedFromGroup: 0
'403':
description: Forbidden
content:
application/json:
schema:
description: ''
type: object
properties:
message:
type: string
minLength: 1
examples:
cannot delete setting or not permitted:
value:
message: Setting [setting_name] cannot be changed
summary: Delete group setting
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: name of setting to be deleted
example: companyAddress
required:
- name
examples:
delete company address:
value:
name: companyAddress
security:
- api_key_in_header: []
parameters:
- in: path
name: group_id
schema:
type: integer
description: group id
required: true
/group/{group_id}/user:
summary: Manage users in a group
get:
operationId: get--group-user
description: Get users from given group.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
description: ''
uniqueItems: true
items:
type: object
properties:
group_id:
oneOf:
- type: string
- type: integer
minLength: 1
user_id:
oneOf:
- type: string
- type: integer
minLength: 1
activated:
oneOf:
- type: string
- type: integer
minLength: 1
role_id:
oneOf:
- type: string
- type: integer
minLength: 1
id:
oneOf:
- type: string
- type: integer
minLength: 1
email:
type: string
minLength: 1
pass_hash:
type: string
minLength: 1
synch_time:
type: string
minLength: 1
login_time:
type: string
minLength: 1
register_time:
type: string
minLength: 1
time_zone:
oneOf:
- type: string
- type: integer
minLength: 1
start_of_the_week:
oneOf:
- type: string
- type: integer
minLength: 1
display_name:
type: string
minLength: 1
activation_code:
type: string
forgotten_password_code:
type: string
minLength: 1
os_username:
type: string
operating_system:
type: string
minLength: 1
login_count:
type: string
minLength: 1
plan:
oneOf:
- type: string
- type: integer
minLength: 1
language:
oneOf:
- type: string
- type: integer
minL
# --- truncated at 32 KB (452 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/timecamp/refs/heads/main/openapi/timecamp-openapi.yml