ControlUp Invitations API

openapi: 3.2.0
info:
  title: Dex Invitations API
  version: 1.0.0
  description: Dex API Description
  contact: {}
servers:
- url: https://api.controlup.com/v1
tags:
- name: Invitations
paths:
  /organizations/{orgId}/invitations:
    post:
      operationId: OrgInvitationPublicController_create
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse_InvitationResults_'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody_ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes__'
        '401':
          description: 'Unauthorized: Access is denied'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized__'
        '403':
          description: 'Forbidden: Access to this resource is denied'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden__'
        '404':
          description: 'Not Found: The requested resource could not be found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound__'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError__'
      description: 'Invites users to your organization with the specified roles.

        You can invite multiple users with a single request by sending multiple objects in the request body.'
      summary: Invite users
      tags:
      - Invitations
      security:
      - apiKey: []
      parameters:
      - description: ID of your ControlUp organization. You can find your organization ID on the [API Key Management page](how-to-make-api-requests#how-to-find-your-controlup-organization-id) in the DEX platform.
        in: path
        name: orgId
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      requestBody:
        description: Add an object for each user you want to invite.
        required: true
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/InviteUserPublic'
              type: array
              description: Add an object for each user you want to invite.
    patch:
      operationId: OrgInvitationPublicController_update
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse_InvitationResults_'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody_ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes__'
        '401':
          description: 'Unauthorized: Access is denied'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized__'
        '403':
          description: 'Forbidden: Access to this resource is denied'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden__'
        '404':
          description: 'Not Found: The requested resource could not be found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound__'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseBody_ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError__'
      description: Resends an invitation email to a previously invited email address.
      summary: Resend invitation
      tags:
      - Invitations
      security:
      - apiKey: []
      parameters:
      - description: ID of your ControlUp organization. You can find your organization ID on the [API Key Management page](how-to-make-api-requests#how-to-find-your-controlup-organization-id) in the DEX platform.
        in: path
        name: orgId
        required: true
        schema:
          $ref: '#/components/schemas/UUID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReinviteUser'
components:
  schemas:
    ? ErrorResponseBody_ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError__
    : properties:
        metadata:
          $ref: '#/components/schemas/ErrorResponseMetadata'
        error:
          $ref: '#/components/schemas/ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError_'
      required:
      - error
      - metadata
      type: object
    ErrorCode.NotFound:
      enum:
      - 5
      type: number
    HttpStatusCode.INTERNAL_SERVER_ERROR:
      enum:
      - 500
      type: number
    ErrorMessage.Unauthorized:
      enum:
      - Unauthorized
      type: string
    ReinviteUser:
      properties:
        email:
          $ref: '#/components/schemas/Email'
          description: The user’s email address.
      required:
      - email
      type: object
    ErrorCode.Unauthorized:
      enum:
      - 3
      type: number
    BadRequestErrorMessages:
      enum:
      - Bad Request
      - Invalid Params
      - Unique Field Violation
      type: string
    PositiveInteger:
      type: integer
      format: int32
      minimum: 1
    ErrorResponseBody_ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized__:
      properties:
        metadata:
          $ref: '#/components/schemas/ErrorResponseMetadata'
        error:
          $ref: '#/components/schemas/ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized_'
      required:
      - error
      - metadata
      type: object
    ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden_:
      properties:
        message:
          $ref: '#/components/schemas/ErrorMessage.Forbidden'
        code:
          $ref: '#/components/schemas/ErrorCode.Forbidden'
        status:
          $ref: '#/components/schemas/HttpStatusCode.FORBIDDEN'
        data:
          additionalProperties: true
          type: object
      required:
      - status
      - code
      - message
      type: object
    HttpStatusCode.UNAUTHORIZED:
      enum:
      - 401
      type: number
    BadRequestErrorCodes:
      enum:
      - 2
      - 14
      - 50
      type: number
    APIResponse_InvitationResults_:
      properties:
        data:
          allOf:
          - $ref: '#/components/schemas/InvitationResults'
      required:
      - data
      type: object
    ErrorResponseMetadata:
      properties:
        cuRequestId:
          type: string
        orgId:
          type: string
        userId:
          type: string
        userIp:
          type: string
      required:
      - userIp
      - userId
      - orgId
      - cuRequestId
      type: object
    ErrorMessage.InternalServerError:
      enum:
      - Internal Server Error
      type: string
    ErrorMessage.Forbidden:
      enum:
      - Forbidden
      type: string
    NonEmptyArray_PositiveInteger_:
      items:
        $ref: '#/components/schemas/PositiveInteger'
      type: array
      minItems: 1
    ErrorMessage.NotFound:
      enum:
      - Not Found
      type: string
    ErrorCode.InternalServerError:
      enum:
      - 6
      type: number
    ErrorType_ErrorMessage.Unauthorized.HttpStatusCode.UNAUTHORIZED.ErrorCode.Unauthorized_:
      properties:
        message:
          $ref: '#/components/schemas/ErrorMessage.Unauthorized'
        code:
          $ref: '#/components/schemas/ErrorCode.Unauthorized'
        status:
          $ref: '#/components/schemas/HttpStatusCode.UNAUTHORIZED'
        data:
          additionalProperties: true
          type: object
      required:
      - status
      - code
      - message
      type: object
    HttpStatusCode.FORBIDDEN:
      enum:
      - 403
      type: number
    ErrorCode.Forbidden:
      enum:
      - 4
      type: number
    InviteUserPublic:
      properties:
        email:
          $ref: '#/components/schemas/Email'
          description: The user’s email address.
        roles:
          $ref: '#/components/schemas/NonEmptyArray_PositiveInteger_'
          description: 'An array of role IDs (integers) to assign to the user.

            You can use [GET /roles](orgrolespubliccontroller_getall) to see the ID of each role.


            Default role IDs:

            * Admin - 1

            * Editor - 2

            * Viewer - 3

            * No Permissions - 4

            * VDI and DaaS Admins - 5

            * Access Real-Time DX Console - 6'
      required:
      - roles
      - email
      type: object
    ErrorResponseBody_ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound__:
      properties:
        metadata:
          $ref: '#/components/schemas/ErrorResponseMetadata'
        error:
          $ref: '#/components/schemas/ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound_'
      required:
      - error
      - metadata
      type: object
    HttpStatusCode.BAD_REQUEST:
      enum:
      - 400
      type: number
    Email:
      type: string
      format: email
      description: Valid email address.
      pattern: ^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$
    ErrorResponseBody_ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes__:
      properties:
        metadata:
          $ref: '#/components/schemas/ErrorResponseMetadata'
        error:
          $ref: '#/components/schemas/ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes_'
      required:
      - error
      - metadata
      type: object
    ErrorType_ErrorMessage.NotFound.HttpStatusCode.NOT_FOUND.ErrorCode.NotFound_:
      properties:
        message:
          $ref: '#/components/schemas/ErrorMessage.NotFound'
        code:
          $ref: '#/components/schemas/ErrorCode.NotFound'
        status:
          $ref: '#/components/schemas/HttpStatusCode.NOT_FOUND'
        data:
          additionalProperties: true
          type: object
      required:
      - status
      - code
      - message
      type: object
    ErrorType_ErrorMessage.InternalServerError.HttpStatusCode.INTERNAL_SERVER_ERROR.ErrorCode.InternalServerError_:
      properties:
        message:
          $ref: '#/components/schemas/ErrorMessage.InternalServerError'
        code:
          $ref: '#/components/schemas/ErrorCode.InternalServerError'
        status:
          $ref: '#/components/schemas/HttpStatusCode.INTERNAL_SERVER_ERROR'
        data:
          additionalProperties: true
          type: object
      required:
      - status
      - code
      - message
      type: object
    InvitationResults:
      properties:
        invitedUsers:
          items:
            type: string
          type: array
          description: A list of email addresses of users who were successfully invited.
        uninvitedUsers:
          items:
            properties:
              errorCode:
                type: number
                format: double
                description: The specific error code for the invitation failure.
              reason:
                type: string
                description: The reason the user was not successfully invited.
              email:
                type: string
                description: The user’s email address.
            required:
            - reason
            - email
            type: object
          type: array
          description: A list of email addresses of users who were not invited.
      type: object
      example:
        invitedUsers:
        - test1@controlup.com
        - test2@controlup.com
        uninvitedUsers:
        - email: test3@controlup.com
          reason: 'user cannot be invited - user is competitors'' domain - email: test3@controlup.com'
        - email: test4@controlup.com
          reason: user cannot be invited - user already related to org
    HttpStatusCode.NOT_FOUND:
      enum:
      - 404
      type: number
    ErrorType_BadRequestErrorMessages.HttpStatusCode.BAD_REQUEST.BadRequestErrorCodes_:
      properties:
        message:
          $ref: '#/components/schemas/BadRequestErrorMessages'
        code:
          $ref: '#/components/schemas/BadRequestErrorCodes'
        status:
          $ref: '#/components/schemas/HttpStatusCode.BAD_REQUEST'
        data:
          additionalProperties: true
          type: object
      required:
      - status
      - code
      - message
      type: object
    ErrorResponseBody_ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden__:
      properties:
        metadata:
          $ref: '#/components/schemas/ErrorResponseMetadata'
        error:
          $ref: '#/components/schemas/ErrorType_ErrorMessage.Forbidden.HttpStatusCode.FORBIDDEN.ErrorCode.Forbidden_'
      required:
      - error
      - metadata
      type: object
    UUID:
      type: string
      format: uuid
      description: 'Stringified UUIDv4.

        See [RFC 4112](https://tools.ietf.org/html/rfc4122)'
      pattern: ^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-4[0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}$
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
x-readme:
  explorer-enabled: true
  proxy-enabled: false
  samples-languages:
  - shell
  - powershell
  - node
  - javascript
  - python
  - c
  - clojure
  - cplusplus
  - csharp
  - http
  - go
  - java
  - json
  - kotlin
  - objectivec
  - ocaml
  - php
  - r
  - ruby
  - shell
  - swift