REST API:tenant Resource

Performs actions on Tenant records via the REST API

Access Permissions

Users that have the Manage Tenants and Company Capabilities permission can use this REST API resource.

Retrieve the metadata for a Tenant

Retrieves metadata for a Tenant via the REST API

Method: GET
URI: https://{yourDomain}/networking/rest/tenant/{tenant_id}

Response

<platform>
    <tenant>
        <id>1479765335</id>
        <object_id>8c5b349851c041a28d19277a12dee8f0</object_id>
        <document_space/>
        <classification/>
        <trial_days/>
        <deleted/>
        <created_id type="" 
            uri="https://{{domain}}/networking/rest/record/USER/1" 
            displayValue="">1</created_id>
        <owner_id type="" 
            uri="https://{{domain}}/networking/rest/record/USER/5" 
            displayValue="Admin">5</owner_id>
        <modified_id type="" 
            uri="https://{{domain}}/networking/rest/record/USER/5" 
            displayValue="Admin">5</modified_id>
        <number>1742261497</number>
        <name/>
        <search_string/>
        <start_date>2010-11-12T13:14:15Z</start_date>
        <payment_type/>
        <license_blocks/>
        <country>United States</country>
        <next_billing_date/>
        <base_subscriber_plan type="" 
            uri="https://{{domain}}/networking/rest/record/456zzy789jhk/null" 
            displayValue=""/>
        <trial_account/>
        <accessory_purchase_plan type="" 
            uri="https://{{domain}}/networking/rest/record/456zzy789jhk/null" 
            displayValue=""/>
        <workflow_owners/>
        <data_space/>
        <date_modified>2010-11-12T13:14:15Z</date_modified>
        <company>Greene Services</company>
        <base_subscriber_option type="" 
            uri="https://{{domain}}/networking/rest/record/456zzy789jhk/null" 
            displayValue=""/>
        <discount/>
        <workflow_state/>
        <active>1</active>
    </tenant>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Create a Tenant

Creates a new Tenant

Method: POST
URI: https://{yourDomain}/networking/rest/tenant

Note: If you want to create a sub-domain tenant, pass the <service_portal_sub_domain> tag in the payload. For example for a sub-domain name "mydomain", pass the tag as <service_portal_sub_domain>mydomain</service_portal_sub_domain>.

Request

<platform>
    <tenant>
        <company>BSmith Inc</company>
        <name>BSmith Inc</name>
        <email>bsmith@email.com</email>
        <last_name>Bob</last_name>
        <password>password</password>
        <first_name>Smith</first_name>
        <phone>650-555-1212</phone>
        <number_of_users>1</number_of_users>
        <country>United States</country>
        <date_format>mm/dd/yyyy</date_format>
        <time_zone>12</time_zone>
        <street>1230 Midas Way</street>
        <city>Sunnyvale</city>
        <force_password_to_be_changed>0</force_password_to_be_changed>
    </tenant>
</platform>

To preload the new tenant's applications (overriding the list specified in the Service Provider Settings, Tenant Configuration section), add a comma-separated list of package IDs like the following:

<appList>4949678694fe4ccd9dcdfd9c32c49521,
         eodf3997d57d4c7bb57f28d4e58d364f</appList>

where:

Whitespace between the values is ignored
The values are package installation IDs -- the values that appear as the id value in the Installation Link part of the Package page.

To get the ServiceDesk application and ServiceDesk tenant capabilities, pass the following flag with the request parameters:

<isCaseDynamics>1</isCaseDynamics>

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>      
        <id>...</id>  <!-- tenant ID -->  
    </message>
</platform>

See also: REST API:Error Codes

Search Tenants

Method

GET

URI

https://{yourDomain}/networking/rest/tenant?{query_parameters}

Sample Search: ?fieldList=name,id&filter=name contains 'smith' & sortby='id'; (Field names are in the Fields section.)

Query Parameters

fieldList - A comma-separated list of field names to retrieve

