The docs are moving!

Find us at our new Help Center where we've combined our documentation and knowledgebase articles in one easy-to-search location.

We aren't updating the Developer Portal anymore, except for the Element Docs — all updates happen in the Help Center. We're retiring the Developer Portal as you know it in:

UI API

Manage Accounts

If you are the user who created the organization, you are the organization administrator. You can manage the accounts related to the organization with the /accounts endpoint. You can create, retrieve, update, delete, and search accounts. To manage accounts, you must include a valid Organization Secret and the User Secret of the organization administrator in the header of any API requests to /accounts. If any requests come from someone else, even a user that you add to the default account, they will receive a 401 Unauthorized error code.

On this page
Find Accounts
Add an Account
Add Users to Accounts
Get a Specific Account
Update an Account
Deactivate and Reactivate an Account
Delete an Account

Find Accounts

You can see all of the accounts in your organization with the GET /accounts endpoint. If you have many accounts, adding a CEQL query helps to keep the response manageable.

Find Accounts Parameters

Name	Description	Required
where	The CEQL search expression is a where clause like in a typical SQL query, but without the WHERE keyword. For example, to search for accounts created on or after ‘Jan 15, 2017′, use a search expression like `where=createdDate >= ‘2014-01-17′`. If you do not use a CEQL query, the endpoint returns all accounts in a paginated fashion.	N
offset	The record offset at which to begin the paginated results. Default 0	N
pageSize	The page size for the paginated results. Default 200	N

Find Accounts Example Request

curl -X GET \
  'https://api.cloud-elements.com/elements/api-v2/accounts?where=createdDate%3E'\''2017-01-15'\''&offset=1&pageSize=200' \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \

Find Accounts Example Response

[
  {
    "id": 1234,
    "name": "Company Default Account",
    "description": "Auto created default account for the entire company",
    "active": true,
    "companyId": 999,
    "createdDate": "2017-03-23",
    "externalId": "you@yourcompany.com",
    "defaultAccount": true,
    "type": "Default"
  },
  {
    "id": 3780,
    "name": "Customer Account",
    "description": "A customer's account",
    "active": true,
    "companyId": 998,
    "createdDate": "2017-04-25",
    "externalId": "1984",
    "defaultAccount": false,
    "type": "CompanyAccount"
  }
]

Account Attributes

The attribute names that appear only in the JSON response appear in code format.

Name	Description
ID `id`	The unique identifier for an account within an organization. Use in any `/accounts` endpoint with an {id} variable.
Name `name`	The name of the account.
Description `description`	A brief description of the account.
Active `active`	Indicates if the account is active. In the JSON response `true` is active and `false` is inactive.
`companyId`	The unique identifier of the organization created at initial signup.
Created `createdDate`	The date when the organization administrator created the account.
`externalID`	A unique identifier for the account, required to add an account using `POST/ accounts`.
`defaultAccount`	Indicates if the account is an organization level account — `true` — or account level — `false`.
`type`	Indicates the type of account, either account level — `CompanyAccount` — or organization level — `Default`.

Add an Account

Add accounts with the POST /accounts endpoint.

Add Account JSON Body

{
  "name": "Account Name",
  "description": "Short description of the account",
  "externalId": "companyemail@company.com"
}

Required

externalId

Note: If you create an account using only externalId, the name and description will be whatever value you provide for externalId.

Add Account Example Request

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2/accounts \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \
  -d '{
  "name": "Account For Docs",
  "description": "This account is used to demonstrate a POST /instances request",
  "externalId": "notsorandomId"
}
'

Add Account Example Response

{
    "id": 4030,
    "name": "Account For Docs",
    "description": "This account is used to demonstrate a POST /instances request",
    "active": true,
    "companyId": 819,
    "externalId": "notsorandomId",
    "defaultAccount": false,
    "type": "CompanyAccount"
}

See Account Attributes for descriptions of each attribute.

