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

<syntaxhighlight lang="xml" enclose="div">

<platform>

   <tenant>
       <id>1479765335</id>
       <object_id>8c5b349851c041a28d19277a12dee8f0</object_id>
       <document_space/>
       <classification/>
       <trial_days/>
       <deleted/>
       <created_id type="" 
           uri="https://{yourDomain}/networking/rest/record/USER/1" 
           displayValue="">1</created_id>
       <owner_id type="" 
           uri="https://{yourDomain}/networking/rest/record/USER/5" 
           displayValue="Admin">5</owner_id>
       <modified_id type="" 
           uri="https://{yourDomain}/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://{yourDomain}/networking/rest/record/456zzy789jhk/null" 
           displayValue=""/>
       <trial_account/>
       <accessory_purchase_plan type="" 
           uri="https://{yourDomain}/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://{yourDomain}/networking/rest/record/456zzy789jhk/null" 
           displayValue=""/>
       <discount/>
       <workflow_state/>
       <active>1</active>
   </tenant>
   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

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

<syntaxhighlight lang="xml" enclose="div">

<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> </syntaxhighlight>

• 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:

<syntaxhighlight lang="xml" enclose="div">

<appList>4949678694fe4ccd9dcdfd9c32c49521,

        eodf3997d57d4c7bb57f28d4e58d364f</appList> 

</syntaxhighlight>

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:

<syntaxhighlight lang="xml" enclose="div">

<isCaseDynamics>1</isCaseDynamics> </syntaxhighlight>

Response

<syntaxhighlight lang="xml" enclose="div">

<platform>

   <message>
       0
       <description>Success</description>      
       <id>...</id>    
   </message>

</platform> </syntaxhighlight>

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:

<syntaxhighlight lang="xml" enclose="div">

<platform>

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

  <totalRecordCount>N</totalRecordCount> 

</platform> </syntaxhighlight>

• 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

<syntaxhighlight lang="xml" enclose="div">

<platform> <tenant>

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

</tenant> </platform> </syntaxhighlight>

Response

<syntaxhighlight lang="xml" enclose="div"> <platform>

   <message>
       0
       <description>Success</description>        
   </message>

</platform> </syntaxhighlight>

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

<syntaxhighlight lang="xml" enclose="div">

<platform>

   <message>
       0
       <description>Success</description>        
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Fields

Name	Type	Attributes	Required During Add	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