Service endpoint that lets to perform 1 to 10 operations to create, update or delete users and assign Spaces license to new created or existing user. Only service app authentication is permitted. User emails must belong to the same company that owns service app. Service app must have "accounts.users.bulk.write" scope to use this endpoint.

URL Parameters

None.

Body Parameters

NameDescriptionJSON typeRequiredValid Values
actionActionstringYes"create", "update", "delete"
emailUser emailstringYesMust be valid email.Must belong to one of domains of company.
passwordNew password when create or update userstringcreate-Yes, update-No, delete-NoLength must be 4-200 characters
firstnameUser's first name. If both firstname and lastname are empty or none, set email as user name.stringNoMust not contain special characters (|~!@#$%^&*()_+=<>?:;,."). Total length user's displayname ("firstname" + "lastname") must not be greater than 380.
lastnameUser's last name. If both firstname and lastname are empty or none, set email as user name. stringNoMust not contain special characters (|~!@#$%^&*()_+=<>?:;,."). Total length user's displayname ("firstname" + "lastname") must not be greater than 380.
languageUser's primary language. If empty or none set default language ("en") as user's primary language when "action" is "create" and do nothing if "action" is "update". If value was not recognized as existing language code, set default language ("en") when "action" is "create" and do nothing if "action" is "update".stringNo
cellphoneUser's mobile phone number.stringNoMust be valid phone number, starting with "+"
workphoneUser's work phone number.stringNoMust be valid phone number, starting with "+"
license_typeSpaces license type to assign. Company must have license of this type. If "action" is "update" and value is empty (""), deallocate spaces license from user if user has one.stringNo

"spaces_power",

"spaces_business",

""

Authentication

ServiceAppAuthenticator

Authorization

None

Example Request

URL

For Production: POST https://accounts.avayacloud.com/api/1.0/users/bulkupdate
For Staging: POST https://onesnastaging.esna.com/api/1.0/users/bulkupdate

Headers

Authorization: "service_app eyJhbGciOiJSUzI1NiIsIdfgdfgnR5cCI6IkpXVCJ9.eyJ1c2VyX2lkX3NpZyI6ImxPWHpxNzVzR3J3X0xwWEMyRGRMakhyYXJlWVhyTzFMdEZHZkhkOWNkTXciLCJwcm9kdWN0X3R5cGUiOiJhY2NvdW50cyIsImxhc3R1cGRhdGV0aW1lIjoiMjAxNy0wMS0zMFQxMzo1ODo0Ny4yMDYiLCJpc3MiOiJ6YW5nLmlvIiwicHVibGlja2V5aWQiOiJhZ3h6Zm05dVpYTnVZVEl3TVRSeUdnc1NEVWRLZDNSUWRXSnNhV05MWlhrdfgdWdJQ2dsUEtFakFvTSIsImV4cCI6MTQ5NTM5MTIwMywidXNlcl9pZCI6ImFneHpmbTl1WlhOdVlUSXdNVFJ5RVFzU0JGVnpaWElZZ0lEQXMtX25fUW9NIiwidmVyIjoiMi4wIn0.SqZpw1uPIebqW3qlDsm0-DWYFKEH0SgPwtD-tSESWOF-5hLkZMqJH28ooWux2S7s9riIew7pTVPnZpTgJa5zHcEAG0gXSEJVOqmpGp_4ufM8YtZoZMpBFjyAkwyAt-ILkGUYIo0GU5WyzMPLV8YLXfgdfgOgkE2MGGOajBkjPmC2Db3pA0D0M9k-21EL1gwWBC5YIq0PDAkgulegwl6khRmB8irJQ-dfg-d-KV9eYfFpsCdJKRGzSfqg"

Body

[{
	"action": "create",
	"email": "user1@somecompany.com",
	"password": "password",
	"firstname": "firstname",
	"lastname": "lastname",
	"language": "fr",
	"cellphone": "+37066111111",
	"workphone": "+37066222222",
	"license_type": "spaces_business"
}]

Example Response