Add Users to Accounts

Add users to accounts with the account id and the POST /accounts/{accountId}/users endpoint.

After you create a user, they do not receive any notification. This is because many users do not need to access Cloud Elements directly. If the new user needs to access Cloud Elements, either provide them with the password that you entered or encourage them to reset their password.

Add Users Parameters

Name	Description	Required
id	The unique identifier for an account within an organization. Use in any `/accounts` endpoint with an {id} variable.	Y

To get a list of accounts including ids see Find Accounts.

Add Users JSON Body

{
  "firstName": "User's First Name",
  "lastName": "User's Last Name",
  "email": "useremail@company.com",
  "password": "password"
}

Required

firstName
lastName
email
password

You can also include the following optional attributes to provide more details about the user. The attributes do not appear in Cloud Elements:

{
  "city": "string",
  "country": "string",
  "phone": "string",
  "postalCode": "string",
  "stateProvince": "string",
  "street1": "string",
  "street2": "string",
  "roles":[
        {
        "key": "role key either admin or org-admin"
      }
    ]
}

Add Users Example Request

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2/accounts/4022/users \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \
  -d '{
  "firstName": "First",
  "lastName": "Last",
  "email": "FirstLast@company.com",
  "password": "password",
  "roles":[
      {
      "key": "admin"
    }
  ]
}'

Add Users Example Response

{
    "id": 4022,
    "createdDate": "2017-07-12",
    "firstName": "First",
    "email": "FirstLast@company.com",
    "active": true,
    "lastName": "Last",
    "accountExpired": false,
    "accountLocked": false,
    "credentialsExpired": false,
    "roles": [
      {
            "id": 3,
            "name": "Administrator",
            "key": "admin",
            "active": true,
            "description": "Cloud Elements Application Administrator.",
            "features": []
        },
        {
            "id": 2717,
            "name": "Organization User",
            "key": "org",
            "active": true,
            "description": "Organization User",
            "features": []
        }
    ],
    "secret": "pgJTa2A3Lxr/7o/fN7NlRb1ATrgc4JlXVKFq7HpcF74=",
    "lastLoginDate": "1970-01-01",
    "emailValid": true,
    "accountNonExpired": true,
    "credentialsNonExpired": true,
    "accountNonLocked": true,
    "enabled": true,
    "fullName": "First Last"
}

See User Attributes for descriptions of each attribute.

Get a Specific Account

Access a specific account with the account id and the GET /accounts/{id} endpoint.

Get Account Parameters

Name	Description	Required
id	The unique identifier for an account within an organization. Use in any `/accounts` endpoint with an {id} variable.	Y

