TimeCamp [v1] Group API

openapi: 3.0.0
info:
  title: TimeCamp [v1] Approvals [v1] Approvals [v1] Group 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] Group'
  x-displayName: Group
paths:
  /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:
    parameters:
    - in: path
      name: group_id
      schema:
        type: integer
      description: group id
      required: true
    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: []
  /group/{group_id}/user:
    summary: Manage users in a group
    parameters:
    - in: path
      required: true
      name: group_id
      description: group_id
      schema:
        type: integer
    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
                      minLength: 1
                    admin_pass:
                      type: string
                      nullable: true
                    admin_userid:
                      type: string
                      nullable: true
                    root_group_id:
                      oneOf:
                      - type: string
                      - type: integer
                      minLength: 1
                    last_session_id:
                      oneOf:
                      - type: string
                      - type: integer
                      nullable: true
                    already:
                      oneOf:
                      - type: string
                      - type: integer
                      minLength: 1
                    additional_email:
                      type: string
              examples:
                returned users:
                  value:
                  - group_id: '111'
                    user_id: '23'
                    activated: '1'
                    role_id: '1'
                    id: '23'
                    email: john@smith.com
                    pass_hash: gx97b8z7f98as789dfasd
                    synch_time: '2021-03-18 12:47:10'
                    login_time: '2021-03-17 07:59:02'
                    register_time: '2009-03-25 11:35:52'
                    time_zone: '0'
                    start_of_the_week: '0'
                    display_name: John Smith
                    activation_code: ''
                    forgotten_password_code: XXXyyyy333
                    os_username: ''
                    operating_system: chrome-plugin
                    login_count: '22352'
                    plan: '100'
                    language: '0'
                    admin_pass: null
                    admin_userid: null
                    root_group_id: '111'
                    last_session_id: null
                    already: '1'
                    additional_email: ''
                  - group_id: '111'
                    user_id: '32'
                    activated: '1'
                    role_id: '1'
                    id: '32'
                    email: margaret@smith.com
                    pass_hash: xxx87sgf8g6as6896g89sa98
                    synch_time: '2021-03-15 14:26:19'
                    login_time: '2021-03-15 11:41:14'
                    register_time: '2018-07-04 08:39:25'
                    time_zone: '0'
                    start_of_the_week: '0'
                    display_name: Margaret Smith
                    activation_code: null
                    forgotten_password_code: ''
                    os_username: DESKTOP-NGFIM9L\msmith
                    operating_system: Windows 10 (build 19041), 64-bit edition
                    login_count: '1885'
                    plan: '0'
                    language: '1'
                    admin_pass: 88978fgs98a798s7adasxzbv
                    admin_userid: '23'
                    root_group_id: '111'
                    last_session_id: null
                    already: '1'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: array
                items: {}
              examples:
                group not found:
                  value: []
      tags:
      - '[v1] Group'
      summary: Get users in group
      security:
      - api_key_in_header: []
    post:
      operationId: post--group-user
      description: Invite user to a group.
      tags:
      - '[v1] Group'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  statuses:
                    type: object
                    properties:
                      '[invited_email]':
                        type: object
                        properties:
                          status:
                            type: string
                            minLength: 1
              examples:
                invited and send email:
                  value:
                    statuses:
                      some@emal.com:
                        status: Invite
                invited without email:
                  value:
                    statuses:
                      some@email.com:
                        status: Add to group
                invited two users:
                  value:
                    statuses:
                      some@email.com:
                        status: Add to group
                      another@email.com:
                        status: Add to group
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  message:
                    type: string
                    minLength: 1
              examples:
                invalid email or not provided any:
                  value:
                    message: 'invalid email '
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  message:
                    type: string
                    minLength: 1
                required:
                - message
              examples:
                not permitted to invite:
                  value:
                    message: You cannot invite people to this group
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tt_global_admin:
                  type: integer
                  description: set invited users as time tracking administrators
                  enum:
                  - 0
                  - 1
                email:
                  type: array
                  description: emails to invite
                  items:
                    type: string
                dry_run:
                  type: integer
                  enum:
                  - 0
                  - 1
                  default: 0
                  description: used to simulate invite ie. check for errors in request, because it does not really invite user
                can_view_rates:
                  type: integer
                  description: can invited users view rates
                  enum:
                  - 0
                  - 1
                tt_can_create_level_1_tasks:
                  type: integer
                  description: can invited users create tasks at root level
                  enum:
                  - 0
                  - 1
                add_to_all_projects:
                  type: integer
                  description: adds invited users to all existing tasks
                  enum:
                  - 0
                  - 1
                projects:
                  type: array
                  description: array of tasks ids to add invited users to
                  items:
                    type: integer
                guests:
                  type: array
                  items:
                    type: object
                    properties:
                      guest:
                        type: boolean
                        description: is this user guest
                      email:
                        type: string
                        description: guest email
                send_mail:
                  type: integer
                  enum:
                  - 0
                  - 1
                  description: should send invitation email
                  default: 1
              required:
              - email
            encoding:
              tt_global_admin:
                style: form
                explode: true
              email:
                style: form
                explode: true
            examples:
              invite two users without sending email:
                value:
                  email:
                  - some@email.com
                  - another@email.com
                  send_email: 0
              add two guests:
                value:
                  email:
                  - some@email.com
                  - another@email.com
                  guests:
                  - guest: 1
                    email: some@email.com
                  - guest: 1
                    email: another@email.com
        description: If `tt_global_admin` is set to `1` then fields `tt_can_create_level_1_tasks` and `can_view_rates` are set to `1` too - this behavior is unchangeable.
      parameters: []
      summary: Invite user to a group
      security:
      - api_key_in_header: []
    delete:
      operationId: delete--group-user
      description: Delete user from group.
      tags:
      - '[v1] Group'
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    type: string
                    minLength: 1
                  wiped:
                    type: boolean
              examples:
                deleted user:
                  value:
                    status: ok
                    wiped: true
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  message:
                    type: string
                    minLength: 1
              examples:
                not permitted:
                  value:
                    message: You cannot remove users from this group
                user to delete not found:
                  value:
                    message: User with specified ID wasn't found
                user is not in this group:
                  value:
                    message: User does not belong to this group
      summary: Delete user from group
      security:
      - api_key_in_header: []
    put:
      operationId: put--group-user
      description: Update user in group or move user to other group.
      tags:
      - '[v1] Group'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  user_id:
                    type: array
                    items:
                      type: integer
                  role_id:
                    type: number
                  group_id:
                    type: number
              examples:
                changed role to 1:
                  value:
                    user_id:
                    - 1723605
                    role_id: 1
                    group_id: 252
                moved 2 users to different group:
                  value:
                    user_id:
                    - 51256
                    - 6362
                    role_id: 0
                    group_id: 5526
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
              examples:
                not permitted to this group:
                  value:
                    message: You cannot change roles in this group
                not permitted to user:
                  value:
                    message: 'You cannot change roles of this user: [user_id]'
                not permitted to move to this group:
                  value:
                    message: You cannot move people to this group
      summary: Update user in group
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  oneOf:
                  - type: integer
                  - type: array
                  description: user or users to edit
                  example: 552
                  items: {}
                role_id:
                  type: integer
                  description: role id to set for user/users
                  enum:
                  - 1 - administrator
                  - 2 - supervisor
                  - 3 - user
                  - 5 - guest
                group_id:
                  type: integer
                  description: group id to move user to
            examples:
              move users to new group:
                value:
                  user_id:
                  - 1723605
                  - 1706128
                  group_id: 5526
              change user role:
                value:
                  user_id: 1723605
                  role_id: 1
      security:
      - api_key_in_header: []
  /group/{group_id}/scheduler:
    parameters:
    - in: path
      required: true
      name: group_id
      description: group id
      schema:
        type: integer
    get:
      operationId: get--group-scheduler
      description: Get group scheduler.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                description: ''
                minItems: 1
                uniqueItems: true
                items:
                  type: object
                  properties:
             

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/timecamp/refs/heads/main/openapi/timecamp-v1-group-api-openapi.yml