openapi: 3.1.0
info:
  title: COR Attachments Users API
  description: The COR API lets you integrate with projectcor.com applications using simple HTTP methods, in either XML or JSON formats, making this an ideal API for developing integrations with other softwares, external clients or mobile applications
  version: 1.0.0
servers:
- url: https://api.projectcor.com/v1
  description: Production server
security:
- bearerAuth: []
tags:
- name: Users
paths:
  /users:
    get:
      tags:
      - Users
      summary: Get Users
      description: 'Retrieves a paginated list of users with optional filtering. By default, responses are paginated with 20 items per page.


        **Filter options:**

        - `withHiddenUsers` (boolean): Include hidden users in the response

        - `withPosition` (boolean): Include user positions in the response

        - `createdAt` (string): Filter users created on or after this date (YYYY-MM-DD)

        - `updatedAt` (string): Filter users updated on or after this date (YYYY-MM-DD)'
      parameters:
      - name: page
        in: query
        schema:
          type:
          - integer
          - boolean
          default: 1
        description: 'Page number (default: 1). Set to `false` to disable pagination.'
      - name: perPage
        in: query
        schema:
          type: integer
          default: 20
        description: 'Number of items per page (default: 20).'
      - name: filters
        in: query
        schema:
          type: string
        description: 'URL-encoded JSON filters object. Available fields: `withHiddenUsers`, `withPosition`, `createdAt`, `updatedAt`.'
        example: '{"withHiddenUsers":true, "withPosition":true, "createdAt": "2024-01-01", "updatedAt": "2024-01-31"}'
      responses:
        '200':
          description: Paginated list of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
              example:
                total: '100'
                perPage: 20
                page: 1
                lastPage: 20
                data:
                - id: 123
                  first_name: Jane
                  picture: https://user-images.staging.projectcor.com/local/Upload/ProfilePictures/50x50/user.png
                  last_name: Doe
                  email: jane.doe@example.com
                  cuil: ''
                  remaining_hours: 100
                  user_position_id: 3
                  role_id: 2
                  daily_hours: 0
                  labels: []
                  plan_id: 5
                  plan_name: Capacity Planning
                  hidden: false
                  position_name: null
                  category_id: null
                  category_name: null
                  gmt: -03:00
                  leaves: []
                - id: 456
                  first_name: John
                  picture: https://user-images.staging.projectcor.com/local/Upload/ProfilePictures/50x50/user.png
                  last_name: Smith
                  email: john.smith@example.com
                  cuil: ''
                  remaining_hours: 80
                  user_position_id: 2
                  role_id: 4
                  daily_hours: 8
                  labels:
                  - id: 210595
                    lang: es
                    name: Desarrollo web
                  plan_id: 5
                  plan_name: Capacity Planning
                  hidden: false
                  position_name: null
                  category_id: null
                  category_name: null
                  gmt: -03:00
                  leaves: []
    post:
      tags:
      - Users
      summary: Create a user
      description: "Creates a user using a POST http method. The user will receive an invitation email.\n\n**Required properties:**\n- `first_name` — User given name\n- `last_name` — User family name\n- `email` — User email\n- `role_id` — ID of the user's role:\n  - **1**: C-Level\n  - **2**: Director\n  - **3**: Project Manager\n  - **4**: Collaborator\n  - **5**: Freelancer\n  - **6**: Client"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreateInput'
            example:
              first_name: John
              last_name: Doe
              email: john.doe@example.com
              role_id: 1
              user_position_id: 2
              phone: 123-456-7890
              description: Senior Developer
              birthday: '1990-01-01'
              work_in: Engineering
              hourly_rate: 50.0
              monthly_hours: 160
              daily_hours: 8
              salary: 4500
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /users/{user_id}:
    put:
      tags:
      - Users
      summary: Update a user
      description: 'Updates a user using a PUT http method.


        ⚠️ **Important:** Use caution when using this endpoint. The system will replace the existing user with the values passed in the request body.


        **Available properties:**

        - `first_name` — User given name

        - `last_name` — User family name

        - `email` — User email

        - `role_id` — ID of the user''s role (1-6)

        - `user_position_id` — ID of the user''s position

        - `phone`, `description`, `birthday`, `work_in`

        - `hourly_rate`, `monthly_hours`, `daily_hours`

        - `plan_id` — 4: Project Management, 5: Capacity Planning

        - `hidden`, `charge_hours` — Boolean values

        - `salary` — New monthly salary amount

        - `salary_from` — Month from which salary should apply (MM-YYYY). Defaults to the current month if `salary` is provided.'
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: integer
        description: User ID
        example: 123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdateInput'
            example:
              first_name: John
              last_name: Doe
              email: john.doe@example.com
              role_id: 3
              salary: 5200
              salary_from: 01-2026
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    delete:
      tags:
      - Users
      summary: Delete a user
      description: Deletes a user from the system.
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: integer
        description: User ID to delete
        example: 123
      responses:
        '200':
          description: User deleted successfully
          content:
            application/json:
              schema:
                type: boolean
              example: true
  /users/{user_id}/labels:
    put:
      tags:
      - Users
      summary: Assign or unassign user label
      description: 'Updates a label for a specified user by their user ID. It assigns a new label to the user or unassigns the existing label with the specified `labelId`.


        **To assign a label:** Omit the `unassign` property or set it to `false`.


        **To remove a label:** Set `unassign` to `true`.'
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: integer
        description: User ID
        example: 123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserLabelInput'
            examples:
              assign_label:
                summary: Assign a label to user
                value:
                  labelId: 3003
              unassign_label:
                summary: Remove a label from user
                value:
                  labelId: 3003
                  unassign: true
      responses:
        '200':
          description: Label updated successfully
  /users/search-by-name/{name}:
    get:
      tags:
      - Users
      summary: Get users by Name
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        schema:
          type:
          - integer
          - boolean
          default: 1
        description: 'Page number (default: 1). Set to `false` to disable pagination.'
      - name: perPage
        in: query
        schema:
          type: integer
          default: 20
        description: 'Number of items per page (default: 20).'
      responses:
        '200':
          description: Paginated list of users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserListResponse'
              example:
                total: '1'
                perPage: 20
                page: 1
                lastPage: 1
                data:
                - id: 123
                  first_name: Jane
                  picture: https://user-images.staging.projectcor.com/local/Upload/ProfilePictures/50x50/user.png
                  last_name: Doe
                  email: jane.doe@example.com
                  cuil: ''
                  remaining_hours: 100
                  user_position_id: 3
                  role_id: 2
                  daily_hours: 0
                  labels:
                  - id: 210595
                    lang: es
                    name: Desarrollo web
                  plan_id: 5
                  plan_name: Capacity Planning
                  hidden: false
                  position_name: null
                  category_id: null
                  category_name: null
                  gmt: -03:00
                  leaves: []