To get a list of accounts including ids see [Find Accounts.

Get Account Example Request

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2/accounts/4022 \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \

Get Account Example Response

  {
    "id": 4030,
    "name": "Account For Docs",
    "description": "This account is used to demonstrate a POST /instances request",
    "active": true,
    "companyId": 819,
    "createdDate": "2017-07-10",
    "externalId": "notsorandomId",
    "defaultAccount": false,
    "type": "CompanyAccount"
}

See Account Attributes for descriptions of each attribute.

Update an Account

Change the name, description, or externalId of a specific account with the account id and the PATCH /accounts/{id} endpoint.

Update Account Parameters

Name	Description	Required
id	The unique identifier for an account within an organization. Use in any `/accounts` endpoint with an {id} variable.	Y

To get a list of accounts including ids see [Find Accounts.

Update Account Example Request

curl -X PATCH \
  https://api.cloud-elements.com/elements/api-v2/accounts/4022 \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \
  -d '{
  "name": "Updated Account",
  "description": "This account is used to demonstrate a PATCH /instances request",
  "externalId": "newRandomId"
}
'

Update Account Example Response

  {
    "id": 4022,
    "name": "Updated Account",
    "description": "This account is used to demonstrate a PATCH /instances request",
    "active": true,
    "companyId": 819,
    "createdDate": "2017-07-10",
    "externalId": "newRandomId",
    "defaultAccount": false,
    "type": "CompanyAccount"
  }

See Account Attributes for descriptions of each attribute.

Get a List of Account Users

You can retrieve a list of users associated with an account with the account id and the GET /accounts/{id}/users endpoint.

Account Users Parameters

Name	Description	Required
id	The unique identifier for an account within an organization. Use in any `/accounts` endpoint with an {id} variable.	Y

To get a list of accounts including ids see [Find Accounts.

Account Users Example Request

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2/accounts/4046/users \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \

Account Users Example Response

[
    {
        "id": 3805,
        "createdDate": "2017-07-10",
        "firstName": "Neta",
        "password": "secured",
        "email": "Alfaro@mycompany.com",
        "active": false,
        "lastName": "Alfaro",
        "accountExpired": false,
        "accountLocked": false,
        "credentialsExpired": true,
        "lastLoginDate": "2017-07-10",
        "emailValid": true,
        "accountNonExpired": false,
        "credentialsNonExpired": false,
        "accountNonLocked": true,
        "enabled": false,
        "fullName": "Neta   Alfaro"
    }
]

See User Attributes for descriptions of each attribute.

Deactivate and Reactivate an Account

You can deactivate an account or activate an already deactivated account with the account id and the PATCH /accounts/{id} endpoint. Deactivating an account essentially performs the same action as deleting an account. After you deactivate an account, you cannot view it in Cloud Elements 2.0. You can still find the account using the Cloud Elements APIs. Use the account id with /accounts endpoints that use the {id} variable.

Deactivate and Reactivate Account Parameters

Name	Description	Required
id	The unique identifier for an account within an organization. Use in any `/accounts` endpoint with an {id} variable.	Y

To get a list of accounts including ids see [Find Accounts.

Deactivate Account Example Request

curl -X PATCH \
  https://api.cloud-elements.com/elements/api-v2/accounts/4022 \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \
  -d '{
  "active": false
}
'

To reactivate a deactivated account, set active to true.

Deactivate and Reactivate Account Example Response

  {
    "id": 4022,
    "name": "Updated Account",
    "description": "This account is used to demonstrate a PATCH /instances request",
    "active": false,
    "companyId": 819,
    "createdDate": "2017-07-10",
    "externalId": "newRandomId",
    "defaultAccount": false,
    "type": "CompanyAccount"
  }

If you reactivate an account, active is set to true in the response.

See Account Attributes for descriptions of each attribute.

Delete an Account

Delete an account from your organization with the account id and the DELETE /accounts/{id} endpoint. Deleting an account essentially performs the same action as deactivating an account. You can recover a deleted account by reactivating it. The account will not appear in Cloud Elements 2.0 and is not retrieved by GET /accounts. You can still find the account using the account id with /accounts endpoints that use the {id} variable.

Warning: Do not delete the default organization-level account. Doing so will prevent you from logging in to Cloud Elements or making API requests.

If you delete an account that also has users associated with it, the account deletion deactivates the users. If you reactivate the account and want to keep the same users, you must reactivate them separately.

To check for any users of the account, use GET /accounts/{id}/users. If you receive a status of 404 Not Found with the response body below, the account has no users and you can delete it.

{
    "requestId": "59664ce6e4b0bbce0a2bd24f",
    "message": "No users found"
}

Delete Account Parameters

Name	Description	Required
id	The unique identifier for an account within an organization. Use in any `/accounts` endpoint with an {id} variable.	Y

To get a list of accounts including ids see [Find Accounts.

Delete Account Example Request

curl -X DELETE \
  https://api.cloud-elements.com/elements/api-v2/accounts/4031 \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \

Delete Account Example Response

The response is empty. You can confirm that you deleted the account with GET /accounts/{id}. In the response, active is set to false.