namespace team import async import users import common import team_common union_closed AdminTier "Describes which team-related admin permissions a user has." team_admin "User is an administrator of the team - has all permissions." user_management_admin "User can do most user provisioning, de-provisioning and management." support_admin "User can do a limited set of common support tasks for existing users." member_only "User is not an admin of the team." example default member_only = null # # Common structs # struct TeamMemberProfile extends MemberProfile "Profile of a user as a member of a team." groups List(team_common.GroupId) "List of group IDs of groups that the user belongs to." example default team_member_id = "dbmid:FDFSVF-DFSDF" account_id = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc" external_id = "244423" email = "tami@seagull.com" email_verified = false status = active name = default groups = ["g:e2db7665347abcd600000000001a2b3c"] membership_type = full joined_on = "2015-05-12T15:50:38Z" union_closed MemberSelectorError extends UserSelectorError user_not_in_team "The user is not a member of the team." ######################## # Member info routes ######################## # # Route: members/list # struct MembersListArg limit UInt32(min_value=1, max_value=1000) = 1000 "Number of results to return per call." include_removed Boolean = false "Whether to return removed members." example default limit = 100 include_removed = false struct TeamMemberInfo "Information about a team member." profile TeamMemberProfile "Profile of a user as a member of a team." role AdminTier "The user's role in the team." example default profile = default role = member_only struct MembersListResult members List(TeamMemberInfo) "List of team members." cursor String "Pass the cursor into :route:`members/list/continue` to obtain the additional members." has_more Boolean "Is true if there are additional team members that have not been returned yet. An additional call to :route:`members/list/continue` can retrieve them." example default members = [default] cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu" has_more = true union MembersListError "" route members/list(MembersListArg, MembersListResult, MembersListError) "Lists members of a team. Permission : Team information" attrs auth = "team" owner = "adminx" # # Route: members/list/continue # struct MembersListContinueArg cursor String "Indicates from what point to get the next set of members." example default cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu" union MembersListContinueError invalid_cursor "The cursor is invalid." route members/list/continue(MembersListContinueArg, MembersListResult, MembersListContinueError) "Once a cursor has been retrieved from :route:`members/list`, use this to paginate through all team members. Permission : Team information" attrs auth = "team" owner = "adminx" # # Route: members/get_info # struct MembersGetInfoArgs members List(UserSelectorArg) "List of team members." example default members = [default] union_closed MembersGetInfoItem "Describes a result obtained for a single user whose id was specified in the parameter of :route:`members/get_info`." id_not_found String "An ID that was provided as a parameter to :route:`members/get_info`, and did not match a corresponding user. This might be a team_member_id, an email, or an external ID, depending on how the method was called." member_info TeamMemberInfo "Info about a team member." example default member_info = default # Information returned by :route:`members/get_info`. # describing multiple team members." alias MembersGetInfoResult = List(MembersGetInfoItem) union MembersGetInfoError "" route members/get_info(MembersGetInfoArgs, MembersGetInfoResult, MembersGetInfoError) "Returns information about multiple team members. Permission : Team information This endpoint will return :field:`MembersGetInfoItem.id_not_found`, for IDs (or emails) that cannot be matched to a valid team member." attrs auth = "team" owner = "adminx" ########################## # Member management routes ########################## # # Route members/add # struct MemberAddArg member_email common.EmailAddress member_given_name common.NamePart? "Member's first name." member_surname common.NamePart? "Member's last name." member_external_id team_common.MemberExternalId? "External ID for member." member_persistent_id String? "Persistent ID for member. This field is only available to teams using persistent ID SAML configuration." send_welcome_email Boolean = true "Whether to send a welcome email to the member. If send_welcome_email is false, no email invitation will be sent to the user. This may be useful for apps using single sign-on (SSO) flows for onboarding that want to handle announcements themselves." role AdminTier = member_only example default member_email = "tom.s@company.com" member_given_name = "Tom" member_surname = "Silverstone" member_external_id = "company_id:342432" role = default struct MembersAddArg new_members List(MemberAddArg) "Details of new members to be added to the team." force_async Boolean = false "Whether to force the add to happen asynchronously." example default new_members = [default] union_closed MemberAddResult "Describes the result of attempting to add a single user to the team. 'success' is the only value indicating that a user was indeed added to the team - the other values explain the type of failure that occurred, and include the email of the user for which the operation has failed." success TeamMemberInfo "Describes a user that was successfully added to the team." team_license_limit common.EmailAddress "Team is already full. The organization has no available licenses." free_team_member_limit_reached common.EmailAddress "Team is already full. The free team member limit has been reached." user_already_on_team common.EmailAddress "User is already on this team. The provided email address is associated with a user who is already a member of (including in recoverable state) or invited to the team." user_on_another_team common.EmailAddress "User is already on another team. The provided email address is associated with a user that is already a member or invited to another team." user_already_paired common.EmailAddress "User is already paired." user_migration_failed common.EmailAddress "User migration has failed." duplicate_external_member_id common.EmailAddress "A user with the given external member ID already exists on the team (including in recoverable state)." duplicate_member_persistent_id common.EmailAddress "A user with the given persistent ID already exists on the team (including in recoverable state)." persistent_id_disabled common.EmailAddress "Persistent ID is only available to teams with persistent ID SAML configuration. Please contact Dropbox for more information." user_creation_failed common.EmailAddress "User creation has failed." example default success = default union_closed MembersAddLaunch extends async.LaunchResultBase complete List(MemberAddResult) example default complete = [default] route members/add(MembersAddArg, MembersAddLaunch, Void) "Adds members to a team. Permission : Team member management A maximum of 20 members can be specified in a single call. If no Dropbox account exists with the email address specified, a new Dropbox account will be created with the given email address, and that account will be invited to the team. If a personal Dropbox account exists with the email address specified in the call, this call will create a placeholder Dropbox account for the user on the team and send an email inviting the user to migrate their existing personal account onto the team. Team member management apps are required to set an initial given_name and surname for a user to use in the team invitation and for 'Perform as team member' actions taken on the user before they become 'active'." attrs auth = "team" owner = "adminx" # # Route members/add/job_status/get # union_closed MembersAddJobStatus extends async.PollResultBase complete List(MemberAddResult) "The asynchronous job has finished. For each member that was specified in the parameter :type:`MembersAddArg` that was provided to :route:`members/add`, a corresponding item is returned in this list. " failed String "The asynchronous job returned an error. The string contains an error message." example default complete = [default] route members/add/job_status/get(async.PollArg, MembersAddJobStatus, async.PollError) "Once an async_job_id is returned from :route:`members/add` , use this to poll the status of the asynchronous request. Permission : Team member management" attrs auth = "team" owner = "adminx" # # Route members/set_profile # # Note that we do not allow changing 'familiar_name' and 'display_name from users.Name, since they # are derived from the given_name, surname and locale. struct MembersSetProfileArg "Exactly one of team_member_id, email, or external_id must be provided to identify the user account. At least one of new_email, new_external_id, new_given_name, and/or new_surname must be provided." user UserSelectorArg "Identity of user whose profile will be set." new_email common.EmailAddress? "New email for member." new_external_id team_common.MemberExternalId? "New external ID for member." new_given_name common.NamePart? "New given name for member." new_surname common.NamePart? "New surname for member." new_persistent_id String? "New persistent ID. This field only available to teams using persistent ID SAML configuration." example default user = default new_email = "t.smith@domain.com" new_surname = "Smith" union MembersSetProfileError extends MemberSelectorError external_id_and_new_external_id_unsafe "It is unsafe to use both external_id and new_external_id" no_new_data_specified "None of new_email, new_given_name, new_surname, or new_external_id are specified" email_reserved_for_other_user "Email is already reserved for another user." external_id_used_by_other_user "The external ID is already in use by another team member." set_profile_disallowed "Pending team member's email cannot be modified." param_cannot_be_empty "Parameter new_email cannot be empty." persistent_id_disabled "Persistent ID is only available to teams with persistent ID SAML configuration. Please contact Dropbox for more information." persistent_id_used_by_other_user "The persistent ID is already in use by another team member." route members/set_profile(MembersSetProfileArg, TeamMemberInfo, MembersSetProfileError) "Updates a team member's profile. Permission : Team member management" attrs auth = "team" owner = "adminx" # # Route members/set_admin_permissions # struct MembersSetPermissionsArg "Exactly one of team_member_id, email, or external_id must be provided to identify the user account." user UserSelectorArg "Identity of user whose role will be set." new_role AdminTier "The new role of the member." example default user = default new_role = default struct MembersSetPermissionsResult team_member_id team_common.TeamMemberId "The member ID of the user to which the change was applied." role AdminTier "The role after the change." example default team_member_id = "dbmid:9978889" role = default union MembersSetPermissionsError extends UserSelectorError last_admin "Cannot remove the admin setting of the last admin." user_not_in_team "The user is not a member of the team." cannot_set_permissions "Cannot remove/grant permissions." team_license_limit "Team is full. The organization has no available licenses." route members/set_admin_permissions(MembersSetPermissionsArg, MembersSetPermissionsResult, MembersSetPermissionsError) "Updates a team member's permissions. Permission : Team member management" attrs auth = "team" owner = "adminx" # # Route members/send_welcome_email # union MembersSendWelcomeError extends MemberSelectorError "" route members/send_welcome_email(UserSelectorArg, Void, MembersSendWelcomeError) "Sends welcome email to pending team member. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account. No-op if team member is not pending." attrs auth = "team" owner = "adminx" # # Route members/remove # struct MembersDeactivateArg "Exactly one of team_member_id, email, or external_id must be provided to identify the user account." user UserSelectorArg "Identity of user to remove/suspend." wipe_data Boolean = true "If provided, controls if the user's data will be deleted on their linked devices." example default user = default wipe_data = false struct MembersRemoveArg extends MembersDeactivateArg transfer_dest_id UserSelectorArg? "If provided, files from the deleted member account will be transferred to this user." transfer_admin_id UserSelectorArg? "If provided, errors during the transfer process will be sent via email to this user. If the transfer_dest_id argument was provided, then this argument must be provided as well." keep_account Boolean = false "Downgrade the member to a Basic account. The user will retain the email address associated with their Dropbox account and data in their account that is not restricted to team members. In order to keep the account the argument wipe_data should be set to False." example default user = default wipe_data = true transfer_dest_id = default transfer_admin_id = default keep_account = false union MembersDeactivateError extends UserSelectorError user_not_in_team "The user is not a member of the team." union MembersRemoveError extends MembersDeactivateError remove_last_admin "The user is the last admin of the team, so it cannot be removed from it." removed_and_transfer_dest_should_differ "Expected removed user and transfer_dest user to be different" removed_and_transfer_admin_should_differ "Expected removed user and transfer_admin user to be different." transfer_dest_user_not_found "No matching user found for the argument transfer_dest_id." transfer_dest_user_not_in_team "The provided transfer_dest_id does not exist on this team." transfer_admin_user_not_found "No matching user found for the argument transfer_admin_id." transfer_admin_user_not_in_team "The provided transfer_admin_id does not exist on this team." unspecified_transfer_admin_id "The transfer_admin_id argument must be provided when file transfer is requested." transfer_admin_is_not_admin "Specified transfer_admin user is not a team admin." cannot_keep_account_and_transfer "Cannot keep account and transfer the data to another user at the same time." cannot_keep_account_and_delete_data "Cannot keep account and delete the data at the same time. To keep the account the argument wipe_data should be set to False." email_address_too_long_to_be_disabled # Added value in order to handle task T82902. "The email address of the user is too long to be disabled." route members/remove(MembersRemoveArg, async.LaunchEmptyResult, MembersRemoveError) "Removes a member from a team. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account. Accounts can be recovered via :route:`members/recover` for a 7 day period or until the account has been permanently deleted or transferred to another account (whichever comes first). Calling :route:`members/add` while a user is still recoverable on your team will return with :field:`MemberAddResult.user_already_on_team`. This endpoint may initiate an asynchronous job. To obtain the final result of the job, the client should periodically poll :route:`members/remove/job_status/get`." attrs auth = "team" owner = "adminx" # # Route members/remove/job_status/get # route members/remove/job_status/get(async.PollArg, async.PollEmptyResult, async.PollError) "Once an async_job_id is returned from :route:`members/remove` , use this to poll the status of the asynchronous request. Permission : Team member management" attrs auth = "team" owner = "adminx" # # Route members/suspend # union MembersSuspendError extends MembersDeactivateError suspend_inactive_user "The user is not active, so it cannot be suspended." suspend_last_admin "The user is the last admin of the team, so it cannot be suspended." team_license_limit "Team is full. The organization has no available licenses." route members/suspend(MembersDeactivateArg, Void, MembersSuspendError) "Suspend a member from a team. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account." attrs auth = "team" owner = "adminx" # # Route members/unsuspend # struct MembersUnsuspendArg "Exactly one of team_member_id, email, or external_id must be provided to identify the user account." user UserSelectorArg "Identity of user to unsuspend." example default user = default union MembersUnsuspendError extends MembersDeactivateError unsuspend_non_suspended_member "The user is unsuspended, so it cannot be unsuspended again." team_license_limit "Team is full. The organization has no available licenses." route members/unsuspend(MembersUnsuspendArg, Void, MembersUnsuspendError) "Unsuspend a member from a team. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account." attrs auth = "team" owner = "adminx" # # Route members/recover # struct MembersRecoverArg "Exactly one of team_member_id, email, or external_id must be provided to identify the user account." user UserSelectorArg "Identity of user to recover." example default user = default union MembersRecoverError extends UserSelectorError user_unrecoverable "The user is not recoverable." user_not_in_team "The user is not a member of the team." team_license_limit "Team is full. The organization has no available licenses." route members/recover(MembersRecoverArg, Void, MembersRecoverError) "Recover a deleted member. Permission : Team member management Exactly one of team_member_id, email, or external_id must be provided to identify the user account." attrs auth = "team" owner = "adminx"