Users (V2)

Users (V2) API allows an authenticated user with the required permissions to retrieve users within their organizations.

GET Users

	GET /users
Method	GET
URL or End Point	/access/v2/users
Headers	Authorization, Content-Type
Query Parameters	keyword, status, favoriteOnly, userRoles, sorts, offset, limit
Body	Not applicable

This method retrieves a list of existing portal users in your organization based on your search criteria. Only an authenticated user from your organization with portal access can use this method.The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.

The following screenshots show sample curl requests for different scenarios, and a successful JSON response for this method. The request was for a user retrieving their own profile information, and the response returned shows the request was successful.

Search for users with various status types

Copy

curl -X
GET "https://api.equinix.com/access/v2/users?keyword=John&status=ACTIVE,APPROVED,LOCKED&favoriteOnly=true&userRoles=USER&sorts=STATUS&offset=0&limit=1"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

Search for users with status type = TERMINATED

Copy

curl -X
GET "https://api.equinix.com/access/v2/users?keyword=John&status=TERMINATED&favoriteOnly=false&userRoles=USER&sorts=STATUS&offset=0&limit=1"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

The description of the query parameter is as follows:

Query Parameter name	Mandatory	Type	Example	Applicable Values	Description
keyword	No	string	John		Filters search according to this keyword. This is free text input. For example, this could be a first name (given name), last name (surname), username, or primary email. Any user with this keyword in their first name, last name, username or primary email address will be returned. Limit: 1200 characters
status	No	array [strings]	ACTIVE, APPROVED, LOCKED	NEW, APPROVED, ACTIVE, INACTIVE, LOCKED, TERMINATED	Status of the user. Multiple statuses should be comma-separated. Default value: all statuses except TERMINATED Status - Description NEW - User was invited by the administrator through the portal, and submitted their user profile for your administrator approval. APPROVED - User was created or approved by your administrator. User can be listed as a notification or technical contact. ACTIVE - Approved user with permissions assigned by your administrator. Once a user has their password created, they can log into the portal. User can be an ordering, notification or technical contact. INACTIVE - User was deactivated, and can no longer access the portal or IBX. To reactivate your account, contact your Master Administrator. LOCKED - User profile is locked. User is unable to log into the portal, but can still be listed as a notification or technical contact. TERMINATED - User's portal profile, permissions, and IBX access have been terminated. This status is permanent and cannot be changed.
favoriteOnly	No	boolean	true	true, false	Searches for users marked as favorite. Default value: false When true, only favorite users of the authenticated user will be returned. When false, all users will be returned.
userRoles	No	array [strings]	USER	MASTER_ADMIN, IBX_ADMIN, USER	User role or portal user type. Multiple roles should be comma-separated. Default value: all user roles User role - Description MASTER_ADMIN - Master Administrators can create and manage other master administrators, IBX administrators and common users for all IBXs. IBX_ADMIN - IBX Administrators may create and manage common users for selected IBXs or cages. USER - Common user with permissions assigned to them by Master or IBX administrators.
sorts	No	array [string]	STATUS	EMAIL, FIRST_NAME, LAST_NAME, ROLE, STATUS, -EMAIL, -FIRST_NAME, -LAST_NAME, -ROLE, -STATUS	Sorting preference for the returned record. Default: Users are sorted in descending order of their activation date Sorts - Description EMAIL - Users will be returned in ascending alphanumeric order of their primary email address. FIRST_NAME - Users will be returned in ascending alphanumeric order of their first or given name. LAST_NAME - Users will be returned in ascending alphanumeric order of their last name or surname. ROLE - Users will be returned in ascending alphanumeric order of their user role. STATUS - Users will be returned in ascending alphanumeric order of their user status. When these sorts values are prefixed by '-' users will be returned in descending order instead.
offset	No	integer	0		Defines the index of the first record returned in the response. By specifying the offset, the response returns a subset of records starting with the offset value. For example, if the offset is 10, the starting record returned in the response would be the 11th record. Default value: 0
limit	No	integer	1		Defines the maximum number of records returned in your query. Default value: 10 Limit: 1 to 200

Copy

