openapi: 3.0.1
info:
title: DocuSign Admin AccountBrands UserImport API
description: An API for an organization administrator to manage organizations, accounts and users
termsOfService: https://www.docusign.com/company/terms-and-conditions/developers
contact:
name: DocuSign Developer Center
url: https://developers.docusign.com
email: devcenter@docusign.com
version: v2.1
servers:
- url: https://api.docusign.net/Management
tags:
- name: UserImport
description: "Methods to import users.\n\nTo ensure your CSV is properly formatted, use the\n[Sample Bulk Add CSV file](https://admin.docusign.com/static-resources/organization-user-import.csv)\n as a template.\n\nYou can add up to 2,000 users to an account and include up to 50 accounts per import. The maximum number of users per import is 8,000."
paths:
/v2/organizations/{organizationId}/imports/bulk_users/add:
post:
tags:
- UserImport
summary: Docusign Creates a request to import new users into an account.
description: "Creates a request to import *new* users.\n\n- Required scopes: `user_write`\n\n\n\nYour CSV import file is made up of a header row with the column headers and a row of user or account data for each user you want to add to an account. Only new users can be imported. Any changes to existing users will be ignored. To make changes to existing users, use `updateBulkUserImports`.\n\nTo ensure your CSV is properly formatted, use the\n[Sample Bulk Add CSV file](https://admin.docusign.com/static-resources/organization-user-import.csv)\n as a template. The following table describes the columns.\n\n\n\n| Column | Required | Description |\n| :------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| AccountID | yes | The API account ID for the account to which you want you add the user. You can find this id in the Admin area for the account under **API and Keys**. |\n| AccountName | | The name of the user's account in your organization. The account name must match the account ID provided. |\n| FirstName | yes | The user's first name. |\n| LastName | yes | The user's last name. |\n| UserEmail | yes | The user's complete email address. |\n| PermissionSet | yes | The user's permission set. The PermissionSet value must match an existing permission set for the account. This value is not case sensitive. |\n| UserTitle | | The user's job title. |\n| CompanyName | | The user's company name. |\n| Group | | The user's assigned groups. The Group values must match existing Group names for the account. Additional Group columns can be added to the file to add users to more than one group. You do not need to add users to the Everyone group, since all new users are automatically added to that group. |\n| AddressLine1 | | The user's address, first line. |\n| AddressLine2 | | The user's address, second line. |\n| City | | The user's city name. |\n| StateRegionProvince | | The user's regional location. |\n| PostalCode | | The user's postal code. |\n| Phone | | The user's phone number. |\n| Language | | The user's display language for their DocuSign account. Must be one of: - Chinese Simplified:
zh_CN - Chinese Traditional:
zh_TW - Dutch:
nl - English:
en - French:
fr - German:
de - Italian:
it - Japanese:
ja - Korean:
ko - Portuguese:
pt - Portuguese Brazil:
pt_BR - Russian:
ru - Spanish:
es
|\n| LoginPolicy | | The user's login policy. Valid values include the following: - Column left blank = The user is created with no policy assigned.
- FedAuthRequired = The user must log in with an Identity Provider.
- FedAuthBypass = The user may log in with an Identity Provider or their DocuSign username and password.
For more information on login policies, see [Setting User Login Policy](https://support.docusign.com/en/guides/org-admin-guide-user-login-policy). |\n| AutoActivate | | For domain users, new users can be activated automatically for domain accounts using SSO by setting the value to **true**. The user is activated automatically once the import is complete. Memberships activated in this way do not receive an activation email. |\n\n\nYou can add up to 2,000 users to an account and include up to 50 accounts per import. The maximum number of users per import is 8,000."
operationId: OrganizationImport_OrganizationImportUsers_Insert
parameters:
- name: organizationId
in: path
description: The organization ID Guid
required: true
schema:
type: string
format: uuid
requestBody:
content:
multipart/form-data:
schema:
required:
- file.csv
type: object
properties:
file.csv:
type: string
description: CSV file.
format: binary
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationImportResponse'
security:
- accessCode:
- user_write
x-ds-methodname: addBulkUserImport
x-ds-method: addBulkUserImport
x-ds-service: BulkImports
x-ds-in-sdk: true
/v2/organizations/{organizationId}/imports/bulk_users/update:
post:
tags:
- UserImport
summary: Docusign Bulk updates information for existing users.
description: "Bulk updates information for existing users.\n\n- Required scopes: `user_write`\n\n\n\nYour CSV import file is made up of a header row with the column headers and a row of user or account data for each user you want to add to an account. Only new users can be imported. Any changes to existing users will be ignored. To make changes to existing users, use `updateBulkUserImports`.\n\n**Update limit**: You can update up to 2,000 users on an account and include up to 50 accounts per import. The maximum number of updated users per import is 8,000.\n\nThis method requires the following HTTP headers:\n\n| Header | Value |\n| :--- | :--- |\n| Content-Type | `text/csv` |\n| Content-Disposition | `filename=filename.csv` |\n\n\n\nTo ensure your CSV is properly formatted, use the\n[Sample Bulk Update CSV file](https://admin.docusign.com/static-resources/organization-user-update-import.csv)\n as a template. The following table describes the columns.\n\nNote that the columns for bulk adding users and bulk update users are slightly different.\nThe update CSV file requires an `APIUserName` column, and does not have an `AutoActivate` column.\n\n\n\n| Column | Required | Description |\n| :------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| AccountID | yes | The 32-character API account ID of the user's account in your organization. You can find this value in the API and Keys section of the Admin area of the account. |\n| AccountName | | The name of the user's account in your organization. The account name must match the account ID provided. |\n| FirstName | yes | The user's first name. |\n| LastName | yes | The user's last name. |\n| UserEmail | yes | The user's complete email address. |\n| PermissionSet | yes | The user's permission set. The PermissionSet value must match an existing permission set for the account. This value is not case sensitive. |\n| UserTitle | | The user's job title. |\n| CompanyName | | The user's company name. |\n| Group | | The user's assigned groups. The Group values must match existing Group names for the account. Additional Group columns can be added to the file to add users to more than one group. You do not need to add users to the Everyone group, since all new users are automatically added to that group. |\n| AddressLine1 | | The user's address, first line. |\n| AddressLine2 | | The user's address, second line. |\n| City | | The user's city name. |\n| StateRegionProvince | | The user's regional location. |\n| PostalCode | | The user's postal code. |\n| Phone | | The user's phone number. |\n| Language | | The user's display language for their DocuSign account. Must be one of: - Chinese Simplified:
zh_CN - Chinese Traditional:
zh_TW - Dutch:
nl - English:
en - French:
fr - German:
de - Italian:
it - Japanese:
ja - Korean:
ko - Portuguese:
pt - Portuguese Brazil:
pt_BR - Russian:
ru - Spanish:
es
|\n| LoginPolicy | | The user's login policy. Valid values include the following: - Column left blank = The user is created with no policy assigned.
- FedAuthRequired = The user must log in with an Identity Provider.
- FedAuthBypass = The user may log in with an Identity Provider or their DocuSign username and password.
For more information on login policies, see [Setting User Login Policy](https://support.docusign.com/en/guides/org-admin-guide-user-login-policy). |\n| AutoActivate | | For domain users, new users can be activated automatically for domain accounts using SSO by setting the value to **true**. The user is activated automatically once the import is complete. Memberships activated in this way do not receive an activation email. |\n\n\n\n## Updating user email addresses\n\nChanging a user's email address should be done carefully. The user's email address is used to log in to DocuSign and receive documents to sign from others.\nOnce changed, existing documents that were sent or received:\n\n- Will still appear in the user's documents list.\n- Notifications about these documents will be sent to the new email address. If someone sends a new document to the old email address:\n- DocuSign will send a notification to the old address.\n- It will not appear in the documents list of the account.\n\nThis change of email address will be applied to all of the user's account memberships."
operationId: OrganizationImport_OrganizationImportUsers_Update
parameters:
- name: organizationId
in: path
description: The organization ID Guid
required: true
schema:
type: string
format: uuid
requestBody:
content:
multipart/form-data:
schema:
required:
- file.csv
type: object
properties:
file.csv:
type: string
description: CSV file.
format: binary
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationImportResponse'
security:
- accessCode:
- user_write
x-ds-methodname: updateBulkUserImports
x-ds-method: updateBulkUserImports
x-ds-service: BulkImports
x-ds-in-sdk: true
/v2/organizations/{organizationId}/imports/bulk_users/close:
post:
tags:
- UserImport
summary: Docusign Creates a request to close the accounts of existing users.
description: "Creates a request to close the accounts of existing users.\n\n- Required scopes: `user_write`\n\nGiven a CSV list of users, close their accounts.\n\n\nYour CSV import file is made up of a header row with the column headers and a row of user or account data for each user whose account you want to close.\n\nTo ensure your CSV is properly formatted, use the\n[Sample Bulk Update CSV file](https://admin.docusign.com/static-resources/organization-user-update-import.csv)\n as a template. The following table describes the columns.\n\n\n\n\n| Column | Required | Description |\n| :------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| AccountID | yes | The 32-character API account ID of the user's account in your organization. You can find this value in the API and Keys section of the Admin area of the account. |\n| AccountName | | The name of the user's account in your organization. The account name must match the account ID provided. |\n| FirstName | yes | The user's first name. |\n| LastName | yes | The user's last name. |\n| UserEmail | yes | The user's complete email address. |\n| PermissionSet | yes | The user's permission set. The PermissionSet value must match an existing permission set for the account. This value is not case sensitive. |\n"
operationId: OrganizationImport_OrganizationImportUsers_Close
parameters:
- name: organizationId
in: path
description: The organization ID Guid
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationImportResponse'
security:
- accessCode:
- user_write
x-ds-methodname: closeBulkUserImportRequest
x-ds-method: closeBulkUserImportRequest
x-ds-service: BulkImports
x-ds-in-sdk: true
/v2/organizations/{organizationId}/imports/bulk_users/close_external:
post:
tags:
- UserImport
summary: Docusign Closes external memberships.
description: 'Closes external memberships.
- Required scopes: `user_write`
External memberships are:
- Users who have an email address at a verified domain
- But do not belong to the organization
'
operationId: OrganizationImport_OrganizationImportUsers_CloseExternal
parameters:
- name: organizationId
in: path
description: The organization ID Guid
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationImportResponse'
security:
- accessCode:
- user_write
x-ds-methodname: closeBulkExternalUserImportRequest
x-ds-method: closeBulkExternalUserImportRequest
x-ds-service: BulkImports
x-ds-in-sdk: true
/v2/organizations/{organizationId}/imports/bulk_users:
get:
tags:
- UserImport
summary: Docusign Gets a list of all of the user import requests.
description: 'Gets a list of all of the user import requests.
- Required scopes: `user_read`
'
operationId: OrganizationImport_OrganizationImportUsers_Get
parameters:
- name: organizationId
in: path
description: The organization ID Guid
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationImportsResponse'
security:
- accessCode:
- user_read
x-ds-methodname: getBulkUserImportRequests
x-ds-method: getBulkUserImportRequests
x-ds-service: BulkImports
x-ds-in-sdk: true
/v2/organizations/{organizationId}/imports/bulk_users/{importId}:
get:
tags:
- UserImport
summary: Docusign Returns the details of a single user import request.
description: 'Returns the details of a single user import request.
- Required scopes: `user_read`
Use this method to check the status of the request by looking at the `status` property of the response.
Once the status becomes `completed` (or fails), use this method to get the details.
To get a list of all of the user import requests, use `getBulkUserImportRequests`.'
operationId: OrganizationImport_OrganizationImportUsers_GetById
parameters:
- name: organizationId
in: path
description: The organization ID Guid
required: true
schema:
type: string
format: uuid
- name: importId
in: path
description: The import ID GUID for the request.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationImportResponse'
security:
- accessCode:
- user_read
x-ds-methodname: getBulkUserImportRequest
x-ds-method: getBulkUserImportRequest
x-ds-service: BulkImports
x-ds-in-sdk: true
delete:
tags:
- UserImport
summary: Docusign Deletes a specific user import request.
description: 'Deletes a specific import request and its results.
- Required scopes: `user_write`
To delete a user, see `closeBulkUserImportRequest`.'
operationId: OrganizationImport_OrganizationImportUsers_DeleteById
parameters:
- name: organizationId
in: path
description: The organization ID Guid
required: true
schema:
type: string
format: uuid
- name: importId
in: path
description: The import ID GUID for the request.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
security:
- accessCode:
- user_write
x-ds-methodname: deleteBulkUserImport
x-ds-method: deleteBulkUserImport
x-ds-service: BulkImports
x-ds-in-sdk: true
/v2/organizations/{organizationId}/imports/bulk_users/{importId}/results_csv:
get:
tags:
- UserImport
summary: 'Docusign Given the ID of a user import request,
return the CSV file that was imported.'
description: 'Returns the contents of the CSV file
associated with a user import request.
- Required scopes: `user_read`
The results have an additional column,
`ProcessingResults`,
that describes the results of importing that row.
'
operationId: OrganizationImport_OrganizationImportUsers_GetCSVResults
parameters:
- name: organizationId
in: path
description: The organization ID Guid
required: true
schema:
type: string
format: uuid
- name: importId
in: path
description: The import ID GUID for the request.
required: true
schema:
type: string
format: uuid
responses:
'200':
description: OK
content:
text/csv:
schema:
type: object
security:
- accessCode:
- user_read
x-ds-methodname: getBulkUserImportCSV
x-ds-method: getBulkUserImportCSV
x-ds-service: BulkImports
x-ds-in-sdk: true
components:
schemas:
OrganizationImportResponseRequestor:
type: object
properties:
name:
type: string
description: ''
id:
type: string
description: ''
type:
type: string
description: ''
email:
type: string
description: The email address.
description: ''
x-ds-definition-name: OrganizationImportResponseRequestor
x-ms-summary: ''
OrganizationImportResponseErrorRollup:
type: object
properties:
error_type:
type: string
description: ''
count:
type: integer
description: ''
format: int32
description: ''
x-ds-definition-name: OrganizationImportResponseErrorRollup
x-ms-summary: ''
OrganizationImportResponse:
type: object
properties:
id:
type: string
description: ''
format: uuid
example: 00000000-0000-0000-0000-000000000000
type:
type: string
description: ''
requestor:
$ref: '#/components/schemas/OrganizationImportResponseRequestor'
created:
type: string
description: ''
format: date-time
last_modified:
type: string
description: ''
format: date-time
status:
type: string
description: Status.
user_count:
type: integer
description: ''
format: int32
processed_user_count:
type: integer
description: ''
format: int32
added_user_count:
type: integer
description: ''
format: int32
updated_user_count:
type: integer
description: ''
format: int32
closed_user_count:
type: integer
description: ''
format: int32
no_action_required_user_count:
type: integer
description: ''
format: int32
error_count:
type: integer
description: ''
format: int32
warning_count:
type: integer
description: ''
format: int32
invalid_column_headers:
type: string
description: ''
imports_not_found_or_not_available_for_accounts:
type: string
description: ''
imports_failed_for_accounts:
type: string
description: ''
imports_timed_out_for_accounts:
type: string
description: ''
imports_not_found_or_not_available_for_sites:
type: string
description: ''
imports_failed_for_sites:
type: string
description: ''
imports_timed_out_for_sites:
type: string
description: ''
file_level_error_rollups:
type: array
description: ''
items:
$ref: '#/components/schemas/OrganizationImportResponseErrorRollup'
user_level_error_rollups:
type: array
description: ''
items:
$ref: '#/components/schemas/OrganizationImportResponseErrorRollup'
user_level_warning_rollups:
type: array
description: ''
items:
$ref: '#/components/schemas/OrganizationImportResponseWarningRollup'
has_csv_results:
type: boolean
description: ''
results_uri:
type: string
description: ''
description: ''
x-ds-definition-name: OrganizationImportResponse
x-ms-summary: ''
OrganizationImportsResponse:
type: object
properties:
imports:
type: array
description: ''
items:
$ref: '#/components/schemas/OrganizationImportResponse'
description: ''
x-ds-definition-name: OrganizationImportsResponse
x-ms-summary: ''
OrganizationImportResponseWarningRollup:
type: object
properties:
warning_type:
type: string
description: ''
count:
type: integer
description: ''
format: int32
description: ''
x-ds-definition-name: OrganizationImportResponseWarningRollup
x-ms-summary: ''
securitySchemes:
accessCode:
type: oauth2
description: OAuth2 Access code Grant
flows:
authorizationCode:
authorizationUrl: https://account.docusign.com/oauth/auth
tokenUrl: https://account.docusign.com/oauth/auth
scopes:
organization_read: ''
permission_read: ''
group_read: ''
user_read: ''
account_read: ''
account_write: ''
user_write: ''
identity_provider_read: ''
domain_read: ''
x-ds-categories:
- name: UserManagement
summary: Methods to manage users in an account.
description: Methods to manage users in an account.
- name: BulkOperations
summary: Methods to import and export users and accounts.
description: Methods to import and export users and accounts.
- name: IdentityProviders
summary: Methods to get a list of identity providers.
description: Methods to get a list of identity providers.
- name: ReservedDomains
summary: Methods to get a list of reserved domains.
description: Methods to get a list of reserved domains.
- name: Organization
summary: Methods for working with organizations.
description: Methods for working with organizations.
x-original-swagger-version: '2.0'