{

	"action": "create",
	"status": "success",
	"data": {
		"id": "aghkZXZ-Tm9uZXIRCxIEVXNlchiAgICAoPSKCAw",
		"username": "user1@somecompany.com",
		"name": {
			"familyname": "lastname",
			"formatted": "",
			"givenname": "firstname",
			"honorific_prefix": "",
			"honorific_suffix": "",
			"middlename": "",
			"pronunciation": "",
			"pronunciation_url": ""
		},
		"last_login": null,
		"date_joined": "2021-09-07T08:17:42.936000",
		"lastmodifiedversion": "2021-09-07T08:17:45.350000",
		"user_action_required": 0,
		"emails": [{
			"value": "user3@newcompany.com",
			"type": "",
			"primary": true,
			"label": "",
			"relationdef_id": "aghkZXZ-Tm9uZXIYCxILUmVsYXRpb25EZWYYgICAgKD0igoM"
		}],
		"languages ": [

			{
				"code": "fr-FR",
				"primary": true
			}
		],


		"timezone": "",
		"picture_url": "http://localhost:9000/norevimages/noimage.jpg",
		"relation_graphs": [{
			"relationdef_id": "aghkZXZ-Tm9uZXIYCxILUmVsYXRpb25EZWYYgICAgKD0igoM",
			"initiator_id": "aghkZXZ-Tm9uZXIUCxIHQ29tcGFueRiAgICAgOqUCQw",
			"initiator_type": "company",
			"relation_type": "employee"
		}],
		"phone_numbers": [{
				"value": "+37066222222",
				"type": "work",
				"canonicalForm": "+37066222222",
				"primary": true,
				"verified": false,
				"identity": false,
				"login": false,
				"unique": false,
				"qualified_method": "",
				"verify_method": "",
				"verified_on": null,
				"private_num": false,
				"formattedType": "Work"
			},
			{
				"value": "+37066111111",
				"type": "mobile",
				"canonicalForm": "+37066111111",
				"primary": false,
				"verified": false,
				"identity": false,
				"login": false,
				"unique": false,
				"qualified_method": "",
				"verify_method": "",
				"verified_on": null,
				"private_num": true,
				"formattedType": "Mobile"
			}
		],
		"addresses": [],
		"gender": "",
		"displayname": "firstname lastname",
		"permissions": [
			//user's permissions
		],
		"licenses": [{
			"purchased_license_id": "aghkZXZ-Tm9uZXIdCxIQUHVyY2hhc2VkTGljZW5zZRiAgICAgL_vCAw",
			"service_type": "zangspaces_business",
			"product_type": "zangspaces",
			"expiration": "2022-02-01T09:00:00",
			"parentid": "aghkZXZ-Tm9uZXIUCxIHQ29tcGFueRiAgICAgOqUCQw",
			"parent_type": "company",
			"trial": false,
			"allocated": "2021-09-07T08:17:46.713000",
			"parent_displayname": "new_company"
		}]
	}
}

Errors

General errors

Response example:

{
    "error": {
        "message": "User bulk API invalid data: list required",
        "code": "user_bulk.list_required"
    }
}
Error codeResponse codeError messageDescription
user_bulk.list_required400User bulk API invalid data: list requiredAPI expects array, but got another type
user_bulk.data_empty400User bulk API invalid data: list is emptyGot empty array
user_bulk.limit_exceed400User bulk API request data limit exceededRequest body objects limit exceeded (10)
service_app.scope_required403No required scope configured for service appService app must have scope for this endpoint("accounts.users.bulk.write")

Field errors

Endpoint return errors for every object that does not fit requirements.

Error code is dot-separated location (field) and reason.

Example:

{
        "action": "create",
        "errors": [
            {
                "message": "User already exists.",
                "code": "email.user_exists"
            }
        ],
        "status": "error"
    }
Location (fields)Error reasonDescription
emailduplicate_addressEmail address has already been used in this request.
emailinvalid_domainUser email does not match any of company's domain.

action,

license_type

invalid_choiceInvalid choice.

email,

password,

firstname,

lastname,

workphone,

cellphone

invalid_valueInvalid value.

action,

email,

password (for "create" action only)

field_requiredThis field is required.
email ("create")user_existsCan not create new user. User with this email already exists.
email ("update", "delete")user_does_not_existCan not update or delete user. User with this email does not exists.
non_field_errorsdisplayname_too_longUser's display name ("firstname" + "lastname") is too long (greater than 380 characters).

Warnings

Endpoint returns warnings if user was successfully created or updated but Spaces license can not be assigned.

For example:

{
      "action": "create",
      "status": "success",
      "warnings": [
            {
                "code": "license.assigning_error",
                "message": "Can not assign "spaces_business" license to user"
            }
        ],
       "data": {

                     //user data
                     ...
                   },
        
    }

Possible error codes are :

  • "license.assigning_error" - Can not assign specific license to user.
  • "license.not_found" - Company does not have Spaces license.