{
    "data": [
        {
            "username": "johndoe1",
            "firstName": "John",
            "lastName": "Doe",
            "email": "johndoe@corp.com",
            "title": "Manager",
            "department": "Procurement",
            "status": "TERMINATED",
            "securityProfile": "COMPLETED",
            "userRole": "USER",
            "isFavourite": false,
            "activationDateTime": "2021-05-20T13:58:09Z",
            "deactivationDateTime": "2022-01-29T01:10:11Z",
            "deletedDateTime": "2022-03-29T01:10:11Z",
            "createdDateTime": "2021-05-20T13:58:09Z",
            "updatedDateTime": "2021-05-20T14:34:15Z"

        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 1,
        "total": 1,
        "next": "/users?keyword=John&status=TERMINATED&favoriteOnly=flase&userRoles=USER&sorts=STATUS&offset=0&limit=1",
        "previous": "/users?keyword=John&status=TERMINATED&favoriteOnly=false&userRoles=USER&sorts=STATUS&offset=0&limit=1"
    }
}

The description of the response payload is as follows:

Field name	Type	Example	Description
data	array [objects]		Data returned from your query. Each user object comprises the following fields where applicable: username, firstName, lastName, email, title, department, status, securityProfile, userRole, isFavourite.
username	string	johndoe1	Username of the portal user.
firstName	string	Johnathan	Legal first name or given name.
lastName	string	Doe	Legal last name, surname, or family name.
email	string	johndoe@corp.com	Primary email address.
title	string	Manager	Job title or designation of user. Limit: 1 - 50 characters.
department	string	Procurement	Department to which the new user belongs. Limit: 1 - 50 characters.
status	string	ACTIVE	Status of the user. Refer to the description of query parameter 'status' for more information.
securityProfile	string	COMPLETED	IBX security profile status. Security profile status - Description COMPLETED - User has set up their security profile to access the IBX. NOT_COMPLETED - User has not completed setting up their security profile. Until their security profile is completed, they cannot physically access any IBX. NOT_APPLICABLE - Security profile setup is not applicable to the user. You need to assign permissions to the user.
userRole	string	USER	User role or portal user type. Refer to the description of query parameter 'userRole' for more information.
isFavourite	boolean	true	Favorite status of the user. Refer to the description of query parameter 'FavouriteOnly' for more information.
activationDateTime	string	2021-05-20T13:58:09Z	Date and time of user's activation. Activation applies to the ACTIVE state. Refer to the description of query parameter 'status' for more information.
deactivationDateTime	string	2022-01-29T01:10:11Z	Date and time of user's deactivation. Deactivation applies to the INACTIVE state. Refer to the description of query parameter 'status' for more information.
deletedDateTime	string	2022-03-29T01:10:11Z	Date and time of user's profile termination. Termination applies to the TERMINATED state. Refer to the description of query parameter 'status' for more information.
createdDateTime	string	2021-05-20T13:58:09Z	Date and time of user's profile creation. Creation applies to the APPROVED state. Refer to the description of query parameter 'status' for more information.
updatedDateTime	string	2021-05-20T14:34:15Z	Date and time of user's profile update.
pagination	object		Page information. This object comprises the following fields: offset, limit, total, next, previous.
offset	integer	1	Offset of the first record in the response, as defined in the query parameter 'offset'.
limit	integer	1	Maximum number of records in the response, as defined in the query parameter 'limit'.
total	integer	11	Total number of available records.
next	string	/users?offset=1&limit=1	URL for the next page of results.
previous	string	/users?offset=0&limit=1	URL for the previous page of results.

To verify the username is associated with the intended user, retrieve the user's profile for further details with GET Users {username}. This method is applicable for existing portal users, and does not apply to terminated users.

If you get “Insufficient permissions” error, contact your Master Administrator.

GET Users {username}

	GET /users/{username}
Method	GET
URL or End Point	/access/v2/users/{username}
Headers	Authorization, Content-Type
Query Parameters	Not applicable
Body	Not applicable

This method retrieves a portal user's profile details by their username. An authenticated user with any portal permissions may retrieve the profile information of any user in their organization. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

This method retrieves the user profiles for users with the following statuses:

NEW
APPROVED
ACTIVE
LOCKED
INACTIVE

For more information on these statuses, refer below to the description of the response payload field 'status'.

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.

The following screenshots show a sample curl request and JSON response for this method. The request was for a user retrieving their own profile information, and the response returned shows the request was successful.

Copy

curl -X
GET "https://api.equinix.com/access/v2/users/johndoe1"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

The description of the URL parameters is as follows:

URL Parameter name	Mandatory	Type	Example	Applicable Values	Description
username	Yes	string	johndoe1		Username of the portal user whose profile you want to retrieve. If you are unsure of the exact username, contact your Master Administrator. Limit: 8-250 characters.

URL Parameter name

Mandatory

Type

Example

Applicable Values

Description

username

Yes

string

johndoe1

Username of the portal user whose profile you want to retrieve.

If you are unsure of the exact username, contact your Master Administrator.

Limit: 8-250 characters.

Copy

{
    "status": "ACTIVE",
    "username": "johndoe1",
    "firstName": "John",
    "lastName": "Doe",
    "localName": "ジョン・ドー",
    "contactDetails": [
        {
            "type": "PHONE",
            "value": "+1-987-654-3210"
        },
        {
            "type": "EMAIL",
            "value": "johndoe@corp.com"
        },
        {
            "type": "MOBILE",
            "value": "+1-987-123-4567"
        },
        {
            "type": "SECONDARY_EMAIL",
            "value": "janesmith@corp.com"
        }
    ],
    "companyName": "Sample Company",
    "companyLocalName": "サンプル会社",
    "title": "Manager",
    "department": "Procurement",
    "activationDateTime": "2021-05-20T13:58:09Z",
    "createdDateTime": "2021-05-20T13:58:09Z",
    "updatedDateTime": "2021-05-20T14:34:15Z",
    "updatedByFullName": "Chris Admin",
    "timezone": "Asia/Tokyo",
    "locale": "JA_JP"
}

The description of the response payload is as follows:

Field name	Type	Example	Description
status	string	ACTIVE	Status of the user. Status - Description NEW - User was invited by the administrator through the portal, and submitted their user profile for your administrator approval. APPROVED - User was created or approved by your administrator. User can be listed as a notification or technical contact. ACTIVE - Approved user with permissions assigned by your administrator. Once a user has their password created, they can log into the portal. User can be an ordering, notification or technical contact. INACTIVE - User was deactivated, and can no longer access the portal. To reactivate your account, contact your Master Administrator. LOCKED - User profile is locked. User is unable to log into the portal, but can still be listed as a notification or technical contact. Profiles of users with other statuses will not be returned.
username	string	johndoe1	Username of the portal user. This is either provided during the user profile creation, or defaulted to the user's primary email address when the username was not provided.
firstName	string	Johnathan	Legal first name or given name.
lastName	string	Doe	Legal last name, surname, or family name.
localName	string	ジョン・ドー	User's legal name in non-Western characters.
contactDetails	array [objects]		List of contact details for this person. Each contact detail object consists of the following fields: type, value.
type	string	PHONE	Type of contact detail in the type-value pair. Type - Description PHONE - Primary phone number. EMAIL - Email address. MOBILE - Mobile phone number. This is the secondary contact number. SECONDARY_EMAIL - Secondary email address.
value	string	+1-987-654-3210	Value related to the contact detail type in the type-value pair.
companyName	string	Sample Company	Company name associated with user.
companyLocalName	string	サンプル会社	Name of the company in non-Western characters.
title	string	Manager	Job title or designation of user.
department	string	Procurement	Department to which the new user belongs.
activationDateTime	string	2021-05-20T13:58:09Z	Date and time of user's activation. Refer to the description of query parameter 'status' for more information.
createdDateTime	string	2021-05-20T13:58:09Z	Date and time of user's profile creation. Creation applies to the APPROVED state. Refer to the description of query parameter 'status' for more information.
updatedDateTime	string	2021-05-20T14:34:15Z	Date and time of user's profile update.
updatedByFullName	string	Chris Admin	The full name of the administrator who updated the user's profile.
timezone	string	Asia/Tokyo	User's preferred time zone to be contacted. For a full list of time zones, see Time Zone in the Appendix.
locale	string	EN_US	Preferred language of the user. For a full list of locale codes, see Locale Codes in the Appendix.

If you get “Insufficient permissions” error, contact your Master Administrator.

GET Users

GET Users {username}

Was this documentation helpful?