The asterisk (*) wildcard specifies all fields
{fieldname} specifies an individual field (e.g. name)

(Use the REST API:field Resource to get a complete list of fields.)

For a Composite Object, specify {alias}.{fieldname} to select a related-record field, where the alias is defined in the Object Relationships.
For a Database View, specify {alias}.{fieldname}, where the object alias is defined in the Database View.
alias.* specifies all fields in the aliased object.

filter - Filtering criteria to filter the records

For more examples, see Filter Expressions in REST APIs and the REST API Examples.)

pageSize - Number of records to retrieve from the result set in order to make a "page".
page - Number of the logical page in a database result set. The first page is page "zero" (0).

Page zero is returned by default, so appending &pageSize=1 to your query returns a single record.

getTotalRecordCount returns the number of total records.
Causes the following structure to be returned, where N is the total number of records:

<platform> 
   <status>
   <packageDeploy>
   ...
   </packageDeploy>
   </status>
   <message>
      <code>0</code>
      <description>Success</description>
   </message>

   <!-- added by the query param -->
   <totalRecordCount>N</totalRecordCount> 
</platform>

sortBy - Field name for primary sort
Ex: &sortBy=name
sortOrder - Sort order of the primary field, either asc or desc (ascending or descending)
Ex: &sortOrder=desc
sortBy2 - Field name for secondary sort
sortOrder2 - Sort order of the second field, either asc or desc (ascending or descending)

For more information, see: Specifying Query Parameters in REST APIs

Update a Tenant

Updates Tenant information

Method: PUT
URI: https://{yourDomain}/networking/rest/tenant/{tenant_id}

Request

<platform>
<tenant>
    <free>1</free>
    <country>India</country>
    <payment_type>Manual</payment_type>
</tenant>
</platform>

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>        
    </message>
</platform>

See also: REST API:Error Codes

Delete a Tenant

Deletes a Tenant, and all related information

Method: DELETE
URI: https://{yourDomain}/networking/rest/tenant/{tenant_id}

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>        
    </message>
</platform>

See also: REST API:Error Codes

Fields

Name	Type	Attributes	Description	Additional Information
company	String		Company Name
service_portal_sub_domain	String		Sub-domain Name	In Configure Service Settings, if Enable Tenant SubDomains is not enabled under Tenant Configuration, then even if this value is passed during tenant creation, it is not taken into consideration. For more information see, [Prefix for Service Domain].
email	email		Email address of the User
first_name	String		User First Name
last_name	String		User Last Name
password	String		Password
time_zone	int		Time zone ID	Time Zone Codes
date_format	String			Date Format
phone	String		User Phone
number_of_users	int		Number Of Users
document_space	int		per User document space
object_id	String	Read Only	tenant object id	Default: 8c5b349851c041a28d19277a12dee8f0
number	int	Read Only	Tenant Number
deleted	Boolean	Read Only	Designates if the Tenant is active or not
discount	percentage		Discount for the tenant
created_id	String	Read Only
data_space	int		per user data space
classification	String		Customer classification
owner_id	String	Read Only
start_date	date	Read Only	registration date	UTC Format
country	String
city	String
state	String
sendWelcomeEmail	Boolean		Sends a welcome email when set to 1	Default: 0
force_password_change_on_login	Boolean		Prompts for password reset on first login when set to 1	Default: 1
street	String
zip	String
base_subscriber_plan	Lookup		Tenant's purchase plan	URI attribute contains record URL
base_subscriber_option	Lookup		Tenant's payment plan	URI attribute contains record URL
accessory_purchase_plan	Lookup		Tenant's plan for purchasing additional usage-resources.	URI attribute contains record URL

Search

where to start

Feedback

customize and design

resources

Tools

Personal tools

REST API:tenant Resource

Contents

Access Permissions

Retrieve the metadata for a Tenant

Create a Tenant

Search Tenants

Update a Tenant

Delete a Tenant

Fields