Users

Creating a new user

To create a new user you can use the /users endpoint. The method is POST. Ensure that the necessary permissions are provided to the API account to create or modify user accounts.

When you’re creating an account, the following fields are mandatory:

  • userName
  • password
  • firstName
  • lastName
  • timezone
  • workCountry

High-level request elements

userName

String

Specifies the username for the account

password

String

Specifies the password for the account.

Note the following password rules:

  • Alpha numeric [a-zA-Z0-9_].
  • Must have at least one uppercase and one lowercase character.
  • Minimum length is 8 characters.
  • Any special characters other than ‘_’ (underscore) can’t be used.

firstName

String

Specifies the first name of the user.

middleName

String

Specifies the middle name of the user.

lastName

String

Specifies the last name of the user.

title

String

The title of the user.

nickname

String

Preferred name to be shown in the platform interface.

status

String

Specifies the validity status of the user. The status can be one of the following:

  • Active (A)
  • Inactive (I)
  • Pending (P)
  • Suspended (B)
  • Deleted (D)

Note: The default status is PENDING. You can’t set the status while creating an account. Refer to the section about ‘user state machine’ just under the heading Users.

companyName

String

Specifies the company name.

jobTitle

String

Specifies the job title at the company.

division

String

Specifies the division in the company that this user is associated with.

department

String

Specifies the department in the company that this user is associated with.

Teams and Roles

String

Specifies the primary and secondary values for each respective variable:

  • teamName1, teamName2
  • role1, role2

Work Place Address

String

Specifies the primary and secondary values for each respective type. Of all these the workEmailAddress1 is the mandatory field:

  • workEmailAddress1, workEmailAddress2
  • workAddress1, workAddress2
  • workSuburb, workState
  • workPostCode, workCountry
  • workPostalAddress1, workPostalAddress2
  • workPostalSuburb, workPostalState
  • workPostalPostCode, workPostalCountry

Work Place Phones

Number

Specifies the primary and secondary values for each respective type. Of all these the workMobilePhone1 is the mandatory field:

  • workMobilePhone1, workMobilePhone2
  • workPhoneAreaCode1, workPhone1
  • workPhoneAreaCode2, workPhone2
  • workFaxAreaCode1, workFax1
  • workSetellitePhone, WorkOtherPhone

timezone

String

Specifies the time zone in which the user lives in. Values are relative to GMT.

Supported values are:

  • Offset from GMT in the format '+/-NN. For example, ‘+10’.
  • Worldwide time zone in the format ‘Country/City’. For example, ‘Australia/Melbourne’.

See the list of worldwide time zones.

Personal Address

String

Specifies the primary and secondary values for each respective type:

  • personalEmailAddress1, personalEmailAddress2
  • personalAddress1, personalAddress2
  • personalSuburb, personalState
  • personalCountry, personalPostCode

Personal Phones

Number

Specifies the primary and secondary values for each respective type:

  • personalPhoneAreaCode1, personalPhone1
  • personalPhoneAreaCode2, personalPhone2
  • personalFaxAreaCode1, personalFax1
  • otherPhoneAreaCode1, otherPhone1
  • otherMobile

Alias Fields

String

The other (alias) name and title fields:

  • otherFirstName, otherLastName, otherTitle

  • JSON
  • XML

Creating a new user

Users can easily be created by using the following request structure:

 

{{codeStart}}

POST https://api.<region>.whispir.com/users?apikey=[your api key]

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key

Content-Type: application/vnd.whispir.user-v1+json

{

"firstName": "John",

"lastName": "Wick",

"userName": "John.Wick",

"password": "AmF10gt_x",

"timezone": "Australia/Melbourne",

"workEmailAddress1": "jwick@testcompany.com",

"workMobilePhone1": "61423456789",

"workCountry": "Australia"

}

 

The successful response will be a 201 response with the details of the user created and their associated unique mri.

 

{

"userName": "John.Wick",

"password": "",

"status": "PENDING",

"firstName": "John",

"lastName": "Wick",

"personalEmailAddress2": "",

"personalCountry": "Australia",

"workEmailAddress1": "jwick@testcompany.com",

"workMobilePhone1": "61423456789",

"workCountry": "Australia",

"workPostalCountry": "Australia",

"timezone": "Australia/Melbourne",

"link": [

{

"uri": "https://api.<region>.whispir.com/users/AF48A9EC3F02E43C?apikey=[your api key]",

"rel": "self",

"method": "GET"

},

{

"uri": "https://api.<region>.whispir.com/users/AF48A9EC3F02E43C?apikey=[your api key]",

"rel": "updateUser",

"method": "PUT",

"type": "application/vnd.whispir.user-v1+xml,application/vnd.whispir.user-v1+json"

},

{

"uri": "https://api.<region>.whispir.com/users/AF48A9EC3F02E43C?apikey=[your api key]",

"rel": "deleteUser",

"method": "DELETE"

}

]

}

{{codeEnd}}