openapi: 3.2.0
info:
  title: Moveworks Users API
  version: 1.0.0
  description: 'Operations tagged Users across 3 of this provider''s published API definitions: moveworks-content-gateway-openapi.yaml, moveworks-data-api-openapi.yaml, moveworks-identity-gateway-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://content-gateway-example.com/v1
  description: https://content-gateway-example.com/v1
- url: https://api.moveworks.ai/export/v1/records
  description: US PROD server. If you are located in the US region please use this server URL
- url: https://api.am-eu-central.moveworks.ai/export/v1/records
  description: EU PROD server. If you are located in the EU region please use this server URL
- url: https://api.am-ca-central.moveworks.ai/export/v1/records
  description: CA PROD server. If you are located in the CA region please use this server URL
- url: https://api.moveworksgov.ai/export/v1/records
  description: Govcloud PROD server. If you are on GovCloud infrastrucutre (US region) please use this server URL
- url: https://api.jp.moveworks.com/export/v1/records
  description: Japan production server
- url: https://api.uk.moveworks.com/export/v1/records
  description: UK production server
- url: https://api.prod4.us.moveworks.com/export/v1/records
  description: US Prod 4 production server
- url: https://api.prod3.us.moveworks.com/export/v1/records
  description: US Prod 3 production server
- url: http://localhost:5000/myinstance1
  description: http://localhost:5000/myinstance1
tags:
- name: Users
paths:
  /users:
    get:
      operationId: list-users
      summary: List users
      description: Retrieve a paginated list of users using OData parameters.
      tags:
      - Users
      parameters:
      - name: $top
        in: query
        description: Number of items to return per page (default pagination)
        required: false
        schema:
          type: integer
      - name: $skip
        in: query
        description: Number of items to skip (default pagination offset)
        required: false
        schema:
          type: integer
      - name: $skiptoken
        in: query
        description: Used when the query parameters can be memoized into an encoded string containing filtering and pagination parameters. If the endpoint supports memoized paging, the first call can use $top and $skip, while @odata.nextLink will return with $skiptoken. If memoized querying is not supported, $top and $skip should be sufficient.
        required: false
        schema:
          type: string
      - name: $filter
        in: query
        required: false
        schema:
          type: string
      - name: $select
        in: query
        required: false
        schema:
          type: string
      - name: $orderby
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: User list response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCollection'
        '400':
          description: Bad Request - The request was invalid or cannot be served.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - The request requires user authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - The server understood the request but refuses to authorize it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - The requested resource could not be found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests - Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - The server encountered an unexpected condition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable - The server is currently unable to handle the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://content-gateway-example.com/v1
      description: https://content-gateway-example.com/v1
  /users/{userId}:
    get:
      operationId: get-user-by-id
      summary: Get User By ID
      description: Returns user details given their userId. We recommend a rate limit of 5 req/sec for this endpoint.
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        description: ID of user to fetch details for
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A single user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User_2'
    servers:
    - url: http://localhost:5000/myinstance1
      description: http://localhost:5000/myinstance1
