openapi: 3.2.0
info:
  title: Connecteam API documentation Users:v1:Custom Fields API
  version: v1
servers:
- url: https://api.connecteam.com/
tags:
- name: Users:v1:Custom Fields
paths:
  /users/v1/custom-fields:
    get:
      tags:
      - Users:v1:Custom Fields
      summary: Get custom fields
      description: Retrieves all custom fields associated with the account. Optionally, filter the results by categories, names, types, or custom field IDs.
      operationId: get_custom_fields_users_v1_custom_fields_get
      security:
      - APIKeyHeader: []
      - OAuth2:
        - users.read
      parameters:
      - name: customFieldIds
        in: query
        required: false
        schema:
          title: Customfieldids
          description: Custom field ids to filter by
          type: array
          items:
            type: integer
        description: Custom field ids to filter by
      - name: categoryIds
        in: query
        required: false
        schema:
          title: Categoryids
          description: Custom field category ids to filter by
          type: array
          items:
            type: integer
        description: Custom field category ids to filter by
      - name: customFieldTypes
        in: query
        required: false
        schema:
          description: Custom field types to filter by
          type: array
          items:
            $ref: '#/components/schemas/UserCustomFields'
        description: Custom field types to filter by
      - name: customFieldNames
        in: query
        required: false
        schema:
          title: Customfieldnames
          description: Custom field names to filter by
          type: array
          items:
            type: string
        description: Custom field names to filter by
      - name: limit
        in: query
        required: false
        schema:
          title: Limit
          description: The maximum number of results to display per page
          default: 10
          minimum: 1
          maximum: 500
          type: integer
        description: The maximum number of results to display per page
      - name: offset
        in: query
        required: false
        schema:
          title: Offset
          description: The resource offset of the last successfully read resource will be returned as the paging.offset JSON property of a paginated response containing more results
          default: 0
          minimum: 0
          type: integer
        description: The resource offset of the last successfully read resource will be returned as the paging.offset JSON property of a paginated response containing more results
      - name: sort
        in: query
        required: false
        schema:
          description: Sort key
          allOf:
          - $ref: '#/components/schemas/CustomFieldsSortExternal'
        description: Sort key
      - name: order
        in: query
        required: false
        schema:
          description: Sort order, set only if sort key is set
          default: asc
          allOf:
          - $ref: '#/components/schemas/SortOrder'
        description: Sort order, set only if sort key is set
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedBaseResponse_GetCustomFieldsSettingsResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - Users:v1:Custom Fields
      summary: Create custom fields
      description: Create individual or multiple custom fields associated with the account under a specific category.
      operationId: create_custom_fields_users_v1_custom_fields_post
      security:
      - APIKeyHeader: []
      - OAuth2:
        - users.write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Body
              allOf:
              - $ref: '#/components/schemas/Body_create_custom_fields_users_v1_custom_fields_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse_GetCustomFieldsSettingsResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Users:v1:Custom Fields
      summary: Update custom fields
      description: Update custom fields settings by their unique ID
      operationId: update_custom_fields_users_v1_custom_fields_put
      security:
      - APIKeyHeader: []
      - OAuth2:
        - users.write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Body
              allOf:
              - $ref: '#/components/schemas/Body_update_custom_fields_users_v1_custom_fields_put'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse_GetCustomFieldsSettingsResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Users:v1:Custom Fields
      summary: Delete custom fields
      description: Delete individual or multiple custom fields associated with the account by their unique ID.
      operationId: delete_custom_fields_users_v1_custom_fields_delete
      security:
      - APIKeyHeader: []
      - OAuth2:
        - users.delete
      requestBody:
        required: true
        content:
          application/json:
            schema:
              title: Body
              allOf:
              - $ref: '#/components/schemas/Body_delete_custom_fields_users_v1_custom_fields_delete'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse_BulkDeleteCustomFieldResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Body_update_custom_fields_users_v1_custom_fields_put:
      properties:
        customFields:
          items:
            $ref: '#/components/schemas/CustomFieldBulkEditRequest'
          type: array
          maxItems: 100
          title: Customfields
          description: The custom fields.
      type: object
      required:
      - customFields
      title: Body_update_custom_fields_users_v1_custom_fields_put
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Body_create_custom_fields_users_v1_custom_fields_post:
      properties:
        customFields:
          items:
            anyOf:
            - $ref: '#/components/schemas/DropdownCustomFieldCreateRequest'
            - $ref: '#/components/schemas/CustomFieldCreateRequest'
          type: array
          maxItems: 100
          title: Customfields
          description: The custom fields.
      type: object
      required:
      - customFields
      title: Body_create_custom_fields_users_v1_custom_fields_post
    PaginatedBaseResponse_GetCustomFieldsSettingsResponse_:
      properties:
        requestId:
          type: string
          title: Requestid
        data:
          $ref: '#/components/schemas/GetCustomFieldsSettingsResponse'
        paging:
          $ref: '#/components/schemas/PagingResponseModel'
      type: object
      required:
      - data
      - paging
      title: PaginatedBaseResponse[GetCustomFieldsSettingsResponse]
    CustomFieldSettingsResponse:
      properties:
        id:
          type: integer
          title: Id
          description: The custom fields id
        name:
          type: string
          maxLength: 100
          title: Name
          description: The name of the custom field
        isRequired:
          type: boolean
          title: Isrequired
          description: Indicates whether the custom field is required
        categoryId:
          type: integer
          title: Categoryid
          description: The unique identifier of the custom field category
        isVisibleToAllAdmins:
          type: boolean
          title: Isvisibletoalladmins
          description: Indicates whether the custom field is visible to all admins
        viewAccessAdminIds:
          items:
            type: integer
            minimum: 1.0
          type: array
          title: Viewaccessadminids
          description: 'A list of unique identifiers of the admins who will be granted access to view this custom field, owners can always see all custom fields.

            Applicable only to custom fields that are not visible to all admins.'
        isEditableForAllAdmins:
          type: boolean
          title: Iseditableforalladmins
          description: Indicates whether the custom field is editable by all admins
        editAccessAdminIds:
          items:
            type: integer
            minimum: 1.0
          type: array
          title: Editaccessadminids
          description: 'A list of unique identifiers of the admins who will be granted access to edit this custom field, owners can always edit all custom fields.

            Applicable only to custom fields that are not editable by all admins.'
        isVisibleToUsers:
          type: boolean
          title: Isvisibletousers
          description: Indicates whether the custom field is visible to users
        isEditableForUsers:
          type: boolean
          title: Iseditableforusers
          description: 'Indicates whether the custom field is editable by users.

            Applicable only to custom fields that are visible to users.'
        type:
          allOf:
          - $ref: '#/components/schemas/UserCustomFields'
          description: 'The type of the custom field: Email, Date, Number, Text, Phone number, Dropdown, File.'
      type: object
      required:
      - name
      - isRequired
      - categoryId
      - isVisibleToAllAdmins
      - isEditableForAllAdmins
      - isVisibleToUsers
      - isEditableForUsers
      - id
      - type
      title: CustomFieldSettingsResponse
    APIResponse_BulkDeleteCustomFieldResponse_:
      properties:
        requestId:
          type: string
          title: Requestid
        data:
          $ref: '#/components/schemas/BulkDeleteCustomFieldResponse'
      type: object
      required:
      - data
      title: APIResponse[BulkDeleteCustomFieldResponse]
    CustomFieldCreateRequest:
      properties:
        name:
          type: string
          maxLength: 100
          title: Name
          description: The name of the custom field
        isRequired:
          type: boolean
          title: Isrequired
          description: Indicates whether the custom field is required
        categoryId:
          type: integer
          title: Categoryid
          description: The unique identifier of the custom field category
        isVisibleToAllAdmins:
          type: boolean
          title: Isvisibletoalladmins
          description: Indicates whether the custom field is visible to all admins
        viewAccessAdminIds:
          items:
            type: integer
            minimum: 1.0
          type: array
          title: Viewaccessadminids
          description: 'A list of unique identifiers of the admins who will be granted access to view this custom field, owners can always see all custom fields.

            Applicable only to custom fields that are not visible to all admins.'
        isEditableForAllAdmins:
          type: boolean
          title: Iseditableforalladmins
          description: Indicates whether the custom field is editable by all admins
        editAccessAdminIds:
          items:
            type: integer
            minimum: 1.0
          type: array
          title: Editaccessadminids
          description: 'A list of unique identifiers of the admins who will be granted access to edit this custom field, owners can always edit all custom fields.

            Applicable only to custom fields that are not editable by all admins.'
        isVisibleToUsers:
          type: boolean
          title: Isvisibletousers
          description: Indicates whether the custom field is visible to users
        isEditableForUsers:
          type: boolean
          title: Iseditableforusers
          description: 'Indicates whether the custom field is editable by users.

            Applicable only to custom fields that are visible to users.'
        type:
          type: string
          enum:
          - email
          - date
          - phone
          - number
          - str
          - file
          - directManager
          - birthday
          - link
          - location
          title: Type
          description: 'The type of the custom field: Email, Date, Number, Text, Phone number, File.'
      type: object
      required:
      - name
      - isRequired
      - categoryId
      - isVisibleToAllAdmins
      - isEditableForAllAdmins
      - isVisibleToUsers
      - isEditableForUsers
      - type
      title: CustomFieldCreateRequest
    APIResponse_GetCustomFieldsSettingsResponse_:
      properties:
        requestId:
          type: string
          title: Requestid
        data:
          $ref: '#/components/schemas/GetCustomFieldsSettingsResponse'
      type: object
      required:
      - data
      title: APIResponse[GetCustomFieldsSettingsResponse]
    PagingResponseModel:
      properties:
        offset:
          type: integer
          minimum: 0.0
          title: Offset
          description: The resource offset of the last successfully read resource will be returned as the paging.offset JSON property of a paginated response containing more results
        total:
          type: integer
          minimum: 0.0
          title: Total
          description: Total number of resources matching the request, ignoring pagination. Use this to retrieve the full count without paginating through every page. Only populated by endpoints that compute it.
      type: object
      required:
      - offset
      title: PagingResponseModel
    GetCustomFieldsSettingsResponse:
      properties:
        customFields:
          items:
            anyOf:
            - $ref: '#/components/schemas/DropdownCustomFieldSettingsResponse'
            - $ref: '#/components/schemas/CustomFieldSettingsResponse'
          type: array
          title: Customfields
          description: The custom fields.
      type: object
      required:
      - customFields
      title: GetCustomFieldsSettingsResponse
    CustomFieldsSortExternal:
      enum:
      - id
      - name
      - type
      title: CustomFieldsSortExternal
      description: An enumeration.
    BulkDeleteCustomFieldResponse:
      properties:
        customFieldIds:
          items:
            type: integer
          type: array
          title: Customfieldids
          description: The deleted custom fields ids
        success:
          type: boolean
          title: Success
          description: Whether the custom field were deleted successfully.
      type: object
      required:
      - customFieldIds
      - success
      title: BulkDeleteCustomFieldResponse
    DropdownCustomFieldOption:
      properties:
        id:
          type: integer
          title: Id
          description: The id of this option
        value:
          type: string
          title: Value
          description: The name of this option
        isDisabled:
          type: boolean
          title: Isdisabled
          description: Indicates if this option is disabled
          default: false
        isDeleted:
          type: boolean
          title: Isdeleted
          description: 'Indicates if this option is deleted

            (this will still be returned in case someone already chose this option so you can see the value).'
          default: false
      type: object
      required:
      - id
      - value
      title: DropdownCustomFieldOption
    Body_delete_custom_fields_users_v1_custom_fields_delete:
      properties:
        customFieldIds:
          items:
            type: integer
          type: array
          maxItems: 100
          title: Customfieldids
          description: The custom fields IDs to delete
      type: object
      required:
      - customFieldIds
      title: Body_delete_custom_fields_users_v1_custom_fields_delete
    UserCustomFields:
      type: string
      enum:
      - email
      - date
      - phone
      - number
      - str
      - dropdown
      - file
      - directManager
      - birthday
      - link
      - location
      title: UserCustomFields
    EditDropdownCustomFieldOption:
      properties:
        id:
          type: integer
          title: Id
          description: The id of this option
        value:
          type: string
          title: Value
          description: The name of this option
        isDisabled:
          type: boolean
          title: Isdisabled
          description: Indicates if this option is disabled
          default: false
        isDeleted:
          type: boolean
          title: Isdeleted
          description: 'Indicates if this option is deleted

            (this will still be returned in case someone already chose this option so you can see the value).'
          default: false
      type: object
      title: EditDropdownCustomFieldOption
    SortOrder:
      type: string
      enum:
      - asc
      - desc
      title: SortOrder
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreateDropdownCustomFieldOption:
      properties:
        value:
          type: string
          title: Value
          description: The value to be added as the option
        isDisabled:
          type: boolean
          title: Isdisabled
          description: Indicates if this option is disabled
          default: false
      type: object
      required:
      - value
      title: CreateDropdownCustomFieldOption
    DropdownCustomFieldSettingsResponse:
      properties:
        id:
          type: integer
          title: Id
          description: The custom fields id
        name:
          type: string
          maxLength: 100
          title: Name
          description: The name of the custom field
        isRequired:
          type: boolean
          title: Isrequired
          description: Indicates whether the custom field is required
        categoryId:
          type: integer
          title: Categoryid
          description: The unique identifier of the custom field category
        isVisibleToAllAdmins:
          type: boolean
          title: Isvisibletoalladmins
          description: Indicates whether the custom field is visible to all admins
        viewAccessAdminIds:
          items:
            type: integer
            minimum: 1.0
          type: array
          title: Viewaccessadminids
          description: 'A list of unique identifiers of the admins who will be granted access to view this custom field, owners can always see all custom fields.

            Applicable only to custom fields that are not visible to all admins.'
        isEditableForAllAdmins:
          type: boolean
          title: Iseditableforalladmins
          description: Indicates whether the custom field is editable by all admins
        editAccessAdminIds:
          items:
            type: integer
            minimum: 1.0
          type: array
          title: Editaccessadminids
          description: 'A list of unique identifiers of the admins who will be granted access to edit this custom field, owners can always edit all custom fields.

            Applicable only to custom fields that are not editable by all admins.'
        isVisibleToUsers:
          type: boolean
          title: Isvisibletousers
          description: Indicates whether the custom field is visible to users
        isEditableForUsers:
          type: boolean
          title: Iseditableforusers
          description: 'Indicates whether the custom field is editable by users.

            Applicable only to custom fields that are visible to users.'
        isMultiSelect:
          type: boolean
          title: Ismultiselect
          description: 'Indicates whether multiple selections are allowed in the dropdown.

            Applicable only to custom fields configured as dropdown types.'
        dropdownOptions:
          items:
            $ref: '#/components/schemas/DropdownCustomFieldOption'
          type: array
          title: Dropdownoptions
          description: 'The options available for selection in the dropdown field.

            Applicable only to custom fields configured as dropdown types.'
        type:
          type: string
          enum:
          - dropdown
          title: Type
          description: 'The type of the custom field: Email, Date, Number, Text, Phone number, Dropdown, File.'
          default: dropdown
      type: object
      required:
      - name
      - isRequired
      - categoryId
      - isVisibleToAllAdmins
      - isEditableForAllAdmins
      - isVisibleToUsers
      - isEditableForUsers
      - isMultiSelect
      - dropdownOptions
      - id
      title: DropdownCustomFieldSettingsResponse
    CustomFieldBulkEditRequest:
      properties:
        id:
          type: integer
          title: Id
          description: The custom fields id
        name:
          type: string
          maxLength: 100
          title: Name
          description: The name of the custom field
        isRequired:
          type: boolean
          title: Isrequired
          description: Indicates whether the custom field is required
        categoryId:
          type: integer
          title: Categoryid
          description: The unique identifier of the custom field category
        isVisibleToAllAdmins:
          type: boolean
          title: Isvisibletoalladmins
          description: Indicates whether the custom field is visible to all admins
        viewAccessAdminIds:
          items:
            type: integer
            minimum: 1.0
          type: array
          title: Viewaccessadminids
          description: 'A list of unique identifiers of the admins who will be granted access to view this custom field, owners can always see all custom fields.

            Applicable only to custom fields that are not visible to all admins.'
        isEditableForAllAdmins:
          type: boolean
          title: Iseditableforalladmins
          description: Indicates whether the custom field is editable by all admins
        editAccessAdminIds:
          items:
            type: integer
            minimum: 1.0
          type: array
          title: Editaccessadminids
          description: 'A list of unique identifiers of the admins who will be granted access to edit this custom field, owners can always edit all custom fields.

            Applicable only to custom fields that are not editable by all admins.'
        isVisibleToUsers:
          type: boolean
          title: Isvisibletousers
          description: Indicates whether the custom field is visible to users
        isEditableForUsers:
          type: boolean
          title: Iseditableforusers
          description: 'Indicates whether the custom field is editable by users.

            Applicable only to custom fields that are visible to users.'
        isMultiSelect:
          type: boolean
          title: Ismultiselect
          description: 'Indicates whether multiple selections are allowed in the dropdown.

            Applicable only to custom fields configured as dropdown types.'
        dropdownOptions:
          items:
            $ref: '#/components/schemas/EditDropdownCustomFieldOption'
          type: array
          title: Dropdownoptions
          description: 'The options available for selection in the dropdown field.

            Applicable only to custom fields configured as dropdown types.'
      type: object
      required:
      - id
      title: CustomFieldBulkEditRequest
    DropdownCustomFieldCreateRequest:
      properties:
        name:
          type: string
          maxLength: 100
          title: Name
          description: The name of the custom field
        isRequired:
          type: boolean
          title: Isrequired
          description: Indicates whether the custom field is required
        categoryId:
          type: integer
          title: Categoryid
          description: The unique identifier of the custom field category
        isVisibleToAllAdmins:
          type: boolean
          title: Isvisibletoalladmins
          description: Indicates whether the custom field is visible to all admins
        viewAccessAdminIds:
          items:
            type: integer
            minimum: 1.0
          type: array
          title: Viewaccessadminids
          description: 'A list of unique identifiers of the admins who will be granted access to view this custom field, owners can always see all custom fields.

            Applicable only to custom fields that are not visible to all admins.'
        isEditableForAllAdmins:
          type: boolean
          title: Iseditableforalladmins
          description: Indicates whether the custom field is editable by all admins
        editAccessAdminIds:
          items:
            type: integer
            minimum: 1.0
          type: array
          title: Editaccessadminids
          description: 'A list of unique identifiers of the admins who will be granted access to edit this custom field, owners can always edit all custom fields.

            Applicable only to custom fields that are not editable by all admins.'
        isVisibleToUsers:
          type: boolean
          title: Isvisibletousers
          description: Indicates whether the custom field is visible to users
        isEditableForUsers:
          type: boolean
          title: Iseditableforusers
          description: 'Indicates whether the custom field is editable by users.

            Applicable only to custom fields that are visible to users.'
        isMultiSelect:
          type: boolean
          title: Ismultiselect
          description: 'Indicates whether multiple selections are allowed in the dropdown.

            Applicable only to custom fields configured as dropdown types.'
        dropdownOptions:
          items:
            $ref: '#/components/schemas/CreateDropdownCustomFieldOption'
          type: array
          title: Dropdownoptions
          description: 'The options available for selection in the dropdown field.

            Applicable only to custom fields configured as dropdown types.'
        type:
          type: string
          enum:
          - dropdown
          title: Type
          description: 'The type of the custom field: Dropdown'
          default: dropdown
      type: object
      required:
      - name
      - isRequired
      - categoryId
      - isVisibleToAllAdmins
      - isEditableForAllAdmins
      - isVisibleToUsers
      - isEditableForUsers
      - isMultiSelect
      title: DropdownCustomFieldCreateRequest
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: The Api key of the company given by Connecteam
      in: header
      name: X-API-KEY
    OAuth2:
      type: oauth2
      description: OAuth2 Bearer token
      flows:
        clientCredentials:
          scopes:
            account_information.read: account information - read
            account_information.write: account information - write
            account_information.delete: account information - delete
            company_policies.read: company policies - read
            company_policies.write: company policies - write
            company_policies.delete: company policies - delete
            company_insights.read: company insights - read
            users.read: users - read
            users.write: users - write
            users.delete: users - delete
            assets.read: assets - read
            assets.write: assets - write
            assets.delete: assets - delete
            sales_data.read: sales data - read
            sales_data.write: sales data - write
            sales_data.delete: sales data - delete
            attachments.read: attachments - read
            attachments.write: attachments - write
            attachments.delete: attachments - delete
            quick_tasks.read: quick tasks - read
            quick_tasks.write: quick tasks - write
            quick_tasks.delete: quick tasks - delete
            publishers.read: publishers - read
            publishers.write: publishers - write
            publishers.delete: publishers - delete
            chat.read: chat - read
            chat.write: chat - write
            chat.delete: chat - delete
            jobs.read: jobs - read
            jobs.write: jobs - write
            jobs.delete: jobs - delete
            schedule.read: schedule - read
            schedule.write: schedule - write
            schedule.delete: schedule - delete
            daily_note.read: daily note - read
            daily_note.write: daily note - write
            daily_note.delete: daily note - delete
            time_clock.read: time clock - read
            time_clock.write: time clock - write
            time_clock.delete: time clock - delete
            nfc.read: nfc - read
            nfc.write: nfc - write
            nfc.delete: nfc - delete
            time_off.read: time off - read
            time_off.write: time off - write
            time_off.delete: time off - delete
            pay_rates.read: pay rates - read
            pay_rates.write: pay rates - write
            pay_rates.delete: pay rates - delete
            forms.read: forms - read
            forms.write: forms - write
            forms.delete: forms - delete
            onboarding.read: onboarding - read
            onboarding.write: onboarding - write
            onboarding.delete: onboarding - delete
            settings.read: settings - read
            settings.write: settings - write
            settings.delete: settings - delete
            company_checklist.read: company checklist - read
            company_checklist.write: company checklist - write
            recognitions.read: recognitions - read
            celebrations.read: celebrations - read
          tokenUrl: /oauth/v1/token
    HTTPBasic:
      type: http
      description: Use client_id as Username and client_secret as Password
      scheme: basic