Reonic Users API

openapi: 3.2.0
info:
  title: Reonic REST Api v3 Users API
  description: The Reonic REST API v3 provides programmatic access to create and manage resources.
  version: 3.2.0
  contact:
    email: kontakt@reonic.de
    url: https://reonic.com
    name: Reonic GmbH
servers:
- url: '{apiBaseUrl}/rest/v3/'
security:
- X-Authorization: []
tags:
- name: Users
  description: Members of your workspace, such as employees. Not to be confused with **Contacts**, which represent external people like customers or leads.
paths:
  /users:
    get:
      summary: List users
      description: 'List all users.


        **Allowed API keys:** Read-only, Read and Write'
      tags:
      - Users
      parameters:
      - schema:
          type: string
          enum:
          - exclude
          - include
          - only
          default: exclude
          description: 'Controls whether archived users appear in results. Default: exclude.'
        required: false
        description: 'Controls whether archived users appear in results. Default: exclude.'
        name: archived
        in: query
      - schema:
          type: string
          enum:
          - exclude
          - include
          - only
          default: exclude
          description: 'Controls whether deleted users appear in results. Default: exclude.'
        required: false
        description: 'Controls whether deleted users appear in results. Default: exclude.'
        name: deleted
        in: query
      - schema:
          type: string
          example: no-cache
        required: false
        name: Reonic-Cache-Control
        in: header
        description: Set to 'no-cache' to bypass the 1-hour response cache and force a fresh read. The fresh response is then written back to the cache for subsequent callers. Forced refreshes count against the uncached rate-limit bucket (30/min); only cache hits count against the cached bucket (500/min).
      responses:
        '200':
          description: List of all users
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                    description: List of items
                required:
                - data
      operationId: getUsers
      x-operation-id-source: derived
  /users/{userId}:
    get:
      summary: Get user
      description: 'Get a single user by their ID.


        **Allowed API keys:** Read-only, Read and Write'
      tags:
      - Users
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: userId
        in: path
      - schema:
          type: string
          example: no-cache
        required: false
        name: Reonic-Cache-Control
        in: header
        description: Set to 'no-cache' to bypass the 1-hour response cache and force a fresh read. The fresh response is then written back to the cache for subsequent callers. Forced refreshes count against the uncached rate-limit bucket (30/min); only cache hits count against the cached bucket (500/min).
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      operationId: getUsersByUserId
      x-operation-id-source: derived
  /users/create:
    post:
      summary: Create user
      description: 'Create a new user. A user who already exists in another organization is added to yours; if the email already belongs to a member of your organization, the request is rejected.


        **Allowed API keys:** Read and Write'
      tags:
      - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
      responses:
        '201':
          description: The created user
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/User'
                required:
                - data
      operationId: postUsersCreate
      x-operation-id-source: derived
  /users/{userId}/update:
    post:
      summary: Update user
      description: 'Update a user''s access level, external status, or archived state.


        **Allowed API keys:** Read and Write'
      tags:
      - Users
      parameters:
      - schema:
          type: string
          format: uuid
        required: true
        name: userId
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: The updated user
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/User'
                required:
                - data
        '400':
          description: The requested change is not allowed for this user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                - message
      operationId: postUsersByUserIdUpdate
      x-operation-id-source: derived
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
        fullName:
          type: string
          description: First and last name combined
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        phone:
          type: string
        role:
          type: string
          enum:
          - Admin
          - Editor
          - Viewer
        isExternal:
          type: boolean
        imageUrl:
          type:
          - string
          - 'null'
          format: uri
        archivedAt:
          type:
          - string
          - 'null'
          format: date-time
        deletedAt:
          type:
          - string
          - 'null'
          format: date-time
          deprecated: true
          description: Deprecated. This field is always null.
      required:
      - id
      - fullName
      - firstName
      - lastName
      - email
      - phone
      - role
      - isExternal
      - imageUrl
      - archivedAt
      - deletedAt
    UserCreate:
      type: object
      properties:
        firstName:
          type: string
          minLength: 1
          maxLength: 200
        lastName:
          type: string
          minLength: 1
          maxLength: 200
        email:
          type: string
          maxLength: 300
          format: email
          description: Email address of the user. Used as the unique login identifier.
        phone:
          type: string
          pattern: ^\+[1-9]\d{1,14}$
          description: Phone number of the user in E.164 format.
          example: '+491511234567'
        role:
          type: string
          enum:
          - Admin
          - Editor
          - Viewer
          description: Access level granted to the user.
        isExternal:
          type: boolean
          default: false
          description: Whether the user is external to the organization. Must be false for users with the Admin role. Defaults to false.
        sendWelcomeEmail:
          type: boolean
          default: true
          description: Whether to email the user a welcome message inviting them to the platform. Defaults to true.
      required:
      - firstName
      - lastName
      - email
      - role
      additionalProperties: false
    UserUpdate:
      type: object
      properties:
        role:
          type: string
          enum:
          - Admin
          - Editor
          - Viewer
          description: Access level to grant the user.
        isExternal:
          type: boolean
          description: Whether the user is external to the organization. Cannot be enabled for users with the Admin role.
        archived:
          type: boolean
          description: '`true` to archive the user, `false` to unarchive.'
      additionalProperties: false
  securitySchemes:
    X-Authorization:
      type: apiKey
      in: header
      name: X-Authorization
x-tagGroups:
- name: People
  tags:
  - Contacts
  - Users
  - Teams
- name: Projects
  tags:
  - Residential Projects
  - Commercial Projects
- name: Working on a project
  tags:
  - Notes
  - Tasks
  - Files
  - File Folders
  - Activities
  - Time Tracking
  - Checklists
  - Checklist Templates
  - Signature Requests
- name: Calendar
  tags:
  - Calendars
  - Calendar Categories
  - Appointments
- name: Catalog
  tags:
  - Components
  - Planning Templates
  - Planning Packages
  - Offer Templates
- name: Workspace setup
  tags:
  - Kanban Boards
  - Kanban Columns
  - Tags
  - Lead Sources
- name: Wiki
  tags:
  - Wiki
- name: Services
  tags:
  - Photogrammetry
- name: API helpers
  tags:
  - Upload
  - Links
- name: Integrations
  tags:
  - Webhooks
- name: Guides
  tags:
  - Migrating from API v2 to v3
  - Changelog