components:
  schemas:
    UserMetadata:
      type: object
      properties: {}
      description: Custom key-value metadata for the user.
      title: UserMetadata
    User:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the user.
        primary_email_addr:
          type: string
          description: Primary email address of the user.
        full_name:
          type: string
          description: Full name of the user.
        state:
          type: string
          description: 'State of the user account. Enum: Active | Inactive'
        last_modified_datetime:
          type: string
          description: Last modification timestamp (ISO 8601).
        metadata:
          $ref: '#/components/schemas/UserMetadata'
          description: Custom key-value metadata for the user.
      title: User
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ErrorResponseError'
      required:
      - error
      title: ErrorResponse
    ErrorResponseError:
      type: object
      properties:
        code:
          type: string
          description: Standard error code (e.g., UNAUTHORIZED, INVALID_ARGUMENT, NOT_FOUND).
        message:
          type: string
          description: Human-readable explanation of the error.
      required:
      - code
      - message
      title: ErrorResponseError
    UserCollection:
      type: object
      properties:
        '@odata.context':
          type: string
        value:
          type: array
          items:
            $ref: '#/components/schemas/User'
        '@odata.nextLink':
          type: string
      title: UserCollection
    UserobjectExternalIdsItems:
      type: object
      properties:
        connector_name:
          type: string
          description: Name of the connector created in Moveworks Setup
        external_id:
          type: string
          format: uuid
          description: External ID from the source system
        source:
          type: string
          description: Identifier for the source system.
      title: UserobjectExternalIdsItems
    users:
      type: object
      properties:
        '@odata.context':
          type: string
          description: URL to the metadata of the response.
        '@odata.nextLink':
          type: string
          description: URL to fetch the next set of results.
        value:
          type: array
          items:
            $ref: '#/components/schemas/userobject'
      title: users
    429ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      title: 429ErrorResponse
    500ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      title: 500ErrorResponse
    404ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      title: 404ErrorResponse
    403ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      title: 403ErrorResponse
    400ErrorResponse:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      title: 400ErrorResponse
    userobject:
      type: object
      properties:
        id:
          type: string
          description: User record id generated and stored in Moveworks for the end user
        email_addr:
          type: string
          description: Email of the end user stored in Moveworks. This field is ingested from your systems and reflect the value present in your systems.
        access_to_bot:
          type: boolean
          description: Denotes if the end user has access to Moveworks Assistant or not. This is evaluated through the bot access rule configured in Moveworks Setup.
        first_name:
          type: string
          description: First name of the end user. This field is ingested from your systems and reflect the value present in your systems.
        last_name:
          type: string
          description: Last name of the end user.This field is ingested from your systems and reflect the value present in your systems.
        user_preferred_language:
          type: string
          description: User preferred language set from the end user. EN-US is the default value for this field
        first_interaction_time:
          type: string
          format: date-time
          description: Time stamp for the first interaction for the end user.
        latest_interaction_time:
          type: string
          format: date-time
          description: Time stamp for the latest interaction of the end user.
        external_ids:
          type: array
          items:
            $ref: '#/components/schemas/UserobjectExternalIdsItems'
        last_updated_time:
          type: string
          format: date-time
          description: Last updated time for the user entry.
      title: userobject
    UserUserState:
      type: string
      enum:
      - ACTIVE
      - INACTIVE
      description: Specifies the state of the user
      title: UserUserState
    listUsers_Response_200:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/User_2'
        next_page_token:
          type: string
          description: The value provided serves as the starting point for fetching the next page of records. In the next call, use this value as the pageToken parameter.
      required:
      - results
      title: listUsers_Response_200
    UserUserEmploymentInfoEmploymentLocation:
      type: object
      properties:
        location:
          type: string
          description: Specifies the location of the office
        office:
          type: string
          description: Denotes the name of the office
        country_code:
          type: string
          description: Specifies the country code of the employee in E.164 format
        region:
          type: string
          description: The geographical region to which the office is assigned
        timezone:
          type: string
          description: Indicates the time zone in which the office is located
      title: UserUserEmploymentInfoEmploymentLocation
    User_2:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserUser'
        system_identity:
          $ref: '#/components/schemas/UserSystemIdentity'
        last_updated_at:
          type: string
          format: timestamp
          description: Represents the timestamp indicating the most recent modification or update made to the user's information (in ISO-8601 UTC)
      required:
      - user
      - system_identity
      - last_updated_at
      title: User
    UserUserEmploymentInfo:
      type: object
      properties:
        employee_start_date_ts:
          type: string
          format: timestamp
          description: Joining date of the employee in in ISO-8601 UTC.
        role:
          type: string
          description: Role of the user in the organisation
        manager_email:
          type: string
          format: email
          description: Email address of the manager of the user
        cost_center_id:
          type: string
          description: Cost center id for the user
        cost_center_name:
          type: string
          description: Cost center name for the user
        department:
          type: string
          description: Specifies the department the user belongs to
        office_phone_number:
          type: string
          description: Specifies the office phone number of the user
        assistant_full_name:
          type: string
          description: Assistant's full name of the user
        employment_location:
          $ref: '#/components/schemas/UserUserEmploymentInfoEmploymentLocation'
      title: UserUserEmploymentInfo
    UserUser:
      type: object
      properties:
        state:
          $ref: '#/components/schemas/UserUserState'
          description: Specifies the state of the user
        universal_identifier:
          type: string
          description: Unique identifier of the user. This field should always be populated. It will be used to uniquely identify a user across different systems.
        email_addr:
          type: string
          format: email
          description: Email address of the user
        first_name:
          type: string
          description: First name of the user
        last_name:
          type: string
          description: Last name of the user
        full_name:
          type: string
          description: Full name of the user
        work_status:
          $ref: '#/components/schemas/UserUserWorkStatus'
          description: Employement type of the user
        employment_info:
          $ref: '#/components/schemas/UserUserEmploymentInfo'
      required:
      - state
      - universal_identifier
      title: UserUser
    UserUserWorkStatus:
      type: string
      enum:
      - UNKNOWN_WORK_STATUS
      - CONTINGENT
      - INTERN
      - FULL_TIME
      description: Employement type of the user
      title: UserUserWorkStatus
    UserSystemIdentity:
      type: object
      properties:
        id:
          type: string
          description: Refers to the unique identifier assigned to the user in the identity gateway. This is usually primary key of the external system
        username:
          type: string
          description: Refers to the username of the user in the identity system. This is usually lookup key of the external system
      required:
      - id
      title: UserSystemIdentity
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
    OAuth2:
      type: http
      scheme: bearer
    bearerAuth:
      type: http
      scheme: bearer
x-refined-from:
- moveworks-content-gateway-openapi.yaml
- moveworks-data-api-openapi.yaml
- moveworks-identity-gateway-openapi.yaml