components:
  schemas:
    UserListItem:
      description: User object returned by list endpoints (GET /users, GET /users/search-by-name).
      allOf:
      - $ref: '#/components/schemas/UserBase'
      - type: object
        properties:
          labels:
            type: array
            description: Labels assigned to the user.
            items:
              $ref: '#/components/schemas/UserAssignedLabel'
    UserListResponse:
      type: object
      properties:
        total:
          type: string
        perPage:
          type: integer
        page:
          type: integer
        lastPage:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/UserListItem'
    LeaveType:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        type_code:
          type: string
        company_id:
          type: integer
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        deleted_at:
          type: string
          format: date-time
          nullable: true
        icon_name:
          type: string
    UserLabelInput:
      type: object
      required:
      - labelId
      properties:
        labelId:
          type: integer
          description: Label ID to assign or unassign
        unassign:
          type: boolean
          description: Set to true to remove label from the user. Omit or set to false to assign the label.
          default: false
    UserUpdateInput:
      type: object
      properties:
        first_name:
          type: string
          description: User given name
        last_name:
          type: string
          description: User family name
        email:
          type: string
          format: email
          description: User email
        role_id:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          description: 'User Role: 1=C-Level, 2=Director, 3=Project Manager, 4=Collaborator, 5=Freelancer, 6=Client'
        user_position_id:
          type: integer
          description: ID of the user's position
        phone:
          type: string
          description: User phone number
        description:
          type: string
          description: User description
        birthday:
          type: string
          format: date
          description: User birthday (YYYY-MM-DD)
        work_in:
          type: string
          description: Department or area
        hourly_rate:
          type: number
          description: Hourly rate
        monthly_hours:
          type: integer
          description: Monthly hours
        daily_hours:
          type: integer
          description: Daily hours
        plan_id:
          type: integer
          enum:
          - 4
          - 5
          description: 'Plan ID: 4=Project Management, 5=Capacity Planning'
        hidden:
          type: boolean
          description: Whether user is hidden
        charge_hours:
          type: boolean
          description: Whether to charge hours
        salary:
          type: integer
          description: Monthly salary amount
        salary_from:
          type: string
          description: Month from which salary should apply (MM-YYYY). Defaults to the current month if salary is provided.
    UserAssignedLabel:
      type: object
      description: Label assigned to a user, as returned in user list endpoints.
      properties:
        id:
          type: integer
        lang:
          type: string
        name:
          type: string
    Label:
      type: object
      properties:
        id:
          type: integer
        hex:
          type: string
          description: Hex color code
        hsl:
          type: string
          nullable: true
        rgb:
          type: string
          nullable: true
        lang:
          type: string
        name:
          type: string
        color_id:
          type: integer
    Leave:
      type: object
      properties:
        id:
          type: integer
        user_id:
          type: integer
        company_id:
          type: integer
        leave_type_id:
          type: integer
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        deleted_at:
          type: string
          format: date-time
          nullable: true
        all_day:
          type: boolean
        leaveType:
          $ref: '#/components/schemas/LeaveType'
    UserBase:
      type: object
      properties:
        id:
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        picture:
          type: string
          description: URL to user's profile picture
        email:
          type: string
          format: email
        cuil:
          type: string
        remaining_hours:
          type: number
        user_position_id:
          type: integer
        role_id:
          type: integer
          description: 1=C-Level, 2=Director, 3=Project Manager, 4=Collaborator, 5=Freelancer, 6=Client
        daily_hours:
          type: number
        plan_id:
          type: integer
          description: 4=Project Management, 5=Capacity Planning
        plan_name:
          type: string
        hidden:
          type: boolean
        position_name:
          type: string
          nullable: true
        category_id:
          type: integer
          nullable: true
        category_name:
          type: string
          nullable: true
        gmt:
          type: string
          description: UTC offset from the user's last login location. Indicates the timezone configured at their last login.
          example: -03:00
        leaves:
          type: array
          items:
            $ref: '#/components/schemas/Leave'
    User:
      allOf:
      - $ref: '#/components/schemas/UserBase'
      - type: object
        properties:
          labels:
            type: array
            items:
              $ref: '#/components/schemas/Label'
            nullable: true
    UserCreateInput:
      type: object
      required:
      - first_name
      - last_name
      - email
      - role_id
      properties:
        first_name:
          type: string
          description: User given name
        last_name:
          type: string
          description: User family name
        email:
          type: string
          format: email
          description: User email
        role_id:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          description: 'User Role: 1=C-Level, 2=Director, 3=Project Manager, 4=Collaborator, 5=Freelancer, 6=Client'
        user_position_id:
          type: integer
          description: ID of the user's position
        phone:
          type: string
          description: User phone number
        description:
          type: string
          description: User description
        birthday:
          type: string
          format: date
          description: User birthday (YYYY-MM-DD)
        work_in:
          type: string
          description: Department or area
        hourly_rate:
          type: number
          description: Hourly rate
        monthly_hours:
          type: integer
          description: Monthly hours
        daily_hours:
          type: integer
          description: Daily hours
        plan_id:
          type: integer
          enum:
          - 4
          - 5
          description: 'Plan ID: 4=Project Management, 5=Capacity Planning'
        hidden:
          type: boolean
          description: Whether user is hidden
        charge_hours:
          type: boolean
          description: Whether to charge hours
        salary:
          type: integer
          description: Monthly salary amount
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    basicAuth:
      type: http
      scheme: basic