Back to top

API Introduction

Below you will find a current list of the available methods on our CenturyLink Cloud API. If you need help or support, please head over to our Knowledge Base or Getting Started pages.

The calling conventions for the REST API is to send a POST request to the URL of the given method (e.g. https://api.ctl.io/REST/VirtualServer/CreateServer/FORMAT where FORMAT is either XML or JSON). In addition, the content type of the HTTP request must be set as well to either text/xml for XML requests, or application/json; charset=utf-8 for JSON requests. The combination of the format node and the Content Type will determine how the request is interpreted as well as control what format the responses are returned.

The SOAP based API supports the same features as the REST API, and while the request and response messages are essentially identical to those of the REST API, you will want to pull down the WSDL for each API to verify the details. URL's to each API's SOAP WSDL can be found on the individual API pages.

All requests will receive a response (in either JSON or XML format) with at least the following three attributes:

Attributes

Name Type Description Req.
ParentAlias String Account alias of the parent account Yes
AccountAlias String New, four character account alias. If left empty, one is automatically generated No
Location String Account alias of the parent account Yes

Many API calls will also return additional information which will be described in detail.

Authentication Overview

Authentication for the Public API will be handled differently than the CenturyLink Cloud Control System, To create an API user you must access the Control Portal and create an API user here. The credentials for the API consist of a string based API key and a password.

Prior to calling into the API, consumers must first call into the Authentication API to Logon. On successful login, the API will write a persistent cookie as part of its response. The encrypted cookie will be evaluated as part of each subsequent request, this will prevent the need of providing credentials with each API call.

The URL to the SOAP version of the Authentication API can be found at https://api.ctl.io/soap/auth.asmx and the WSDL can be found here.

For a complete walkthrough of the authentication process with the REST/HTTP API, see Using the HTTP API to Log In and Query Servers.

Authentication API Methods

This method is required to be called prior to calling any other method exposed by the CenturyLink Cloud API. This method validates your credentials and writes the Encrypted cookie required to be present for all subsequent calls into the API.

URL

REST: https://api.ctl.io/REST/Auth/Logon/

Request

Attributes

Name Type Description Req.
APIKey String The API access key provided by CenturyLink Cloud. Yes
Password String The API password provided by CenturyLink Cloud. Yes

Examples

XML

<LogonRequest>
  <APIKey>apikey</APIKey>
  <Password>password</Password>
</LogonRequest>

JSON

{
  "APIKey":"apikey",
  "Password":"password"
}

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.

Examples

XML

<LogonResponse Success="true" Message="Login Successful" StatusCode="0" />

JSON

{
  "Success":true,
  "Message":"Login Successful",
  "StatusCode":0
}

Status Codes

Status Code Description
0 Logon was successful
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
100 Authentication Failed - The APIKey & Password combination were not valid. Verify that the values provided in your message match the values given to you by CenturyLink Cloud.

Logout

This method will log you out of the API. The Logon method must be called again prior to accessing the API again.

URL

REST: https://api.ctl.io/REST/Auth/Logout/

Request

Attributes

None Required.

Status Codes

Status Code Description
0 Logout was successful

CreateAccount

Create a brand new (sub) account in the system. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/Account/CreateAccount/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Account.asmx?op=CreateAccount

Request

Attributes

Name Type Description Req.
ParentAlias String Account alias of the parent account. Yes
AccountAlias String New, four character account alias. If left empty, one is automatically generated. No
Location String Location alias of the primary data center for this account. Yes
BusinessName String Long form business name associated with the account. Yes
Address1 String Street address associated with the account. Yes
Address2 String Secondary street address associated with the account. No
City String City associated with the account. Yes
StateProvince String State or province associated with the account. Yes
PostalCode String Postal code associated with the account. Yes
Country String Country associated with the account. Yes
Telephone String Telephone number associated with the account. Yes
Fax String Fax number associated with the account. No
TimeZone String Timezone of the account holder. Timezone must be one of the values in the list below, otherwise the value is set to the parent account's Timezone. No
ShareParentNetworks Boolean Determines whether this account shares the networks of the parent account. Yes
BillingResponsibilityID Integer Determines the recipient of the bill.
1 = Account Directly
2 = Parent Account
Yes

Examples

JSON (REST)

{
  "ParentAlias":"1000",
  "AccountAlias":"1001",
  "Location":"WA1",
  "BusinessName":"Demo Biz",
  "Address1":"110 110th Avenue",
  "Address2":null,
  "City":"Bellevue",
  "StateProvince":"WA",
  "PostalCode":"98004",
  "Country":"USA",
  "Telephone":"877-388-4373",
  "Fax":null,
  "TimeZone":"Pacific Standard Time",
  "ShareParentNetworks":"true",
  "BillingResponsibilityID":"2"
}

XML (REST)

<CreateAccountRequest>
  <ParentAlias>1000</ParentAlias>
  <AccountAlias>1001</AccountAlias>
  <Location>QA1</Location>
  <BusinessName>Demo Biz</BusinessName>
  <Address1>110 110th Avenue</Address1>
  <Address2>Suite 520</Address2>
  <City>Bellevue</City>
  <StateProvince>WA</StateProvince>
  <PostalCode>98004</PostalCode>
  <Country>USA</Country>
  <Telephone>877-388-4373</Telephone>
  <Fax></Fax>
  <TimeZone>Pacific Standard Time</TimeZone>
  <ShareParentNetworks>true</ShareParentNetworks>
  <BillingResponsibilityID>2</BillingResponsibilityID>
</CreateAccountRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <CreateAccount xmlns="http://www.tier3.com/">
      <request>
        <ParentAlias>1000</ParentAlias>
        <AccountAlias>1001</AccountAlias>
        <Location>WA</Location>
        <BusinessName>Demo Biz</BusinessName>
        <Address1>110 110th Avenue</Address1>
        <Address2>Suite 520</Address2>
        <City>Bellevue</City>
        <StateProvince>WA</StateProvince>
        <PostalCode>98004</PostalCode>
        <Country>USA</Country>
        <Telephone>877-388-4373</Telephone>
        <Fax></Fax>
        <TimeZone>Pacific Standard Time</TimeZone>
        <ShareParentNetworks>true</ShareParentNetworks>
        <BillingResponsibilityID>2</BillingResponsibilityID>
      </request>
    </CreateAccount>
  </soap12:Body>
</soap12:Envelope>  

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
AccountDetails Complex (see below) The account details

AccountDetails Attributes

Name Type Description
AccountAlias String Short name associated with the account.
ParentAlias String Short name associated with parent account of the queried account.
Location String Data center location alias associated with this account.
BusinessName String Full name of the business that the account is registered under.
Address1 String Street address of the business associated with this account.
Address2 String Secondary street address (if any) of the business associated with this account.
City String City of the business associated with this account.
StateProvince String State or province of the business associated with this account.
PostalCode String Postal code of the business associated with this account.
Country String Country of the business associated with this account.
Telephone String Telephone number of the business associated with this account.
Fax String Fax number (if any) of the business associated with this account.
TimeZone String Time zone of the business associated with this account.
Status Int Indicator of whether the account is active or not.

Active = 1
Inactive = 0
ShareParentNetworks Boolean True/false flag indicating whether this account shares the networks of its parent.

Examples

JSON (REST)

{
  "AccountDetails": {
    "AccountAlias":"1001",
    "ParentAlias":"1000",
    "Location":"WA1",
    "BusinessName":"Demo Biz",
    "Address1":"110 110th Avenue",
    "Address2":null,
    "City":"Bellevue",
    "StateProvince":"WA",
    "PostalCode":"98004",
    "Country":"USA",
    "Telephone":"877-388-4373",
    "Fax":null,
    "TimeZone":"Pacific Standard Time",
    "Status":1,
    "ShareParentNetworks":true
  },  
  "Success":true,
  "Message":"Account successfully created.",
  "StatusCode":0
}

XML (REST)

<AccountDetailsResponse Success="true" Message="Account successfully created." StatusCode="0">
  <AccountDetails AccountAlias="1001" ParentAlias="1000" Location="WA1" TimeZone="Pacific Standard Time" Status="1" ShareParentNetworks="true">
    <BusinessName>Demo Biz</BusinessName>
    <Address1>110 110th Avenue</Address1>
    <Address2>Suite 520</Address2>
    <City>Bellevue</City>
    <StateProvince>WA</StateProvince>
    <PostalCode>98004</PostalCode>
    <Country>USA</Country>
    <Telephone>877-388-4373</Telephone>
    <Fax />
  </AccountDetails>
</AccountDetailsResponse>

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <CreateAccountResponse xmlns="http://www.tier3.com/">
      <CreateAccountResult Success="true" Message="Account successfully created." StatusCode="0">
        <AccountDetails AccountAlias="1001" ParentAlias="1000" Location="WA1" TimeZone="Pacific Standard Time" Status="1" ShareParentNetworks="true">
          <BusinessName>Demo Biz</BusinessName>
          <Address1>110 110th Avenue</Address1>
          <Address2>Suite 520</Address2>
          <City>Bellevue</City>
          <StateProvince>WA</StateProvince>
          <PostalCode>98004</PostalCode>
          <Country>USA</Country>
          <Telephone>877-388-4373</Telephone>
          <Fax />
        </AccountDetails>
      </CreateAccountResult>
    </CreateAccountResponse>
  </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
5 Resource Not Found. Provided account alias does not exist.
100 Authentication Failed. You must logon to the API prior to calling this method.
1600 Account Alias Required. You must provide an account alias when calling this method.
1601 Address Required. You must provide a primary address when calling this method.
1602 Business Name Required. You must provide a business name when calling this method.
1603 City Required. You must provide a city name when calling this method.
1604 Country Required. You must provide a country name when calling this method.
1605 Postal Code Required. You must provide a postal code when calling this method.
1606 State Province Required. You must provide a state or province name when calling this method.
1607 Telephone Required. You must provide a telephone number when calling this method.
1608 TimeZone Required. You must provide a timezone value when calling this method.
1609 Parent Alias Required. You must provide a parent alias when calling this method.
1610 Postal Code Required. You must provide a primary location when calling this method.
1611 Duplicate Account. You must provide a unique alias and business name when calling this method.
1613 Email Address Required. You must provide an email address when calling this method.
1616 Invalid Billing Responsibility. You must provide valid billing responsibilty when calling this method.
1610 Postal Code Required. You must provide a primary location when calling this method.

Valid Timezone Entries

  • Dateline Standard Time
  • UTC-11
  • Hawaiian Standard Time
  • Alaskan Standard Time
  • Pacific Standard Time (Mexico)
  • Pacific Standard Time
  • US Mountain Standard Time
  • Mountain Standard Time (Mexico)
  • Mountain Standard Time
  • Central America Standard Time
  • Central Standard Time
  • Central Standard Time(Mexico)
  • Canada Central Standard Time
  • SA Pacific Standard Time
  • Eastern Standard Time
  • US Eastern Standard Time
  • Venezuela Standard Time
  • Paraguay Standard Time
  • Atlantic Standard Time
  • Central Brazilian Standard Time
  • SA Western Standard Time
  • Pacific SA Standard Time
  • Newfoundland Standard Time
  • E. South America Standard Time
  • Argentina Standard Time
  • SA Eastern Standard Time
  • Greenland Standard Time
  • Montevideo Standard Time
  • Bahia Standard Time
  • UTC-02
  • Mid-Atlantic Standard Time
  • Azores Standard Time
  • Cape Verde Standard Time
  • Morocco Standard Time
  • UTC
  • GMT Standard Time
  • Greenwich Standard Time
  • W. Europe Standard Time
  • Central Europe Standard Time
  • Romance Standard Time
  • Central European Standard Time
  • W. Central Africa Standard Time
  • Namibia Standard Time
  • Jordan Standard Time
  • GTB Standard Time
  • Middle East Standard Time
  • Egypt Standard Time
  • Syria Standard Time
  • South Africa Standard Time
  • FLE Standard Time
  • Turkey Standard Time
  • Israel Standard Time
  • E. Europe Standard Time
  • Arabic Standard Time
  • Kaliningrad Standard Time
  • Arab Standard Time
  • E. Africa Standard Time
  • Iran Standard Time
  • Arabian Standard Time
  • Azerbaijan Standard Time
  • Russian Standard Time
  • Mauritius Standard Time
  • Georgian Standard Time
  • Caucasus Standard Time
  • Afghanistan Standard Time
  • Pakistan Standard Time
  • West Asia Standard Time
  • India Standard Time
  • Sri Lanka Standard Time
  • Nepal Standard Time
  • Central Asia Standard Time
  • Bangladesh Standard Time
  • Ekaterinburg Standard Time
  • Myanmar Standard Time
  • SE Asia Standard Time
  • N. Central Asia Standard Time
  • China Standard Time
  • North Asia Standard Time
  • Singapore Standard Time
  • W. Australia Standard Time
  • Taipei Standard Time
  • Ulaanbaatar Standard Time
  • North Asia East Standard Time
  • Tokyo Standard Time
  • Korea Standard Time
  • Cen. Australia Standard Time
  • AUS Central Standard Time
  • E. Australia Standard Time
  • AUS Eastern Standard Time
  • West Pacific Standard Time
  • Tasmania Standard Time
  • Yakutsk Standard Time
  • Central Pacific Standard Time
  • Vladivostok Standard Time
  • New Zealand Standard Time
  • UTC+12
  • Fiji Standard Time
  • Magadan Standard Time
  • Kamchatka Standard Time
  • Tonga Standard Time
  • Samoa Standard Time

Enable Account

Enable a suspended account in the system. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/Account/EnableAccount/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Account.asmx?op=EnableAccount

Request

Attributes

Name Type Description Req.
AccountAlias String Account alias. Yes

Examples

JSON (REST)

{
  "AccountAlias": "ACCT"
}

XML (REST)

<AccountStatusRequest>
  <AccountAlias>ACCT</AccountAlias>
</AccountStatusRequest>

XML (SOAP)

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <EnableAccount xmlns="http://www.tier3.com/">
      <request>
        <AccountAlias>ACCT</AccountAlias>
      </request>
    </EnableAccount>
  </soap:Body>
</soap:Envelope>  

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request.Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON (REST)

{
  "Success": true,
  "Message": "Account Enabled.",
  "StatusCode": 0,
  "RequestID": 100
}

XML (REST)

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
      <EnableAccountResponse xmlns="http://www.tier3.com/">
          <QueuedItemResponse Success="true" Message="Account Enabled." StatusCode="0">
            <ResponseID>100</ResponseID>
          </QueuedItemResponse>
      </EnableAccountResponse>
  </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
5 Resource Not Found. Provided account alias does not exist.
100 Authentication Failed. You must logon to the API prior to calling this method.
1600 Account Alias Required. You must provide an account alias when calling this method.

GetAccountDetails

Gets all of the contact information and settings for a given account. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/Account/GetAccountDetails/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Account.asmx?op=GetAccountDetails

Request

Attributes

Name Type Description Req.
AccountAlias String Short code for a particular account. Yes

Examples

JSON (REST)

{

  "AccountAlias": "1000"

}

XML (REST)

<GetAccountDetailsRequest>
    <AccountAlias>1000</AccountAlias>
</GetAccountDetailsRequest>

XML (SOAP)

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetAccountDetails xmlns="http://www.tier3.com/">
      <request>
         <AccountAlias>1000</AccountAlias>
      </request>
    </GetAccountDetails>
  </soap:Body>
</soap:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
AccountDetails Complex The account details

AccountDetails Attributes

Name Type Description
AccountAlias String Short name associated with the account.
ParentAlias String Short name associated with parent account of the queried account.
Location String Data center location alias associated with this account.
BusinessName String Full name of the business that the account is registered under.
Address1 String Street address of the business associated with this account.
Address2 String Secondary street address (if any) of the business associated with this account.
City String City of the business associated with this account.
StateProvince String State or province of the business associated with this account.
PostalCode String Postal code of the business associated with this account.
Country String Country of the business associated with this account.
Telephone String Telephone number of the business associated with this account.
Fax String Fax number (if any) of the business associated with this account.
TimeZone String Time zone of the business associated with this account.
Status Int Indicator of whether the account is active or not.
Active = 1,
Disabled = 2,
Deleted = 3,
Demo = 4
ShareParentNetworks Boolean True/false flag indicating whether this account shares the networks of its parent.
SupportLevel String Indicator of support level for the account.
developer,
legacy,
professional,
enterprise

Examples

JSON (REST)

{
  "AccountDetails": {
    "AccountAlias":"1001",
    "ParentAlias":"1000",
    "Location":"WA1",
    "BusinessName":"Example Business Name",
    "Address1":"110 110th Avenue",
    "Address2":null,
    "City":"Bellevue",
    "StateProvince":"WA",
    "PostalCode":"98004",
    "Country":"USA",
    "Telephone":"877-388-4373",
    "Fax":null,
    "TimeZone":"Pacific Standard Time",
    "Status":2,
    "ShareParentNetworks":true
  },
  "Success":true,
  "Message":"Account details successfully queried.",
  "StatusCode":0
}

XML (REST)

<AccountDetailsResponse Success="true" Message="Account details successfully queried." StatusCode="0">
    <AccountDetails AccountAlias="1001" ParentAlias="1000" Location="WA1" TimeZone="Pacific Standard Time" Status="2" ShareParentNetworks="true">
        <BusinessName>Example Business Name</BusinessName>
        <Address1>110 110th Avenue</Address1>
        <City>Bellevue</City>
        <StateProvince>WA</StateProvince>
        <PostalCode>98004</PostalCode>
        <Country>USA</Country>
        <Telephone>877-388-4373</Telephone>
    </AccountDetails>
</AccountDetailsResponse>

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
     <soap:Body>
        <GetAccountDetailsResponse xmlns="http://www.tier3.com/">
            <GetAccountDetailsResult Success="true" Message="Account details successfully queried." StatusCode="0">
                <AccountDetails AccountAlias="1001" ParentAlias="1000" Location="WA1" TimeZone="Pacific Standard Time" Status="2" ShareParentNetworks="true">
                    <BusinessName>Example Business Name</BusinessName>
                    <Address1>110 110th Avenue</Address1>
                    <City>Bellevue</City>
                      <StateProvince>WA</StateProvince>
                    <PostalCode>98004</PostalCode>
                    <Country>USA</Country>
                    <Telephone>877-388-4373</Telephone>
                </AccountDetails>
            </GetAccountDetailsResult>
        </GetAccountDetailsResponse>
      </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
5 Resource Not Found. Provided account alias does not exist.
100 Authentication Failed. You must logon to the API prior to calling this method.
1600 Account Alias Required. You must provide an account alias when calling this method.

GetAccounts

Gets details of the API user's account and any sub-accounts. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/Account/GetAccounts/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Account.asmx?op=AccountsResponseMsg

Request

Attributes

None.

Examples

XML (SOAP)

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
    <AccountsResponseMsg xmlns="http://www.tier3.com/" />
</soap:Body>
</soap:Envelope>  

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Account[] Complex The list of accounts (see below).

Account Attributes

Name Type Description
AccountAlias String Short name associated with the account.
ParentAlias String Short name associated with the parent account.
Location String Data center alias (3 letters). List of data center alias is retrieved from GetLocations operation.
BusinessName String Full business name associated with the account.
IsActive Boolean True/False indicator of whether the account is active or not.
SupportLevel String Indicator of support level for the account.
developer,
legacy,
professional,
enterprise

Examples

JSON (REST)

{
  "Accounts":[
    {
      "AccountAlias":"1001",
      "ParentAlias":"1000",
      "Location":"WA1",
      "BusinessName":"Example Business Name",
      "IsActive":true
    },
    {
      "AccountAlias":"1002",
      "ParentAlias":"1001",
      "Location":"WA1",
      "BusinessName":"Example Department",
      "IsActive":true}
  ],
  "Success":true,
  "Message":"Accounts successfully queried.",
  "StatusCode":0
}

XML (REST)

<AccountsResponse Success="true" Message="Accounts successfully queried." StatusCode="0">
    <Accounts>
        <Account AccountAlias="1001" ParentAlias="1000" Location="WA1" BusinessName="ExampleBusiness Name" IsActive="true"/>
        <Account AccountAlias="1002" ParentAlias="1001" Location="WA1" BusinessName="Example Department" IsActive="true" />
    </Accounts>
</AccountsResponse>

XML (SOAP)

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
      <AccountsResponseMsgResponse xmlns="http://www.tier3.com/">
          <AccountsResponseMsgResult>
              <Accounts>
                  <Account AccountAlias="1001" ParentAlias="1000" Location="WA1" BusinessName="Example Business Name" IsActive="true" />
                  <Account AccountAlias="1002" ParentAlias="1001" Location="WA1" BusinessName="Example Department" IsActive="true" />
              </Accounts>
          </AccountsResponseMsgResult>
      </AccountsResponseMsgResponse>
  </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.

GetCustomFields

Gets the account custom field definitions.

URL

REST: https://api.ctl.io/REST/Account/GetCustomFields/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Account.asmx?op=GetCustomFields

Request

Attributes

Name Type Description Req.
AccountAlias String The Account Alias that has custom fields configured on it. Yes

Examples

JSON

{
  "AccountAlias": "ACCT"
}

XML

<GetCustomFieldsRequest>
    <AccountAlias>ACCT</AccountAlias>
</GetCustomFieldsRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
AccountCustomField Complex Account Custom Field complex object

AccountCustomField Attributes

Name Type Description
ID Int Deprecated. Value is -1. Use UUID instead.
UUID String Unique identifier of the Account Custom Field.
CustomFieldTypeID Int Deprecated. Value is -1. Use CustomFieldType instead.
CustomFieldType String The type of field: "Text", "Option", or "Checkbox".
Name String Friendly name of the Custom Field.
IsRequired Boolean Whether or not the Custom Field is required.
AccountCustomFieldOptions Complex Options for the Account Custom Field, specific to the field type.

Examples

JSON

{
  "AccountCustomFields": [
    {
      "ID": -1,
      "CustomFieldTypeID": -1,
      "CustomFieldType": "Text",
      "Name": "Name",
      "IsRequired": true,
      "UUID":"dba67b15-6e77-4e1f-b413-ddfa3dc4ac1d"
      "AccountCustomFieldOptions": null
    },
    {
      "ID": -1,
      "CustomFieldTypeID": -1,
      "CustomFieldType": "Option",
      "Name": "Type",
      "IsRequired": true,
      "UUID":"d61daab2-e99f-40c2-a4b5-820c3d97eea4"
      "AccountCustomFieldOptions": [
        {
          "Name": "My Type",
          "Value": "1"
        },
        {
          "Name": "Your Type",
          "Value": "2"
        }
      ]
    },
    {
      "ID": -1,
      "CustomFieldTypeID": -1,
      "CustomFieldType": "Checkbox",
      "Name": "Enabled",
      "IsRequired": true,
      "UUID": "de775088-8b94-4e9f-b64b-416623477cf8"
      "AccountCustomFieldOptions": []
    }
  ],
  "Success": true,
  "Message": "Custom Fields retrieved successfully.",
  "StatusCode": 0
}

XML

<AccountCustomFieldsResponse
  Success="true"
  Message="Custom Fields retrieved successfully."
  StatusCode="0">
    <AccountCustomFields>
        <AccountCustomField ID="-1" CustomFieldTypeID="-1" CustomFieldType="Text" Name="Name" UUID="dba67b15-6e77-4e1f-b413-ddfa3dc4ac1d" IsRequired="true" />
        <AccountCustomField ID="-1" CustomFieldTypeID="-1" CustomFieldType="Option" Name="Type" UUID="d61daab2-e99f-40c2-a4b5-820c3d97eea4" IsRequired="true">
            <AccountCustomFieldOptions Name="My Type" Value="1" />
            <AccountCustomFieldOptions Name="Your Type" Value="2" />
        </AccountCustomField>
        <AccountCustomField ID="-1" CustomFieldTypeID="-1" CustomFieldType="Checkbox" Name="Enabled" UUID="de775088-8b94-4e9f-b64b-416623477cf8" IsRequired="true" />
    </AccountCustomFields>
</AccountCustomFieldsResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
100 Authentication Failed. You must logon to the API prior to calling this method.

GetLocations

Gets list of all valid data center location codes that are used in subsequent Account operations. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/Account/GetLocations/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Account.asmx?op=LocationsResponseMsg

Request

Attributes

None

Examples

XML (SOAP)

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <LocationsResponseMsg xmlns="http://www.tier3.com/" />
  </soap:Body>
</soap:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Location[] Complex The list of locations (see below)

Location Attributes

Name Type Description
Alias String Short name associated with the data center. This is the value used as input to other Account operations.
Region String Full name, or friendly name, of the data center.

Examples

JSON (REST)

{
  "Locations":[
    {
      "Alias":"100",
      "Region":"Demo Region 1"
    },
    {
      "Alias":"101",
      "Region":"Demo Region 2"
    },
    {
      "Alias":"102",
      "Region":"Demo Region 3"
    }
  ],
  "Success":true,
  "Message":"Locations successfully queried.",
  "StatusCode":0
}

XML (REST)

<LocationsResponse Success="true" Message="Locations successfully queried." StatusCode="0">
    <Locations>
        <Location Alias="100" Region="Demo Region 1" />
        <Location Alias="101" Region="Demo Region 2" />
        <Location Alias="102" Region="Demo Region 3" />
    </Locations>
</LocationsResponse>

XML (SOAP)

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <LocationsResponseMsgResponse xmlns="http://www.tier3.com/">
      <LocationsResponseMsgResult>
        <Locations>
          <Location Alias="string" Region="string" />
          <Location Alias="string" Region="string" />
        </Locations>
      </LocationsResponseMsgResult>
    </LocationsResponseMsgResponse>
  </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.

SuspendAccount

Disable an existing account in the system. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/Account/SuspendAccount/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Account.asmx?op=SuspendAccount

Request

Attributes

Name Type Description Req.
AccountAlias String Four character account alias. Yes

Examples

JSON (REST)

{

  "AccountAlias": "1000"

}

XML (REST)

<AccountStatusRequest>
  <AccountAlias>1000</AccountAlias>
</AccountStatusRequest>

XML (SOAP

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <SuspendAccount xmlns="http://www.tier3.com/">
      <request>
         <AccountAlias>1000</AccountAlias>
      </request>
    </SuspendAccount>
  </soap:Body>
</soap:Envelope>  

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request.Status aof the request can be obtained by calling the Get Deployment Status method.

Examples

JSON (REST)

{
  "Success": true,
  "Message": "Account Suspended.",
  "StatusCode": 0,
  "RequestID": 100
}

XML (REST)

<QueuedItemResponse Success="true" Message="Account Suspended." StatusCode="0">
    <RequestID>100</RequestID>
</QueuedItemResponse>

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
      <SuspendAccountResponse xmlns="http://www.tier3.com/">
          <QueuedItemResponse Success="true" Message="Account Suspended." StatusCode="0">
              <ResponseID>100</ResponseID>
          </QueuedItemResponse>
      </SuspendAccountResponse>
  </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
5 Resource Not Found. Provided account alias does not exist.
100 Authentication Failed. You must logon to the API prior to calling this method.
1600 Account Alias Required. You must provide an account alias when calling this method.

UpdateAccountDetails

Make changes to an existing account in the system. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/Account/UpdateAccountDetails/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Account.asmx?op=UpdateAccountDetails

Request

Attributes

Name Type Description Req.
AccountAlias String Four character account alias. Yes
BusinessName String Long form business name associated with the account. Yes
Address1 String Street address associated with the account. Yes
Address2 String Secondary street address associated with the account. No
City String City associated with the account. Yes
StateProvince String State or province associated with the account. Yes
PostalCode String Postal code associated with the account. Yes
Country String Country associated with the account. Yes
Telephone String Telephone number associated with the account. Yes
Fax String Fax number associated with the account. No
TimeZone String Timezone of the account holder. Timezone must be one of the values in the list below, otherwise the value is set to the parent account's Timezone. Yes
ShareParentNetworks Boolean Determines whether this account shares the networks of the parent account. Yes

Examples

JSON (REST)

{
  "AccountAlias":"1001",
  "BusinessName":"Demo Biz",
  "Address1":"110 110th Avenue",
  "Address2":null,
  "City":"Bellevue",
  "StateProvince":"WA",
  "PostalCode":"98004",
  "Country":"USA",
  "Telephone":"877-388-4373",
  "Fax":null,
  "TimeZone":"Pacific Standard Time",
  "ShareParentNetworks":"true"
}

XML (REST)

<UpdateAccountDetailsRequest>
    <AccountAlias>1001</AccountAlias>
    <BusinessName>Demo Biz</BusinessName>
    <Address1>110 110th Avenue</Address1>
    <Address2>Suite 520</Address2>
    <City>Bellevue</City>
    <StateProvince>WA</StateProvince>
    <PostalCode>98004</PostalCode>
    <Country>USA</Country>
    <Telephone>877-388-4373</Telephone>
    <Fax></Fax>
    <TimeZone>Pacific Standard Time</TimeZone>
    <ShareParentNetworks>true</ShareParentNetworks>
</UpdateAccountDetailsRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <UpdateAccountDetails xmlns="http://www.tier3.com/">
            <request>
                <AccountAlias>1001</AccountAlias>
                <BusinessName>Demo Biz</BusinessName>
                <Address1>110 110th Avenue</Address1>
                <Address2>Suite 520</Address2>
                <City>Bellevue</City>
                <StateProvince>WA</StateProvince>
                <PostalCode>98004</PostalCode>
                <Country>USA</Country>
                <Telephone>877-388-4373</Telephone>
                <Fax></Fax>
                <TimeZone>Pacific Standard Time</TimeZone>
                <ShareParentNetworks>true</ShareParentNetworks>
            </request>
        </UpdateAccountDetails>
    </soap12:Body>
</soap12:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
AccountDetails Complex The account details

AccountDetails Attributes

Name Type Description
AccountAlias String Short name associated with the account.
ParentAlias String Short name associated with parent account of the queried account.
Location String Data center location alias associated with this account.
BusinessName String Full name of the business that the account is registered under.
Address1 String Street address of the business associated with this account.
Address2 String Secondary street address (if any) of the business associated with this account.
City String City of the business associated with this account.
StateProvince String State or province of the business associated with this account.
PostalCode String Postal code of the business associated with this account.
Country String Country of the business associated with this account.
Telephone String Telephone number of the business associated with this account.
Fax String Fax number (if any) of the business associated with this account.
TimeZone String Time zone of the business associated with this account.
Status Int Indicator of whether the account is active or not.
Active = 1
Inactive = 0
ShareParentNetworks Boolean True/false flag indicating whether this account shares the networks of its parent.

Examples

JSON (REST)

{
  "AccountDetails":{
    "AccountAlias":"1001",
    "ParentAlias":"1000",
    "Location":"WA1",
    "BusinessName":"Demo Biz"
    "Address1":"110 110th Avenue",
    "Address2":null,
    "City":"Bellevue",
    "StateProvince":"WA",
    "PostalCode":"98004",
    "Country":"USA",
    "Telephone":"877-388-4373",
    "Fax":null,
    "TimeZone":"Pacific Standard Time",
    "Status":1,
    "ShareParentNetworks":true
  },
  "Success":true,
  "Message":"Account details successfully updated.",
  "StatusCode":0
}

XML (REST)

<AccountDetailsResponse Success="true" Message="Account details successfully updated." StatusCode="0">
     <AccountDetails AccountAlias="1001" ParentAlias="1000" Location="WA1" TimeZone="Pacific Standard Time" Status="1" ShareParentNetworks="true">
         <BusinessName>Demo Biz</BusinessName>
         <Address1>110 110th Avenue</Address1>
         <Address2>Suite 520</Address2>
         <City>Bellevue</City>
         <StateProvince>WA</StateProvince>
         <PostalCode>98004</PostalCode>
         <Country>USA</Country>
         <Telephone>877-388-4373</Telephone>
         <Fax />
     </AccountDetails>
</AccountDetailsResponse>

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <UpdateAccountDetailsResponse xmlns="http://www.tier3.com/">
            <UpdateAccountDetailsResult Success="true" Message="Account details successfully updated." StatusCode="0">
                <AccountDetails AccountAlias="1001" ParentAlias="1000" Location="WA1" TimeZone="Pacific Standard Time" Status="1" ShareParentNetworks="true">
                    <BusinessName>Demo Biz</BusinessName>
                    <Address1>110 110th Avenue</Address1>
                    <Address2>Suite 520</Address2>
                    <City>Bellevue</City>
                    <StateProvince>WA</StateProvince>
                    <PostalCode>98004</PostalCode>
                    <Country>USA</Country>
                    <Telephone>877-388-4373</Telephone>
                    <Fax />
                </AccountDetails>
            </UpdateAccountDetailsResult>
        </UpdateAccountDetailsResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
5 Resource Not Found. Provided account alias does not exist.
100 Authentication Failed. You must logon to the API prior to calling this method.
1600 Account Alias Required. You must provide an account alias when calling this method.
1601 Address Required. You must provide a primary address when calling this method.
1602 Business Name Required. You must provide a business name when calling this method.
1603 City Required. You must provide a city name when calling this method.
1604 Country Required. You must provide a country name when calling this method.
1605 Postal Code Required. You must provide a postal code when calling this method.
1606 State Province Required. You must provide a state or province name when calling this method.
1607 Telephone Required. You must provide a telephone number when calling this method.
1608 TimeZone Required. You must provide a timezone value when calling this method.
1610 Postal Code Required. You must provide a primary location when calling this method.
1613 Email Address Required. You must provide an email address when calling this method.
1610 Postal Code Required. You must provide a primary location when calling this method.

Valid Timezone Entries

  • Dateline Standard Time
  • UTC-11
  • Hawaiian Standard Time
  • Alaskan Standard Time
  • Pacific Standard Time (Mexico)
  • Pacific Standard Time
  • US Mountain Standard Time
  • Mountain Standard Time (Mexico)
  • Mountain Standard Time
  • Central America Standard Time
  • Central Standard Time
  • Central Standard Time(Mexico)
  • Canada Central Standard Time
  • SA Pacific Standard Time
  • Eastern Standard Time
  • US Eastern Standard Time
  • Venezuela Standard Time
  • Paraguay Standard Time
  • Atlantic Standard Time
  • Central Brazilian Standard Time
  • SA Western Standard Time
  • Pacific SA Standard Time
  • Newfoundland Standard Time
  • E. South America Standard Time
  • Argentina Standard Time
  • SA Eastern Standard Time
  • Greenland Standard Time
  • Montevideo Standard Time
  • Bahia Standard Time
  • UTC-02
  • Mid-Atlantic Standard Time
  • Azores Standard Time
  • Cape Verde Standard Time
  • Morocco Standard Time
  • UTC
  • GMT Standard Time
  • Greenwich Standard Time
  • W. Europe Standard Time
  • Central Europe Standard Time
  • Romance Standard Time
  • Central European Standard Time
  • W. Central Africa Standard Time
  • Namibia Standard Time
  • Jordan Standard Time
  • GTB Standard Time
  • Middle East Standard Time
  • Egypt Standard Time
  • Syria Standard Time
  • South Africa Standard Time
  • FLE Standard Time
  • Turkey Standard Time
  • Israel Standard Time
  • E. Europe Standard Time
  • Arabic Standard Time
  • Kaliningrad Standard Time
  • Arab Standard Time
  • E. Africa Standard Time
  • Iran Standard Time
  • Arabian Standard Time
  • Azerbaijan Standard Time
  • Russian Standard Time
  • Mauritius Standard Time
  • Georgian Standard Time
  • Caucasus Standard Time
  • Afghanistan Standard Time
  • Pakistan Standard Time
  • West Asia Standard Time
  • India Standard Time
  • Sri Lanka Standard Time
  • Nepal Standard Time
  • Central Asia Standard Time
  • Bangladesh Standard Time
  • Ekaterinburg Standard Time
  • Myanmar Standard Time
  • SE Asia Standard Time
  • N. Central Asia Standard Time
  • China Standard Time
  • North Asia Standard Time
  • Singapore Standard Time
  • W. Australia Standard Time
  • Taipei Standard Time
  • Ulaanbaatar Standard Time
  • North Asia East Standard Time
  • Tokyo Standard Time
  • Korea Standard Time
  • Cen. Australia Standard Time
  • AUS Central Standard Time
  • E. Australia Standard Time
  • AUS Eastern Standard Time
  • West Pacific Standard Time
  • Tasmania Standard Time
  • Yakutsk Standard Time
  • Central Pacific Standard Time
  • Vladivostok Standard Time
  • New Zealand Standard Time
  • UTC+12
  • Fiji Standard Time
  • Magadan Standard Time
  • Kamchatka Standard Time
  • Tonga Standard Time
  • Samoa Standard Time

GetAccountSummary

Gets monthly and hourly charges and estimates for a given account or collection of accounts. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/Billing/GetAccountSummary/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Billing.asmx?op=GetAccountSummary

Request

Attributes

Name Type Description Req.
AccountAlias String Short code for a particular account. Yes

Examples

JSON (REST)

{
  "AccountAlias": "1000"
}

XML (REST)

<BillingRequest>
    <AccountAlias>1000</AccountAlias>
</BillingRequest>

XML (SOAP)

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:xsd="http://www.w3.org/2001/XMLSchema"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
  <GetAccountSummary xmlns="http://www.tier3.com/">
    <request>
       <accountAlias>1000</accountAlias>
    </request>
  </GetAccountSummary>
</soap:Body>
</soap:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
MonthlyEstimates Decimal The current estimate of total hourly charges, assuming the current hourly run rate.
MonthToDate Decimal The total of actual hourly charges incurred thus far.
CurrentHour Decimal The total charges incurred during the current hour.
PreviousHour Decimal The total charges incurred during the previous hour.
OneTimeCharges Decimal The total one time charges incurred this month (this would be for non-recurring charges such as domain name registration, SSL Certificates, etc.).
MonthToDateTotal Decimal The total charges incurred this month to date, including One Time Charges.

Examples

JSON (REST)

{
  "OneTimeCharges":0,
  "MonthToDateTotal":2.000000,
  "MonthlyEstimate":2.000000,
  "MonthToDate":2.000000,
  "CurrentHour":0.0,
  "PreviousHour":0.0,
  "Success":true,
  "Message":"OK",
  "StatusCode":0
}

XML (REST)

<BillingSummmaryResponse
  Success="true"
  Message="OK"
  StatusCode="0"
  MonthlyEstimate="161.870000"
  MonthToDate="82.050000"
  CurrentHour="0.223600"
  PreviousHour="0.223600"
  OneTimeCharges="0"
  MonthToDateTotal="82.050000" />

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <GetAccountSummaryResponse xmlns="http://www.tier3.com/">
            <GetAccountSummaryResult
                Success="true"
                Message="OK"
                StatusCode="0"
                MonthlyEstimate="2.000000"
                MonthToDate="2.000000"
                CurrentHour="0.0" 
                PreviousHour="0.0"
                OneTimeCharges="0"
                MonthToDateTotal="2.000000" />
        </GetAccountSummaryResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.
1800 Account Not Found. You must provide a valid account alias when calling this method.

GetBillingHistory

Gets the entire billing history for a given account or collection of accounts. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/Billing/GetBillingHistory/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Billing.asmx?op=GetBillingHistory

Request

Attributes

Name Type Description Req.
AccountAlias String Short code for a particular account. Yes

Examples

JSON (REST)

{
  "AccountAlias": "1000"
}

XML (REST)

<BillingRequest>
  <AccountAlias>1000</AccountAlias>
</BillingRequest>

XML (SOAP)

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <GetBillingHistory xmlns="http://www.tier3.com/">
            <request>
               <accountAlias>1000</accountAlias>
            </request>
        </GetBillingHistory>
    </soap:Body>
</soap:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
AccountAlias String Short name associated with an account.
OutstandingBalance Decimal The total unpaid balance associated with the account.
LedgerEntry Complex (see below) List of invoices that describe the credits and debits on an account.

LedgerEntry Attributes

Name Type Description
InvoiceID String Identifier for the account's invoice.
Date DateTime Date of the invoice.
Description String Descriptive text of the invoice; typically the name of the invoice.
Debit Decimal Charges associated with the invoice period.
Credit Decimal Credits applied to the account during this invoice period.
OutstandingBalance Decimal Total balance due for this invoice.

Examples

JSON (REST)

{
  "AccountAlias":"1001",
  "OutstandingBalance":1722.4500,
  "BillingHistory":[
    {
     "InvoiceID":"ID123456",
     "Date":"\/Date(1343775600000)\/",
     "Description":"Invoice ID123456",
     "Debit":1258.8100,
     "Credit":0,
     "OutstandingBalance":1363.8900,
     "ItemID":244,
     "DisplayPrecedence":1
    },
    {
    "InvoiceID":"ID67890",
    "Date":"\/Date(1346454000000)\/",
    "Description":"Invoice ID67890",
    "Debit":358.5600,
    "Credit":0,
    "OutstandingBalance":1722.4500,
    "ItemID":277,
    "DisplayPrecedence":1
    }
  ],
  "Success":true,
  "Message":"OK",
  "StatusCode":0
}

XML (REST)

<BillingHistoryResponse Success="true" Message="OK" StatusCode="0" AccountAlias="RSDA" OutstandingBalance="1722.4500">
    <BillingHistory>
        <LedgerEntry InvoiceID="ID123456"
            Date="2012-08-31T23:00:00"
            Description="Invoice ID123456"
            Debit="1258.8100"
            Credit="0"
            OutstandingBalance="1363.8900" />
        <LedgerEntry InvoiceID="ID67890"
            Date="2012-09-30T23:00:00"
            Description="Invoice ID67890"
            Debit="358.5600"
            Credit="0"
            OutstandingBalance="1722.4500" />
    </BillingHistory>
</BillingHistoryResponse>

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <GetBillingHistoryResponse xmlns="http://www.tier3.com/">
            <GetBillingHistoryResult Success="true" Message="OK" StatusCode="0" AccountAlias="RSDA" OutstandingBalance="1722.4500">
                <BillingHistory>
                    <LedgerEntry InvoiceID="RSDA4503BF68"
                        Date="2012-08-31T23:00:00"
                        Description="Invoice RSDA4503BF68"
                        Debit="1258.8100"
                        Credit="0"
                        OutstandingBalance="1363.8900" />
                    <LedgerEntry InvoiceID="RSDA9278D23F"
                        Date="2012-09-30T23:00:00"
                        Description="Invoice RSDA9278D23F"
                        Debit="358.5600" Credit="0"
                        OutstandingBalance="1722.4500" />
                </BillingHistory>
            </GetBillingHistoryResult>
        </GetBillingHistoryResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.
1800 Account Not Found. You must provide a valid account alias when calling this method.

GetGroupEstimate

Gets estimated costs for a group of servers. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/Billing/GetGroupEstimate/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Billing.asmx?op=GetGroupEstimate

Request

Attributes

Name Type Description Req.
AccountAlias String Short code for a particular account. If not provided, then the API user's account is used. No
HardwareGroupUUID String Unique identifier of the group that can be acquired via Groups API, or by retrieving this value from the URL when viewing the group in the Control Portal. Yes

Examples

JSON (REST)

{
  "AccountAlias": "1000",
  "HardwareGroupUUID":"8a03fbae8ddfe311b05f00505682315a"
}

XML (REST)

<GroupEstimateRequest>
  <AccountAlias>1000</AccountAlias>
  <HardwareGroupUUID>8a03fbae8ddfe311b05f00505682315a</HardwareGroupUUID>
</GroupEstimateRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <GetGroupEstimate xmlns="http://www.tier3.com/">
            <groupUuid>8a03fbae8ddfe311b05f00505682315a</groupUuid>
        </GetGroupEstimate>
    </soap12:Body>
</soap12:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
MonthlyEstimate Decimal Estimated cost of this group given current rate of usage.
MonthToDate Decimal Charges incurred up to today.
CurrentHour Decimal Charges for the current hour of usage.
PreviousHour Decimal Charges for the previous hour of usage.

Examples

JSON (REST)

{
  "MonthlyEstimate":0,
  "MonthToDate":0,
  "CurrentHour":0,
  "PreviousHour":0,
  "Success":true,
  "Message":"OK",
  "StatusCode":0
}

XML (REST)

<BillingResponse Success="true"
  Message="OK"
  StatusCode="0"
  MonthlyEstimate="0"
  MonthToDate="0"
  CurrentHour="0"
  PreviousHour="0" />

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <GetGroupEstimateResponse xmlns="http://www.tier3.com/">
            <GetGroupEstimateResult Success="true"
                Message="OK"
                StatusCode="0"
                MonthlyEstimate="0"
                MonthToDate="0"
                CurrentHour="0"
                PreviousHour="0" />
        </GetGroupEstimateResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
100 Authentication Failed. You must logon to the API prior to calling this method.
541 Hardware Group Not Found. You must provide a valid hardware group ID when calling this method.
1800 Account Not Found. You must provide a valid account alias when calling this method.

GetGroupSummaries

Gets the charges for groups and servers within a given account, and for any date range. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/Billing/GetGroupSummaries/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Billing.asmx?op=GetGroupSummaries

Request

Attributes

Name Type Description Req.
AccountAlias String Short code for a particular account. If not provided, then the API user's account is used. No
StartDate String Start date for query range. If missing, this defaults to beginning of the current month. No
EndDate String End date for query range. If missing, this defaults to current day of the current month. No

Examples

JSON (REST)

{
  "AccountAlias": "1000",
  "StartDate":"2012-11-01",
  "EndDate":"2012-11-15"
}

XML (REST)

<BillingRequest>
  <AccountAlias>1000</AccountAlias>
  <StartDate>2012-11-01</StartDate>
  <EndDate>2012-11-15</EndDate>
</BillingRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <GetGroupSummaries xmlns="http://www.tier3.com/">
            <accountAlias>1000</accountAlias>
        </GetGroupSummaries>
    </soap12:Body>
</soap12:Envelope>  

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
AccountAlias String Account that this group summary applied to.
StartDate String Start date of the query range.
EndDate Decimal End date of the query range.
Summary Complex (see below) Overview of costs for the group.
ServerGroupTotals Complex (see below) Details of individual costs of the group.

Summary Attributes

Name Type Description
MonthlyEstimate Decimal Estimated costs for all groups based on current usage.
MonthToDate Decimal Current charges so far this month.
CurrentHour Decimal Charges for the current hour.
MonthToDate Decimal Charges for the previous hour.

ServerGroupTotals Attributes

Name Type Description
MonthlyEstimate Decimal Estimated costs for all groups based on current usage.
MonthToDate Decimal Current charges so far this month.
CurrentHour Decimal Charges for the current hour.
PreviousHour Decimal Charges for the previous hour.
GroupID Integer Unique identifier for this specific group.
GroupName String User-given name to this group.
LocationAlias String Data center alias corresponding to this group.
ServerTotal Complex (see below) Collection of servers that make up the group, and the individual cost of each.

ServerTotal Attributes

Name Type Description
MonthlyEstimate Decimal Estimated costs for the server based on current usage.
MonthToDate Decimal Current charges so far this month.
CurrentHour Decimal Charges for the current hour.
PreviousHour Decimal Charges for the previous hour.
ServerName String Name of this server that is incurring charges.

Examples

JSON (REST)

{
  "Summary": {
      "MonthlyEstimate":73.790,
      "MonthToDate":73.790,
      "CurrentHour":0.0,
      "PreviousHour":0.0
  },
  "AccountAlias":"1000",
  "StartDate":"11/1/2012",
  "EndDate":"11/15/2012",
  "GroupTotals": [
    {
      "GroupID":1634,
      "GroupName":"Group 1",
      "LocationAlias":"WA1",
      "ServerTotals":[
        {
          "ServerName":"SERVER1",
          "MonthlyEstimate":73.790,
          "MonthToDate":73.790,
          "CurrentHour":0.0,
          "PreviousHour":0.0
        }
      ],
      "MonthlyEstimate":73.790,
      "MonthToDate":73.790,
      "CurrentHour":0.0,
      "PreviousHour":0.0
    }
  ],
  "Success":true,
  "Message":"Ok",
  "StatusCode":0
}

XML (REST)

<GroupSummariesResponse Success="true" Message="Ok" StatusCode="0" AccountAlias="1000" StartDate="11/1/2012" EndDate="11/15/2012">
    <Summary MonthlyEstimate="73.790" MonthToDate="73.790" CurrentHour="0.0" PreviousHour="0.0" />
    <GroupTotals>
        <ServerGroupTotal MonthlyEstimate="73.790"
            MonthToDate="73.790"
            CurrentHour="0.0"
            PreviousHour="0.0"
            GroupID="1634"
            GroupName="Group 1"
            LocationAlias="WA1">
            <ServerTotals>
                <ServerTotal MonthlyEstimate="73.790"
                    MonthToDate="73.790"
                    CurrentHour="0.0"
                    PreviousHour="0.0"
                    ServerName="SERVER1" />
            </ServerTotals>
        </ServerGroupTotal>
    </GroupTotals>
</GroupSummariesResponse>

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <GetGroupSummariesResponse xmlns="http://www.tier3.com/">
            <GetGroupSummariesResult Success="true"
              Message="Ok"
              StatusCode="0"
              AccountAlias="1000"
              StartDate="11/1/2012"
              EndDate="11/16/2012">
                <Summary MonthlyEstimate="83.180"
                    MonthToDate="83.180"
                    CurrentHour="0.223600"
                    PreviousHour="0.223600" />
                <GroupTotals>
                    <ServerGroupTotal MonthlyEstimate="83.180"
                      MonthToDate="83.180"
                      CurrentHour="0.223600"
                      PreviousHour="0.223600"
                      GroupID="1634"
                      GroupName="Group 1
                      LocationAlias="WA1">
                        <ServerTotals>
                            <ServerTotal MonthlyEstimate="83.180"
                              MonthToDate="83.180"
                              CurrentHour="0.223600"
                              PreviousHour="0.223600"
                              ServerName="SERVER1" />
                        </ServerTotals>
                    </ServerGroupTotal>
                </GroupTotals>
            </GetGroupSummariesResult>
        </GetGroupSummariesResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.
541 Hardware Group Not Found. You must provide a valid hardware group ID when calling this method.
1800 Account Not Found. You must provide a valid account alias when calling this method.
1801 Invalid Start Date. You must provide a valid start date when calling this method.
1802 Invalid End Date. You must provide a valid end date when calling this method.

GetInvoiceDetails

Gets the details for a given invoice within an account. Calls to this operation must include an authorization cookie acquired from the Logon operation.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the V2 Billing | Get Invoice Data for an Account Alias API.

URL

REST: https://api.ctl.io/REST/Billing/GetInvoiceDetails/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Billing.asmx?op=GetInvoiceDetails

Request

Attributes

Name Type Description Req.
AccountAlias String Short code for a particular account. If not provided, then the API user's account is used. Yes
InvoiceID String Unique identifier for a given invoice. Yes

Examples

JSON (REST)

{
  "AccountAlias": "1000",
  "InvoiceID":"ABC1235"
}

XML (REST)

<InvoiceRequest>
  <AccountAlias>1000</AccountAlias>
  <InvoiceID>ABC1235</InvoiceID>
</InvoiceRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <GetInvoiceDetails xmlns="http://www.tier3.com/">
            <accountAlias>1000</accountAlias>
            <invoiceId>ABC1235</invoiceId>
        </GetInvoiceDetails >
    </soap12:Body>
</soap12:Envelope>  

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
OpeningBalance Decimal Previous balance on the account.
NewCharges Decimal New charges for the invoice period.
Payments Decimal Amount of payments received.
EndingBalance Decimal Total billed amount for this invoice.
CurrentOutstandingBalance Decimal Total amount owed by this account.
Invoice Complex (see below) Invoice details and line items.
SupportLevel String Indicator of support level for the account.
developer,
legacy,
professional,
enterprise

Invoice Attributes

Name Type Description
ID String Unique identifier of the invoice.
Terms String Billing terms of this invoice.
CompanyName String Name of the company associated with the account.
AccountAlias String Short code of the account.
Address1 String Street address associated with the account.
City String City associated with the account.
StateProvince String State or province associated with the account.
PostalCode String Postcal code associated with the account.
BillingContactEmail String Email address associated with the account.
InvoiceCCEmail String Secondary email address associated with the account.
TotalAmount Decimal Total amount of this invoice.
InvoiceDate DateTime Date of the invoice.
PONumber String Purchase Order identifier.
InvoiceLineItem Complex (see below) Individual line item on the invoice.

InvoiceLineItem Attributes

Name Type Description
Quantity Integer Count of the item that is being charged.
Description String Typically the name of the billed resource or container.
UnitCost Decimal Cost of one unit of the resource.
ItemTotal Decimal Unit cost multiplied by the quantity.
ServiceLocation String Data center alias associated with this resource.
LineItemDetail Complex (see below) Individual line item description and cost. For instance, may refer to the servers within a group.

LineItemDetail Attributes

Name Type Description
Description String Typically the name of the lowest level billed resource, such as a server name.
Cost Decimal Cost of this resource.

Examples

JSON (REST)

{
  "OpeningBalance":1363.8900,
  "NewCharges":358.5600,
  "Payments":0.0,
  "EndingBalance":1722.4500,
  "CurrentOutstandingBalance":1722.4500,
  "Invoice":
    {
      "ID":"RSDA9278D23F",
      "Terms":"Upon Receipt",
      "CompanyName":"Demo Account",
      "AccountAlias":"1000",
      "ParentAccountAlias":null,
      "Address1":"123 100th St NE",
      "Address2":null,
      "City":"Bellevue",
      "StateProvince":"WA",
      "PostalCode":"98155",
      "BillingContactEmail":"[email protected]",
      "InvoiceCCEmail":"",
      "TotalAmount":358.5600,
      "InvoiceDate":"\/Date(1349046000000)\/",
      "PONumber":null,
      "LineItems":[
        {
          "Quantity":1,
          "Description":"Group 1",
          "UnitCost":103.5800,
          "ItemTotal":103.5800,
          "ServiceLocation":"WA1",
          "ItemDetails":[
            {
              "Description":"SERVER123",
              "Cost":103.5800
            }
          ]
        },
        {
          "Quantity":1,
          "Description":"Demo Group 2",
          "UnitCost":252.9800,
          "ItemTotal":252.9800,
          "ServiceLocation":"WA1",
          "ItemDetails":[
            {
              "Description":"SERVER987",
              "Cost":252.9800
            }
          ]
        },
        {
          "Quantity":1,
          "Description":"External IP Address (QA1)",
          "UnitCost":2.0000,
          "ItemTotal":2.0000,
          "ServiceLocation":"WA1",
          "ItemDetails":[]
        }
      ]
    },
  "Success":true,
  "Message":"Ok",
  "StatusCode":0
}

XML (REST)

<InvoiceDetailResponse
  Success="true"
  Message="Ok"
  StatusCode="0"
  OpeningBalance="1363.8900"
  NewCharges="358.5600"
  Payments="0.0"
  EndingBalance="1722.4500"
  CurrentOutstandingBalance="1722.4500">
  <Invoice
    ID="RSDA9278D23F"
    Terms="Upon Receipt"
    CompanyName="Demo Company"
    AccountAlias="1000"
    Address1="123 100th St NE"
    City="Bellevue"
    StateProvince="WA"
    PostalCode="98155"
    BillingContactEmail="[email protected]"
    InvoiceCCEmail=""
    TotalAmount="358.5600"
    InvoiceDate="2012-09-30T23:00:00">
      <LineItems>
          <InvoiceLineItem Quantity="1" Description="Demo Group 1" UnitCost="103.5800" ItemTotal="103.5800" ServiceLocation="WA1">
              <ItemDetails>
                  <LineItemDetail Description="SERVER123" Cost="103.5800" />
              </ItemDetails>
          </InvoiceLineItem>
          <InvoiceLineItem Quantity="1" Description="Demo Group 2" UnitCost="252.9800" ItemTotal="252.9800" ServiceLocation="WA1">
              <ItemDetails>
                  <LineItemDetail Description="SERVER987" Cost="252.9800" />
              </ItemDetails>
          </InvoiceLineItem>
          <InvoiceLineItem Quantity="1" Description="External IP Address (QA1)" UnitCost="2.0000" ItemTotal="2.0000" ServiceLocation="QA1">
              <ItemDetails />
          </InvoiceLineItem>
      </LineItems>
  </Invoice>
</InvoiceDetailResponse>

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <GetInvoiceDetailsResponse xmlns="http://www.tier3.com/">
            <GetInvoiceDetailsResult
              Success="true"
              Message="Ok"
              StatusCode="0"
              OpeningBalance="1363.8900"
              NewCharges="358.5600"
              Payments="0.0"
              EndingBalance="1722.4500"
              CurrentOutstandingBalance="1722.4500">
                <Invoice ID="RSDA9278D23F"
                  Terms="Upon Receipt"
                  CompanyName="Demo Account"
                  AccountAlias="1000"
                  Address1="123 100th St NE"
                  City="Bellevue"
                  StateProvince="WA"
                  PostalCode="98155"
                  BillingContactEmail="[email protected]"
                  InvoiceCCEmail=""
                  TotalAmount="358.5600"
                  InvoiceDate="2012-09-30T23:00:00">
                    <LineItems>
                        <InvoiceLineItem Quantity="1" Description="Group 1" UnitCost="103.5800" ItemTotal="103.5800" ServiceLocation="WA1">
                            <ItemDetails>
                                <LineItemDetail Description="SERVER123" Cost="103.5800" /></ItemDetails>
                        </InvoiceLineItem>
                        <InvoiceLineItem Quantity="1" Description="Group 2" UnitCost="252.9800" ItemTotal="252.9800" ServiceLocation="WA1">
                            <ItemDetails><LineItemDetail Description="SERVER987" Cost="252.9800" /></ItemDetails>
                            </InvoiceLineItem>
                        <InvoiceLineItem Quantity="1" Description="External IP Address (QA1)" UnitCost="2.0000" ItemTotal="2.0000" ServiceLocation="WA1">
                            <ItemDetails />
                        </InvoiceLineItem>
                    </LineItems>
                </Invoice>
            </GetInvoiceDetailsResult>
        </GetInvoiceDetailsResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.
1800 Account Not Found. You must provide a valid account alias when calling this method.
1804 Invoice ID Required. You must provide a valid invoice ID when calling this method.
1805 Invoice Not Found. There is no valid invoice for the ID provided.

GetServerEstimate

Gets the estimated monthly cost for a given server. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/Billing/GetServerEstimate/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Billing.asmx?op=GetServerEstimate

Request

Attributes

Name Type Description Req.
AccountAlias String Short code for a particular account. If not provided, then the API user's account is used. No
ServerName String Name given to the server. Yes

Examples

JSON (REST)

{
  "AccountAlias": "1000",
  "ServerName":"SVR1"
}

XML (REST)

<ServerEstimateRequest>
  <AccountAlias>RSDA</AccountAlias>
  <ServerName>SVR1</ServerName>
</ServerEstimateRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <GetServerEstimate xmlns="http://www.tier3.com/">
            <name>SVR1</name>
        </GetServerEstimate>
    </soap12:Body>
</soap12:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
MonthlyEstimate Decimal Estimated cost of this server given current rate of usage.
MonthToDate Decimal Charges incurred up to today.
CurrentHour Decimal Charges for the current hour of usage.
PreviousHour Decimal Charges for the previous hour of usage.

Examples

JSON (REST)

{
  "MonthlyEstimate":0,
  "MonthToDate":0,
  "CurrentHour":0,
  "PreviousHour":0,
  "Success":true,
  "Message":"OK",
  "StatusCode":0
}

XML (REST)

<BillingResponse Success="true"
  Message="OK"
  StatusCode="0"
  MonthlyEstimate="0"
  MonthToDate="0"
  CurrentHour="0"
  PreviousHour="0" />

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <GetServerEstimateResponse xmlns="http://www.tier3.com/">
            <GetServerEstimateResult Success="true"
              Message="OK"
              StatusCode="0"
              MonthlyEstimate="0"
              MonthToDate="0" 
              CurrentHour="0"
              PreviousHour="0" />
        </GetServerEstimateResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
5 Resource Does Not Exist. You must provide a valid server identifier when calling this method.
100 Authentication Failed. You must logon to the API prior to calling this method.
541 Hardware Group Not Found. You must provide a valid hardware group ID when calling this method.
1800 Account Not Found. You must provide a valid account alias when calling this method.

GetServerHourlyCharges

Gets the server-based hourly cost for any time period. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/Billing/GetServerHourlyCharges/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Billing.asmx?op=GetServerHourlyCharges

Request

Attributes

Name Type Description Req.
AccountAlias String Short code for a particular account. If not provided, then the API user's account is used. No
ServerName String Name given to the server. Yes
StartDate DateTime Start of the query period. No
EndDate String End of the query period. No

Examples

JSON (REST)

{
  "AccountAlias": "1000",
  "ServerName":"QA1RSDASER101",
  "StartDate":"2012-11-14",
  "EndDate":"2012-11-15"
}

XML (REST)

<ServerRequest>
  <AccountAlias>RSDA</AccountAlias>
  <ServerName>QA1RSDASER101</ServerName>
  <StartDate>2012-11-14</StartDate>
  <EndDate>2012-11-15</EndDate>
</ServerRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <GetServerHourlyCharges xmlns="http://www.tier3.com/">
            <accountAlias>1000</accountAlias>
            <name>QA1RSDASER101</name>
            <startDate>2012-11-15</startDate>
            <endDate>2012-11-15</endDate>
        </GetServerHourlyCharges>
    </soap12:Body>
</soap12:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
AccountAlias String Short code for a particular account.
ServerName String Name given to the server.
StartDate DateTime Start of the query period.
EndDate DateTime End of the query period.
Summary Complex Aggregation of charges for the server.
HourlyCharges Complex Per hour for the server.

Examples

JSON (REST)

{
  "Summary":
    {
      "MonthlyEstimate":0.0,
      "MonthToDate":0.0,
      "CurrentHour":0.0,
      "PreviousHour":0.0
    },
  "AccountAlias":"RSDA",
  "ServerName":"QA1RSDASER101",
  "StartDate":"\/Date(1352851200000)\/",
  "EndDate":"\/Date(1352937600000)\/",
  "HourlyCharges": [
    {
      "Hour":"2012-11-14T12:00:00",
      "ProcessorCost":"0",
      "MemoryCost":"0",
      "StorageCost":"0",
      "OSCost":"0"
    },
    {
      "Hour":"2012-11-14T01:00:00",
      "ProcessorCost":"0",
      "MemoryCost":"0",
      "StorageCost":"0",
      "OSCost":"0"
    }
  ],
  "Success":true,
  "Message":"OK",
  "StatusCode":0
}

XML (REST)

<ServerHourlyChargesResponse
  Success="true"
  Message="OK"
  StatusCode="0"
  AccountAlias="RSDA"
  ServerName="QA1RSDASER101"
  StartDate="2012-11-14T00:00:00"
  EndDate="2012-11-15T00:00:00">
    <Summary MonthlyEstimate="0.0" MonthToDate="0.0" CurrentHour="0.0" PreviousHour="0.0" />
    <HourlyCharge>
        <ServerHourlyCost Hour="2012-11-14T12:00:00" ProcessorCost="0" MemoryCost="0" StorageCost="0" OSCost="0" />
        <ServerHourlyCost Hour="2012-11-14T01:00:00" ProcessorCost="0" MemoryCost="0" StorageCost="0" OSCost="0" />
    </HourlyCharge>
</ServerHourlyChargesResponse>

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <GetServerHourlyChargesResponse xmlns="http://www.tier3.com/">
            <GetServerHourlyChargesResult Success="true"
              Message="OK"
              StatusCode="0"
              AccountAlias="RSDA"
              ServerName="QA1RSDASER101"
              StartDate="2012-11-14T00:00:00"
              EndDate="2012-11-15T00:00:00">
                <Summary MonthlyEstimate="0.0" MonthToDate="0.0" CurrentHour="0.0" PreviousHour="0.0" />
                <HourlyCharges>
                    <ServerHourlyCost Hour="2012-11-14T12:00:00" ProcessorCost="0" MemoryCost="0" StorageCost="0" OSCost="0" />
                    <ServerHourlyCost Hour="2012-11-14T01:00:00" ProcessorCost="0" MemoryCost="0" StorageCost="0" OSCost="0" />
                </HourlyCharges>
            </GetServerHourlyChargesResult>
        </GetServerHourlyChargesResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
5 Resource Does Not Exist. You must provide a valid server identifier when calling this method.
100 Authentication Failed. You must logon to the API prior to calling this method.
541 Hardware Group Not Found. You must provide a valid hardware group ID when calling this method.
1800 Account Not Found. You must provide a valid account alias when calling this method.
1801 Start Date Invalid. You must provide a valid start date when calling this method.
1802 End Date Invalid. You must provide a valid end date when calling this method.

Deploy Blueprint

Deploys a Blueprint with the given set of parameter values.

URL

REST: https://api.ctl.io/REST/Blueprint/DeployBlueprint/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Blueprints.asmx?op=DeployBlueprint

Request

Attributes

Name Type Description Req.
ID Int The ID of the Blueprint to deploy. Yes
LocationAlias string The alias of the Datacenter where you would like to deploy the blueprint to. If not provided, it will default to your primary datacenter. No
Parameters List (see below) A list of Parameter values to use during the deployment of the Blueprint. Yes
CustomFields Complex (see below) Custom Fields that need to be set on each server created during blueprint deployment No

Parameter Attributes

Name Type Description
Name String The name of the Parameter being set.
Value String The value for the Parameter. This value will be validated based on the type and validation rules specified by the Blueprint Parameter definition.

CustomField Attributes

Name Type Description
ID String Unique identifier that is associated with the Account Custom Field. Call Account/GetCustomFields for a list of all custom fields set at the account level.
Value String For Text: Any value; For Option values, call Account/GetCustomFields to see possible values to pass in. Checkbox values should be "true" or "false".

Examples

JSON

{
  "ID": "1",
  "LocationAlias": "WA1",
  "Parameters": [
    { "Name":"T3.BuildServerTask.Password", "Value":"password" },
    { "Name":"T3.BuildServerTask.Network","Value":"VLAN_XXX" },
    { "Name":"T3.BuildServerTask.PrimaryDNS","Value":"192.168.64.19" },
    { "Name":"T3.BuildServerTask.SecondaryDNS","Value":"192.168.64.20" }
  ],
  "CustomFields": [
    { "ID": "ea97c6e09f604eb689dcdc080114b04d","Value": "A test"},
    { "ID": "b9f454f2ae664998acc3302b24330c5b","Value": "2"},
    { "ID": "d1f12de4ce4b4685b72ba632db0685c6","Value": "true"}
  ]
}

XML

<DeployBlueprintRequest>
    <ID>107</ID>
    <LocationAlias>WA1</LocationAlias>
    <Parameters>
        <Parameter Name="T3.BuildServerTask.Password" Value="[email protected]" />
        <Parameter Name="T3.BuildServerTask.Network" Value="VLAN_XXX" />
        <Parameter Name="T3.BuildServerTask.PrimaryDNS" Value="192.168.64.19" />
        <Parameter Name="T3.BuildServerTask.SecondaryDNS" Value="192.168.64.20" />
    </Parameters>
    <CustomFields ID="ea97c6e09f604eb689dcdc080114b04d" Value="Test text" />
    <CustomFields ID="b9f454f2ae664998acc3302b24330c5b" Value="2" />
    <CustomFields ID="d1f12de4ce4b4685b72ba632db0685c6" Value="true" />
</DeployBlueprintRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request to deploy the Blueprint. Status of the request can be obtained by calling the GetDeploymentStatus method.

Examples

JSON

{
  "RequestID": 1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
100 Authentication Failed - You must logon to the API prior to calling this method.
1210 A required Parameter is missing.
1211 A Parameter value is invalid. Ensure that the supplied value meets the validation rules of the Blueprint Parameter.
1212 A Parameter type is invalid. Ensure that the supplied value is convertible to the type defined by the Blueprint Parameter.

Get Blueprint Details

Gets the full details of the specified Blueprint.

URL

REST: https://api.ctl.io/REST/Blueprint/GetBlueprintDetails/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Blueprints.asmx?op=GetBlueprintDetailsResponseMsg

Request

Attributes

Name Type Description Req.
ID Int The ID of the Blueprint to retrieve details for. Yes

Examples

JSON

{ "ID": "1" }

XML

<BlueprintRequest>
    <ID>1</ID>
</BlueprintRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
BlueprintDetails Complex (see below) The Blueprint details (see below)

BlueprintDetails Attributes

Name Type Description
Author String The name of the company that authored the Blueprint.
Capabilities String[] List of capabilities that the Blueprint has been tagged with.
Description String A long description of the Blueprint.
ID Int The ID of the Blueprint
Name String The name of the Blueprint.
Status Int The status of the Blueprint.
1 = Active
3 = Deleted
4 = Under Construction
Visibility Int The visibility of the Blueprint.
1 = Public
2 = Private

Examples

JSON

{
  "BlueprintDetails":{
    "ID":1,
    "Name":"Blueprint 01",
    "Visibility":1,
    "Status":1
    "Author":"",
    "Capabilities":["Web Applications","CDN"],
    "Description":"This is the first Blueprint"
  },
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<GetBlueprintDetailsResponse Success="true" Message="Success" StatusCode="0">
    <BlueprintDetails ID="1" Status="1" Visibility="1">
        <Name>Blueprint 01</Name>
        <Author></Author>
        <Description>This is the first Blueprint</Description>
    </BlueprintDetails>
</GetBlueprintDetailsResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Blueprint with the specified ID cannot be found.
100 Authentication Failed. You must logon to the API prior to calling this method.

Get Blueprint Parameters

Gets a the full list of parameters that are required to deploy a Blueprint.

URL

REST: https://api.ctl.io/REST/Blueprint/GetBlueprintParameters/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Blueprints.asmx?op=GetBlueprintParamatersResponseMsg

Request

Attributes

Name Type Description Req.
ID Int The ID of the Blueprint to retrieve parameters for. Yes

Examples

JSON

{ "ID":1 }

XML

<BlueprintRequest>
    <ID>1</ID>
</BlueprintRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Parameters List (see below) A list of the parameters required to deploy the Blueprint (see below)

Parameter Attributes

Name Type Description
Name String The name of the Parameter.
Options List A list of options to choose from if the Parameter is an Option or MultiSelect type. Each option has 2 attributes: Name and Value.
Regex String A regular expression defining any additional validation that the Parameter value must pass. This value is supplied by the Blueprint author.
Type JSON: Int
XML: String
The data type of the Parameter
1/Network = internal name of an existing network
2/Numeric = numeric value
3/Option = constrained to only one of the listed options
4/Password = password value
5/Server = name of an existing server
6/ServerIP = IP address of an existing server
7/String = string value
8/MultiSelect = value constrained to one or more of the listed options
Â

Examples

JSON

{
  "ID":1,
  "Parameters":[
    {
      "Name":"T3.ScriptTask.Parameter01",
      "Regex":null,
      "Type":7,
      "Options":[]
    },
    {
      "Name":"T3.ScriptTask.Parameter02",
      "Regex":null,
      "Type":3,
      "Options":[
        {"Name":"Option 1","Value":"1"},
        {"Name":"Option 2","Value":"2"}
      ]
    }
  ],
  "Success":true,
  "Message":"Success",
  "StatusCode":0
 }

XML

<GetBlueprintParamatersResponse Success="true" Message="Success" StatusCode="0">
    <ID>46</ID>
    <Parameters>
          <Parameter Name="T3.ScriptTask.Parameter01" Type="String" />
          <Parameter Name="T3.ScriptTask.Parameter02" Type="Option">
              <Option Name="Option 1" Value="1"/>
              <Option Name="Option 2" Value="1"/>
          </Parameter>
      </Parameters>
</GetBlueprintParamatersResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Blueprint with the specified ID cannot be found.
100 Authentication Failed. You must logon to the API prior to calling this method.

Get Blueprints

Gets a list of all Blueprints with the specified search criteria.

URL

REST:https://api.ctl.io/REST/Blueprint/GetBlueprints/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Blueprints.asmx?op=GetBlueprintsResponseMsg

Request

Attributes

Name Type Description Req.
CompanySize Int The target company size the of the Blueprint
1 = 1 - 100
2 = 101 - 1,000
3 = 1,001 - 5,000
4 = 5,000+
No
OperatingSystems Int [] A list of the operating systems that a Blueprint contains
Cent OS - 64 bit = 7
Ubuntu - 64 bit = 20
Debian 64-bit = 21
RedHat Enterprise Linux 64-bit = 22
RedHat Enterprise Linux 5 64-bit = 25
Windows 2012 Datacenter 64-bit = 27
Windows 2012 R2 Datacenter 64-bit = 28
Ubuntu 12 64-Bit = 31
CentOS 5 64-Bit = 33
CentOS 6 64-Bit = 35
Debian 6 64-Bit = 36
Debian 7 64-Bit = 37
RedHat 6 64-Bit = 38
CoreOS = 39
PXE Boot = 40
Ubuntu 14 64-Bit = 41
RedHat 7 64-Bit = 42
Windows 2008 R2 Standard 64-Bit = 43
Windows 2008 R2 Enterprise 64-Bit = 44
Windows 2008 R2 Datacenter 64-Bit = 45
No
Search String A keyword search within the Name and Description of the Blueprint No
Visibility Int The visibility level of the Blueprint.
1 = Public
2 = Private
3 = Private Shared
Yes

Examples

JSON

{
  "CompanySize": "2",
  "OperatingSystems": [ 7, 20, 22, 28],
  "Search": "High Performance",
  "Visibility": 1
}

XML

<GetBlueprintsRequest>
      <CompanySize>2</CompanySize>
      <OperatingSystems>
          <OS>7</OS>
          <OS>20</OS>
          <OS>22</OS>
          <OS>28</OS>
      </OperatingSystems>
      <Search>High Performance</Search>
      <Visibility>1</Visibility>
</GetBlueprintsRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Blueprints Complex (see below) A list of Blueprints (see below).

Blueprint Attributes

Name Type Description
ID Int The ID of the Blueprint.
Name String The name of the Blueprint.

Examples

JSON

{
  "Blueprints":[
    {"ID":1,"Name":"Blueprint 01"},
    {"ID":2,"Name":"Blueprint 02"},
  ],
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<GetBlueprintsResponse Success="true" Message="Success" StatusCode="0">
    <Blueprints>
        <Blueprint ID="1" Name="Blueprint 01" />
        <Blueprint ID="2" Name="Blueprint 02" />
    </Blueprints>
</GetBlueprintsResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
100 Authentication Failed - You must logon to the API prior to calling this method.
1201 The Visibility value is missing or invalid.

Get Deployment Status

Gets the status of the specified Blueprint deployment.

URL

REST: https://api.ctl.io/REST/Blueprint/GetDeploymentStatus/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Blueprints.asmx?op=GetDeploymentStatusMsg

Request

Attributes

Name Type Description Req.
RequestID Int The ID of the Blueprint Deployment to retrieve status for. Yes
LocationAlias String The location of the Blueprint Deployment to retrieve status for. If not provided, will default to the API user's default data center. No
AccountAlias String ID of the account Yes

Examples

JSON

{
  "RequestID": "1",
  "LocationAlias": "WA1"
}

XML

<GetDeploymentStatusRequest>
    <RequestID>1</RequestID>
    <LocationAlias>WA1</LocationAlias>
</GetDeploymentStatusRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Blueprint deployment request. (Obtained from DeployBlueprint.)
CurrentStatus String The status of the Blueprint deployment. Valid values are: NotStarted, Executing, Succeeded, Failed, and Resumed.
Description String A detailed description of the current status.
PercentComplete Int The percentage of the work that has been completed on the request.
StatusDate DateTime The timestamp (UTC) that the most recent status was recorded on the Request.
Step String The current step being executed.
Servers Array An array of strings with the names of any servers built as part of the Blueprint.
This element is only populated when the Request was originally for server creation.

Examples

JSON

{
  "RequestID":210,
  "CurrentStatus":"Failed",
  "Description":"Error Building Blueprint",
  "StatusDate":"\/Date(1318480463790)\/",
  "Step":"0",
  "PercentComplete":0,
  "Success":true,
  "Message":"Success",
  "StatusCode":0,
  "Servers":["WA1T3NWEB01"]
}

XML

<GetDeploymentStatusResponse
  Success="true"
  Message="Success"
  StatusCode="0"
  RequestID="210"
  CurrentStatus="Failed"
  Description="Error Building Blueprint"
  StatusDate="2011-10-12T21:34:23.79"
  Step="0"
  PercentComplete="0"
    <Servers>
        <string>WA1T3NWEB01</string>
    </Servers>
</GetDeploymentStatusResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Blueprint with the specified ID cannot be found.
100 Authentication Failed. You must logon to the API prior to calling this method.

Get Packages

Gets a list of Blueprint Packages.

URL

REST: https://api.ctl.io/REST/Blueprint/GetPackages/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Blueprints.asmx?op=GetPackagesResponseMsg

Request

Attributes

Name Type Description Req.
Classification Int The type of Packages that should be returned.
1 = System (reserved)
2 = Script
3 = Software

Yes
Visibility Int The visibility of Packages that should be returned.
1 = Public
2 = Private
3 = Shared
Yes

Examples

JSON

{ "Classification": "1", "Visibility": "1" }

XML

<GetPackagesRequest>
  <Classification>1</Classification>
  <Visibility>1</Visibility>
</GetPackagesRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Packages Complex (see below) A list of Packages (see below).

Package Attributes

Name Type Description
ID Int The ID of the Package. This value is for reference only.
Name String The name of the Package.
Classification Int The classification of the Package.
1 = System
2 = Script
3 = Software

Examples

JSON

{
  "Packages": [
    {"ID":2,"Name":"Add Disk","Classification":1},
    {"ID":3,"Name":"Add IP Address","Classification":1},
    {"ID":4,"Name":"Add Mapped IP Address","Classification":1},
    {"ID":5,"Name":"Snapshot Server","Classification":1},
    {"ID":6,"Name":"Reboot Server","Classification":1}
  ],
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<GetPackagesResponse Success="true" Message="Success" StatusCode="0">
    <Packages>
        <Package ID="2" Name="Add Disk" Classification="1" />
        <Package ID="3" Name="Add IP Address" Classification="1" />
        <Package ID="4" Name="Add Mapped IP Address" Classification="1" />
        <Package ID="5" Name="Snapshot Server" Classification="1" />
        <Package ID="6" Name="Reboot Server" Classification="1" />
    </Packages>
</GetPackagesResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
100 Authentication Failed - You must logon to the API prior to calling this method.
1200 The Classification value is missing or invalid.
1201 The Visibility value is missing or invalid.

Get Pending Packages

Gets a list of Blueprint Packages that are pending publication.

This list contains all Packages that were uploaded to via FTP or that were uploaded in the UI via HTTP.

URL

REST: https://api.ctl.io/REST/Blueprint/GetPendingPackages/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Blueprints.asmx?op=GetPendingPackages

Request

Attributes

None.

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Packages Complex (see below) A list of Packages (see below)

Package Attributes

Name Type Description
ID Int The ID of the Package.
This value is for reference only and will always be 0.
Name String The name of the Package.
This will be the name of the Package zip file that was uploaded.
Classification Int This value will always be 0 for pending packages

Examples

JSON

{
  "Packages": [
    {"ID":0,"Name":"Script 01","Classification":0},
    {"ID":0,"Name":"Software 01","Classification":0}
  ],
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<GetPackagesResponse Success="true" Message="Success" StatusCode="0">
    <Packages>
        <Package ID="0" Name="Script 01" Classification="0" />
        <Package ID="0" Name="Software 01" Classification="0" />
    </Packages>
</GetPackagesResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
100 Authentication Failed - You must logon to the API prior to calling this method.

Publish Package

Publishes a Blueprint Package for use within the Blueprint Designer.

URL

REST: https://api.ctl.io/REST/Blueprint/PublishPackage/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Blueprints.asmx?op=PublishPackage

Request

Attributes

Name Type Description Req.
Classification Int The type of Packages that should be returned
1 = System (reserved)
2 = Script
3 = Software
Yes
Name String The name of the Package file to publish.
Obtained via the GetPendingPackages method.
Yes
OperatingSystems Int[] A list of operating systems that this Package can be deployed to (see table below).
* The most recent list is always available from the ListAvailableServerTemplates API call.
Yes
Visibility Int The visibility of Packages that should be returned
1 = Public
2 = Private
3 = Shared
Yes

Operating Systems

Operating System Description
2 Windows 2003 R2 Standard 32-bit
3 Windows 2003 R2 Standard 64-bit
5 Windows 2008 R2 Standard 64-bit
15 Windows 2003 R2 Enterprise 32-bit
16 Windows 2003 R2 Enterprise 64-bit
18 Windows 2008 R2 Enterprise 64-bit
20 BOSH Stemcell Template
20 Stemcell - Micro-BOSH
25 RedHat Enterprise Linux 5 64-bit
26 Windows 2008 R2 Datacenter Edition 64-bit
27 Windows 2012 Datacenter Edition 64-bit
28 Windows 2012 R2 Datacenter Edition 64-bit
29 Ubuntu 10 32-bit
30 Ubuntu 10 64-bit
30 Web Fabric Ubuntu x64 Template
30 Web Fabric Ubuntu x64 Template V2
31 Ubuntu 12 64-bit
32 CentOS 5 32-bit
33 CentOS 5 64-bit
34 CentOS 6 32-bit
35 CentOS 6 64-bit
36 Debian 6 64-bit
37 Debian 7 64-bit
38 RedHat Enterprise Linux 6 64-bit
40 PXE Boot [EXPERIMENTAL]
41 Ubuntu 14 64-bit

Examples

JSON

{
  "Classification": "2",
  "Name":"Script01.zip",
  "OperatingSystems":[4,5],
  "Visibility": "1"
}

XML

<PublishPackageRequest>
    <Classification>2</Classification>
    <Name>Script01.zip</Name>
    <OperatingSystems>
    <OS>4</OS>
    <OS>5</OS>
    </OperatingSystems>
    <Visibility>1</Visibility>
</PublishPackageRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request to publish the Package.
Status of the request can be obtained by calling the GetRequestStatus method.

Examples

JSON

{
  "RequestID": 1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
100 Authentication Failed - You must logon to the API prior to calling this method.
1200 The Classification value is missing or invalid.
1201 The Visibility value is missing or invalid.
1202 The supplied operating system values are missing or invalid.

ArchiveHardwareGroup

Archives all Servers in the Group and then archives the Group.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Group Actions | Archive Group API.

URL

REST: https://api.ctl.io/REST/Group/ArchiveHardwareGroup/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Group.asmx?op=ArchiveHardwareGroup

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the group. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access groups in your sub accounts. No
UUID String The unique identifier of the Hardware Group to archive. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "UUID": "b7e44f0391824d408732f215a91a0578"
}

XML

<GroupRequest>
    <AccountAlias>ACCT</AccountAlias>
    <UUID>b7e44f0391824d408732f215a91a0578</UUID>
</GroupRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
  <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
6 Invalid Operation. Group must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.

CreateHardwareGroup

Creates a new Hardware Group.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Groups | Create Group API.

URL

REST: https://api.ctl.io/REST/Group/CreateHardwareGroup/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Group.asmx?op=CreateHardwareGroup

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account to owns the group. Can be the parent alias or a sub-account alias. Yes
ParentUUID String The unique identifier of the parent group. Yes
Name String The name of the Hardware Group Yes
Description String A description of the Hardware Group.If none is supplied, the Name will be used. No

Examples

JSON

{
  "AccountAlias": "UNK",
  "ParentUUID": "b7e44f0391824d408732f215a91a0578",
  "Name": "Group 01",
  "Description": "My new group"
}

XML

<CreateHardwareGroupRequest>
    <AccountAlias>ACCT</AccountAlias>
    <ParentUUID>b7e44f0391824d408732f215a91a0578</ParentUUID>
    <Name>Group 01</Name>
    <Description>My new group</Description>
</CreateHardwareGroupRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Group Complex The created group (see below).

Group Attributes

Name Type Description
ID Int The legacy ID of the Group.
Deprecated. Not available after May 6, 2015. Use UUID instead.
UUID String The unique identifier of the Group.
ParentID Int The legacy ID of the parent Group.
Deprecated. Not available after May 6, 2015. Use ParentUUID instead.
ParentUUID String The unique identifier of the Parent Group.
Name String The name of the Group.
IsSystemGroup Bool Denotes a required system Group.

Examples

JSON

{
  "Group":
    {
      "ID":5,
      "UUID":"3d30a6ab6c1243388b7bc966d073e353",
      "ParentID":2,
      "ParentUUID":"b7e44f0391824d408732f215a91a0578"
      "Name":"Group 01",
      "IsSystemGroup":false
    },
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<CreateHardwareGroupResponse Success="true" Message="Success" StatusCode="0">
  <Group ID="5" UUID="3d30a6ab6c1243388b7bc966d073e353"
    ParentID="2" ParentUUID="b7e44f0391824d408732f215a91a0578"
    Name="Group 01" IsSystemGroup="false" />
</CreateHardwareGroupResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Parent Group with the specified ID cannot be found.
100 Authentication Failed - You must logon to the API prior to calling this method.
1310 The Name attribute is missing.

DeleteHardwareGroup

Deletes the Hardware Group along with all child groups and servers.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Groups | Delete Group API.

URL

REST: https://api.ctl.io/REST/Group/DeleteHardwareGroup/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Group.asmx?op=DeleteHardwareGroup

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the group. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access groups in your sub accounts. No
UUID String The unique identifier of the Hardware Group to delete. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "UUID": "b7e44f0391824d408732f215a91a0578"
}

XML

<DeleteGroupRequest>
  <AccountAlias>ACCT</AccountAlias>
  <UUID>b7e44f0391824d408732f215a91a0578</UUID>
</DeleteGroupRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request to delete the Group. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
  <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
6 Invalid Operation. Group must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.

GetGroups

Gets a list of all groups with the specified search criteria.

URL

REST: https://api.ctl.io/REST/Group/GetGroups/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Group.asmx?op=GetGroups

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the groups. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access groups in your sub accounts. No
Location String The data center location to query for groups. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Location": "DC1"
}

XML

<GetGroupsRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Location>WA1</Location>
</GetGroupsRequest>

Response

Attributes

Name Type Description
AccountAlias String The alias of the account that owns the groups.
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
HardwareGroups Complex A list of Hardware Groups (see below)

Hardware Group Attributes

Name Type Description
ID Int The legacy ID of the Group.
Deprecated. Not available after May 6, 2015. Use UUID instead.
UUID String The unique identifier of the Group.
ParentID Int The legacy ID of the parent Group.
Deprecated. Not available after May 6, 2015. Use ParentUUID instead.
ParentUUID String The unique identifier of the Parent Group.
Name String The name of the Group.
IsSystemGroup Bool Denotes a required system Group.

Examples

JSON

{
  "AccountAlias":"UNK",
  "HardwareGroups": [
    {
      "ID":5,
      "UUID":"3d30a6ab6c1243388b7bc966d073e353",
      "ParentID":2,
      "ParentUUID":"b7e44f0391824d408732f215a91a0578"
      "Name":"Group 01",
      "IsSystemGroup":false
    },
    {
      "ID":2,
      "UUID":"b7e44f0391824d408732f215a91a0578",
      "ParentID":1,
      "ParentUUID":"8a03fcae8ddfe321b05f00505682315a",
      "Name":"Group 02",
      "IsSystemGroup":false
    }
  ],
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<GetGroupsResponse AccountAlias="UNK" Success="true" Message="Success" StatusCode="0">
  <HardwareGroups>
    <HardwareGroup ID="5" UUID="3d30a6ab6c1243388b7bc966d073e353"
      ParentID="2" ParentUUID="b7e44f0391824d408732f215a91a0578"
      Name="Group 01" IsSystemGroup="false" />
    <HardwareGroup ID="2" UUID="b7e44f0391824d408732f215a91a0578"
      ParentID="1" ParentUUID="8a03fcae8ddfe321b05f00505682315a"
      Name="Group 02" IsSystemGroup="false" />
  </HardwareGroups>
</GetGroupsResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
100 Authentication Failed - You must logon to the API prior to calling this method.

HardwareGroupMaintenance

Enables or disables Maintenance Mode on a Hardware Group.

URL

REST: https://api.ctl.io/REST/Group/HardwareGroupMaintenance/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Group.asmx?op=HardwareGroupMaintenance

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the group. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access groups in your sub accounts. No
UUID String The unique identifier of the Hardware Group. Yes
Enable Boolean Turn Maintenance Mode on or off. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "UUID": "b7e44f0391824d408732f215a91a0578",
  "Enable": true
}

XML

<GroupMaintenanceRequest>
    <AccountAlias>ACCT</AccountAlias>
    <UUID>b7e44f0391824d408732f215a91a0578</UUID>
    <Enable>true</Enable>
</GroupMaintenanceRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
  <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
6 Invalid Operation. Group must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.

PauseHardwareGroup

Pauses the Hardware Group along with all child groups and servers.

URL

REST: https://api.ctl.io/REST/Group/PauseHardwareGroup/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Group.asmx?op=PauseHardwareGroup

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the group. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access groups in your sub accounts. No
UUID String The unique identifier of the Hardware Group to pause. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "UUID": "b7e44f0391824d408732f215a91a0578"
}

XML

<GroupRequest>
    <AccountAlias>ACCT</AccountAlias>
    <UUID>b7e44f0391824d408732f215a91a0578</UUID>
</GroupRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
  <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
6 Invalid Operation. Group must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.

PowerOffHardwareGroup

Powers off the Hardware Group along with all child groups and servers.

URL

REST: https://api.ctl.io/REST/Group/PowerOffHardwareGroup/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Group.asmx?op=PowerOffHardwareGroup

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the group. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access groups in your sub accounts. No
UUID String The unique identifier of the Hardware Group to power off. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "UUID": "b7e44f0391824d408732f215a91a0578"
}

XML

<GroupRequest>
    <AccountAlias>ACCT</AccountAlias>
    <UUID>b7e44f0391824d408732f215a91a0578</UUID>
</GroupRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
6 Invalid Operation. Group must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.

PowerOnHardwareGroup

Power on the Hardware Group along with all child groups and servers.

URL

REST: https://api.ctl.io/REST/Group/PowerOnHardwareGroup/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Group.asmx?op=PowerOnHardwareGroup

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the group. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access groups in your sub accounts. No
UUID String The unique identifier of the Hardware Group to power on. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "UUID": "b7e44f0391824d408732f215a91a0578"
}

XML

<GroupRequest>
    <AccountAlias>ACCT</AccountAlias>
    <UUID>b7e44f0391824d408732f215a91a0578</UUID>
</GroupRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
  <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
6 Invalid Operation. Group must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.

RebootHardwareGroup

Reboot the Hardware Group along with all child groups and servers.

URL

REST: https://api.ctl.io/REST/Group/RebootHardwareGroup/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Group.asmx?op=RebootHardwareGroup

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the group. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access groups in your sub accounts. No
UUID String The unique identifier of the Hardware Group to reboot. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "UUID": "b7e44f0391824d408732f215a91a0578"
}

XML

<GroupRequest>
    <AccountAlias>ACCT</AccountAlias>
    <UUID>b7e44f0391824d408732f215a91a0578</UUID>
</GroupRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
6 Invalid Operation. Group must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.

ResetHardwareGroup

Reset the Hardware Group along with all child groups and servers.

URL

REST: https://api.ctl.io/REST/Group/ResetHardwareGroup/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Group.asmx?op=ResetHardwareGroup

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the group. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access groups in your sub accounts. No
UUID String The unique identifier of the Hardware Group to reset. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "UUID": "b7e44f0391824d408732f215a91a0578"
}

XML

<GroupRequest>
    <AccountAlias>ACCT</AccountAlias>
    <UUID>b7e44f0391824d408732f215a91a0578</UUID>
</GroupRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
6 Invalid Operation. Group must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.

RestoreHardwareGroup

Restores an archived Hardware Group.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Group Actions | Restore Group API.

URL

REST: https://api.ctl.io/REST/Group/RestoreHardwareGroup/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Group.asmx?op=RestoreHardwareGroup

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the group. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access groups in your sub accounts. No
UUID String The unique identifier of the hardware group to restore. Yes
ParentUUID String The unique identifier of the hardware group to become the restored group's parent. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "UUID": "b7e44f0391824d408732f215a91a0578",
  "ParentUUID": "8a03fcae8ddfe321b05f00505682315a"
}

XML

<RestoreGroupRequest>
    <AccountAlias>ACCT</AccountAlias>
    <UUID>b7e44f0391824d408732f215a91a0578</UUID>
    <ParentUUID>8a03fcae8ddfe321b05f00505682315a</ParentUUID>
</RestoreGroupRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
6 Invalid Operation. Group must be in an archived state.
100 Authentication Failed. You must logon to the API prior to calling this method.

ShutdownHardwareGroup

Shutdown the Hardware Group along with all child groups and servers.

URL

REST: https://api.ctl.io/REST/Group/ShutdownHardwareGroup/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Group.asmx?op=ShutdownHardwareGroup

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the group. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access groups in your sub accounts. No
UUID String The unique identifier of the Hardware Group to shutdown. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "UUID": "b7e44f0391824d408732f215a91a0578"
}

XML

<GroupRequest>
    <AccountAlias>ACCT</AccountAlias>
    <UUID>b7e44f0391824d408732f215a91a0578</UUID>
</GroupRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
6 Invalid Operation. Group must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.

AddPublicIPAddress

Maps a public IP Address to a Server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Public IP | Add Public IP Address API.

URL

REST: https://api.ctl.io/REST/Network/AddPublicIPAddress/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Network.asmx?op=AddPublicIPAddress

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the Account the API user is mapped to. Providing this value gives you the ability to manage servers in your sub accounts. No
ServerName String The name of the server. Yes
IPAddress String An existing internal IP Address on the server to use for the mapping. Leaving this blank will assign a new internal IP Address. No
ServerPassword String The existing password, for authentication. Required only if existing internal IP was not provided and new IP must be assigned. Depends
AllowHTTP Boolean The public IP mapping will allow HTTP requests. No
AllowHTTPonPort8080 Boolean The public IP mapping will allow HTTP requests on port 8080. No
AllowHTTPS Boolean The public IP mapping will allow HTTPS requests. No
AllowFTP Boolean The public IP mapping will allow FTP requests. No
AllowFTPS Boolean The public IP mapping will allow FTPS requests. No
AllowSFTP Boolean The public IP mapping will allow SFTP requests. No
AllowSSH Boolean The public IP mapping will allow SSH requests. No
AllowRDP Boolean The public IP mapping will allow RDP requests. No

Examples

JSON

{
  "AccountAlias": "SUB1",
  "ServerName": "WA1T3NWEB01",
  "IPAddress": "1.1.1.1",
  "ServerPassword": "password",
  "AllowHTTP": true,
  "AllowHTTPonPort8080": false,
  "AllowHTTPS": false,
  "AllowFTP": false,
  "AllowFTPS": false,
  "AllowSFTP": false,
  "AllowSSH": false,
  "AllowRDP": false
}

XML

<AddIPAddressRequest>
    <AccountAlias>SUB1</AccountAlias>
    <ServerName>WA1T3NWEB01</ServerName>
    <IPAddress>1.1.1.1</IPAddress>
    <ServerPassword>password</ServerPassword>
    <AllowHTTP>true</AllowHTTP>
    <AllowHTTPonPort8080>false</AllowHTTPonPort8080>
    <AllowHTTPS>false</AllowHTTPS>
    <AllowFTP>false</AllowFTP>
    <AllowFTPS>false</AllowFTPS>
    <AllowSFTP>false</AllowSFTP>
    <AllowSSH>false</AllowSSH>
    <AllowRDP>false</AllowRDP>
</AddIPAddressRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Blueprint Request submitted to perform this operation. You can check the status of this operation by calling the GetRequestStatus method on the Queue API.

Examples

JSON

{
 "Success":true,
 "Message":"Success",
 "StatusCode":0,
 "RequestID":1
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0" RequestID="1" />

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed - You must logon to the API prior to calling this method.
101 Access Denied - Your API user account does not have access to the account specified.
506 Server Name Required.
514 Server Password Required.
1000 The IP Address provided is not configured on the Server.

GetAccountNetworks

Gets the list of Networks mapped to an account in any Data Center.

URL

REST: https://api.ctl.io/REST/Network/GetAccountNetworks/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Network.asmx?op=GetAccountNetworks

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the network. If not provided it will assume the Account the API user is mapped to. Providing this value gives you the ability to get networks in your sub accounts. No
Location String The Network's home datacenter alias. If blank, the account home datacenter location is assumed. No

Examples

JSON

{
  "AccountAlias": "UNK",
  "Location": "UN1"
}

XML

<NetworkRequest>
    <AccountAlias>UNK</AccountAlias>
    <Location>UN1</Location>
</NetworkRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Networks Complex A list of Networks (see below).

Network Attributes

Name Type Description

Name | String | The name of the Network. This value should be used on other API methods that require a network reference. | | Description | String | The friendly name of the network if one has been configured. | | Gateway | IPAddress | The default gateway for the network. |

Examples

JSON

{
  "Networks": [
    {
      "Name": "vlan_1114_10.81.14",
      "Description": "vlan_1114_10.81.14",
      "Gateway": "10.81.14.1",
      "Location": "UN1",
      "AccountAlias": "UNK"
    },
    {
      "Name": "vlan_1241_10.81.141",
      "Description": "vlan_1241_10.81.141",
      "Gateway": "10.81.141.1",
      "Location": "UN1",
      "AccountAlias": "UNK"
    }
  ],
  "Success": true,
  "Message": "Networks successfully queried.",
  "StatusCode": 0
}

XML

<GetNetworksResponse Success="true" Message="Networks successfully queried." StatusCode="0">
    <Networks>
        <Network Name="vlan_1114_10.81.14" Description="vlan_1114_10.81.14" Gateway="10.81.14.1" Location="UN1" AccountAlias="UNK"/>
        <Network Name="vlan_1241_10.81.141" Description="vlan_1241_10.81.141" Gateway="10.81.141.1" Location="UN1" AccountAlias="UNK"/>
    </Networks>
</GetNetworksResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.

GetDeployableNetworks

Gets the list of Networks mapped to an account in any Data Center that are deployable.

URL

REST: https://api.ctl.io/REST/Network/GetDeployableNetworks/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Network.asmx?op=GetDeployableNetworks

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the network. If not provided it will assume the Account the API user is mapped to. Providing this value gives you the ability to get networks in your sub accounts. No
Location String The Network's home datacenter alias. If blank, the account home datacenter location is assumed. No

Examples

JSON

{
  "AccountAlias": "UNK",
  "Location": "UN1"
}

XML

<NetworkRequest>
    <AccountAlias>UNK</AccountAlias>
    <Location>UN1</Location>
</NetworkRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Networks Complex (see below) A list of Network (see below)

Network Attributes

Name Type Description
Name String The name of the Network. This value should be used on other api methods that require a network reference.
Description String The friendly name of the network if one has been configured.
Gateway IPAddress The default gateway for the network.

Examples

JSON

{
  "Networks": [
    {
      "Name": "vlan_1114_10.81.14",
      "Description": "vlan_1114_10.81.14",
      "Gateway": "10.81.14.1",
      "Location": "UN1",
      "AccountAlias": "UNK"
    },
    {
      "Name": "vlan_1241_10.81.141",
      "Description": "vlan_1241_10.81.141",
      "Gateway": "10.81.141.1",
      "Location": "UN1",
      "AccountAlias": "UNK"
    }
  ],
  "Success": true,
  "Message": "Networks successfully queried.",
  "StatusCode": 0
}

XML

<GetNetworksResponse Success="true" Message="Networks successfully queried." StatusCode="0">
    <Networks>
        <Network Name="vlan_1114_10.81.14" Description="vlan_1114_10.81.14" Gateway="10.81.14.1" Location="UN1" AccountAlias="UNK"/>
        <Network Name="vlan_1241_10.81.141" Description="vlan_1241_10.81.141" Gateway="10.81.141.1" Location="UN1" AccountAlias="UNK"/>
    </Networks>
</GetNetworksResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.

GetNetworkDetails

Gets the details for a Network and its IP Addresses.

URL

REST: https://api.ctl.io/REST/Network/GetNetworkDetails/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Network.asmx?op=GetNetworkDetailsResponseMsg

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the network. If not provided it will assume the Account the API user is mapped to. Providing this value gives you the ability to get networks in your sub accounts. No
Location String The Network's home datacenter alias. If blank, the account home datacenter location is assumed. No
Name String The Network name. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Location": "UN1",
  "Name": "vlan_1114_10.81.14"
}

XML

<GetNetworkDetailsRequest>
    <AccountAlias>UNK</AccountAlias>
    <Location>UN1</Location>
    <Name>vlan250_172.21.250</Name>
</GetNetworkDetailsRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
NetworkDetails Complex The NetworkDetails (see below)

NetworkDetails Attributes

Name Type Description
Name String The Network name.
Description String The friendly name of the network if one has been configured.
Gateway String The default gateway for the network.
NetworkMask String The network mask.
Location String The Network's home datacenter alias.
IPAddresses String A list of IPAddress (see below)

IPAddress Attributes

Name Type Description
Address String The IP Address.
AddressType String The type of the IP Address
RIP - Real IP (internal IP configured on the VLAN)
MIP - Mapped IP (external IP configured on the Firewall)
VIP - Virtual IP (external IP configured on the Load Balancer)
IsClaimed Boolean Indicates if the address is claimed or available.
ServerName String The name of the Server using this IP address, if applicable.

Examples

JSON

{
  "Success":true,
  "Message":"Success",
  "StatusCode":0,
  "NetworkDetails":{
    "Name":"vlan250_172.21.250",
    "Description":"vlan250_172.21.250",
    "Gateway":"172.21.250.1",
    "NetworkMask":"255.255.255.0",
    "Location":"WA1",
    "IPAddresses: [
      {
        "Address":"172.21.250.2",
        "AddressType":"RIP",
        "IsClaimed":false,
        "ServerName":""
      },
      {
        "Address":"172.21.250.3",
        "AddressType":"RIP",
        "IsClaimed":true,
        "ServerName":"DEMOFIRST01"
      }
    ]
  }
}

XML

<NetworkDetailsResponse Success="true" Message="Success" StatusCode="0">
    <NetworkDetails Name="vlan250_172.21.250" Description="vlan250_172.21.250"
        Gateway="172.21.250.1" NetworkMask="255.255.255.0" Location="WA1">
        <IPAddresses>
            <IPAddress Address="172.21.250.2" AddressType="RIP"
              IsClaimed="false" ServerName="" />
            <IPAddress Address="172.21.250.3" AddressType="RIP"
              IsClaimed="true" ServerName="DEMOFIRST01" />
        </IPAddresses>
    </NetworkDetails>
</NetworkDetailsResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Network with the specified name cannot be found.
100 Authentication Failed. You must logon to the API prior to calling this method.
1510 Name Required.

GetNetworks

Gets the list of Networks mapped to the account in its Primary Data Center.

URL

REST: https://api.ctl.io/REST/Network/GetNetworks/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Network.asmx?op=GetNetworks

Request

Attributes

Name Type Description Req.
AccountAlias String Short code for a particular account. If not provided, then the API user's account is used. No
Location String The alias of the primary data center. No

Examples

JSON (REST)

{
    "AccountAlias": "1000",
    "Location":"WA1"
}

XML (REST)

<Networks>
    <AccountAlias>1000</AccountAlias>
    <Location>WA1</Location>
</Networks>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
  <soap12:Body>
    <Networks xmlns="http://www.tier3.com/">
        <AccountAlias>1000</AccountAlias>
        <Location>WA1</Location>
    </Networks>
  </soap12:Body>
</soap12:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Networks Complex A list of Network (see below)

Network Attributes

Name Type Description
Name String The name of the Network. This value should be used on other API methods that require a network reference.
Description String The friendly name of the network if one has been configured.
Gateway IPAddress The default gateway for the network.

Examples

JSON

{
  "Networks": [
    {
      "Name": "vlan_1114_10.81.14",
      "Description": "vlan_1114_10.81.14",
      "Gateway": "10.81.14.1",
      "Location": "UN1",
      "AccountAlias": "UNK"
    },
    {
      "Name": "vlan_1241_10.81.141",
      "Description": "vlan_1241_10.81.141",
      "Gateway": "10.81.141.1",
      "Location": "UN1",
      "AccountAlias": "UNK"
    }
  ],
  "Success": true,
  "Message": "Networks successfully queried.",
  "StatusCode": 0
}

XML

<GetNetworksResponse Success="true" Message="Networks successfully queried." StatusCode="0">
    <Networks>
        <Network Name="vlan_1114_10.81.14" Description="vlan_1114_10.81.14" Gateway="10.81.14.1" Location="UN1" AccountAlias="UNK"/>
        <Network Name="vlan_1241_10.81.141" Description="vlan_1241_10.81.141" Gateway="10.81.141.1" Location="UN1" AccountAlias="UNK"/>
    </Networks>
</GetNetworksResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.

UpdatePublicIPAddress

Configures firewall settings on a public IP Address.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Public IP | Update Public IP Address API.

URL

REST: https://api.ctl.io/REST/Network/UpdatePublicIPAddress/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Network.asmx?op=UpdatePublicIPAddress

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the Account the API user is mapped to. Providing this value gives you the ability to manage servers in your sub accounts. No
ServerName String The name of the server. Yes
PublicIPAddress String The public, mapped IP to manage. Yes
AllowHTTP Boolean The public IP mapping will allow HTTP requests. No
AllowHTTPonPort8080 Boolean The public IP mapping will allow HTTP requests on port 8080. No
AllowHTTPS Boolean The public IP mapping will allow HTTPS requests. No
AllowFTP Boolean The public IP mapping will allow FTP requests. No
AllowFTPS Boolean The public IP mapping will allow FTPS requests. No
AllowSFTP Boolean The public IP mapping will allow SFTP requests. No
AllowSSH Boolean The public IP mapping will allow SSH requests. No
AllowRDP Boolean The public IP mapping will allow RDP requests. No

Examples

JSON

{
  "AccountAlias": "SUB1",
  "ServerName": "WA1T3NWEB01",
  "PublicIPAddress": "1.1.1.1",
  "AllowHTTP": true,
  "AllowHTTPonPort8080": false,
  "AllowHTTPS": false,
  "AllowFTP": false,
  "AllowFTPS": false,
  "AllowSFTP": false,
  "AllowSSH": false,
  "AllowRDP": false
}

XML

<UpdateIPAddressRequest>
    <AccountAlias>SUB1</AccountAlias>
    <ServerName>WA1T3NWEB01</ServerName>
    <PublicIPAddress>1.1.1.1</PublicIPAddress>
    <AllowHTTP>true</AllowHTTP>
    <AllowHTTPonPort8080>false</AllowHTTPonPort8080>
    <AllowHTTPS>false</AllowHTTPS>
    <AllowFTP>false</AllowFTP>
    <AllowFTPS>false</AllowFTPS>
    <AllowSFTP>false</AllowSFTP>
    <AllowSSH>false</AllowSSH>
    <AllowRDP>false</AllowRDP>
</UpdateIPAddressRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Blueprint Request submitted to perform this operation. You can check the status of this operation by calling the GetRequestStatus method on the Queue API.

Examples

JSON

{
  "Success": true,
  "Message": "Success",
  "StatusCode": 0,
  "RequestID": 1
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0" RequestID="1" />

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed - You must logon to the API prior to calling this method.
101 Access Denied - Your API user does not have access to the account specified.
506 Server Name Required.
1511 Public IP Address Required.
1000 The Public IP Address provided is not configured on the Server.

Queue API Overview

Many operations performed by the API are actually long running tasks, for example making a change to a firewall or publishing a package. As a result, these tasks are performed asynchronously. All of the operations which need to be processed asynchronously will return a RequestID property in their responses. The Queue API allows you to query into the queue to get the status of your requests using this RequestID. Many of these operations also send email notifications upon completion.

NOTE: This Queue is not the same as the Blueprint Queue. For operations related to the Blueprint Queue, please reference Blueprint/GetDeploymentStatus.

The URL to the SOAP version of the Queue API can be found at https://api.ctl.io/soap/Queue.asmx and the WSDL can be found here.

GetRequestStatus

This method can be used to check the status of any of the long running requests which must be performed asynchronously.

NOTE: This Queue is not the same as the Blueprint Queue. For operations related to the Blueprint Queue, please reference Blueprint/GetDeploymentStatus.

URL

REST: https://api.ctl.io/REST/Queue/GetRequestStatus/<format> (format = XML | JSON)

Request

Attributes

Name Type Description Req.
RequestID Int This is the Request ID returned by any of the operations which Queues an async request to perform any given task. Yes

Examples

XML

<QueueStatusRequest>
    <RequestID>50</RequestID>
</QueueStatusRequest>

JSON

{"RequestID":"50"}

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestDetails Complex An entity containing the details of the request.
RequestID Int The ID of the Request whose details were returned.
CurrentStatus String The current status of the request, valid values are: Not Started, Executing, Succeeded, Failed, and Resumed.
PercentComplete Int The percentage of the work that has been completed on the request.
ProgressDesc String A description of the progress of the request, for example a description of the step currently being executed.
RequestTitle String A description of what the Request was created to do.
StepNumber Int The number of the current step being executed.
StatusDate DateTime The timestamp (GMT) that the most recent status was recorded on the Request.

Examples

XML

<QueueStatusResponse Success="true" Message="Request Status successfully retrieved." StatusCode="0">  
     <RequestDetails RequestID="50" RequestTitle="Creating Server UT1XXLAB01" ProgressDesc="Request completed" StatusDate="2010-05-28T18:48:49.527" PercentComplete="100" CurrentStatus="Succeeded" StepNumber="0" />
</QueueStatusResponse>

JSON

{
  "RequestDetails": {
    "RequestID":50,
    "RequestTitle":"Creating Server UT1XXLAB01",
    "ProgressDesc":"Request completed",
    "StatusDate":"\/Date(1275097729527)\/",
    "PercentComplete":100,
    "CurrentStatus":"Succeeded",
    "StepNumber":0
  },
  "Success":true,
  "Message":"Request Status successfully retrieved.",
  "StatusCode":0
}

Status Codes

Status Code Description
0 Create Server request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
100 Authentication Failed - You must logon to the API prior to calling this method.

ListQueueRequests

This method can be used to get a list of Queued requests and their current status details.

NOTE: This Queue is not the same as the Blueprint Queue. For operations related to the Blueprint Queue, please reference Blueprint/GetDeploymentStatus.

URL

REST: https://api.ctl.io/REST/Queue/ListQueueRequests/<format> (format = XML | JSON)

Request

Attributes

Name Type Description Req.
ItemStatusType Int This value indicates the types of statuses you want to get. Valid values are:
1- All
2 - Pending
3 - Complete
4 - Error
Yes

Examples

XML

<ListQueueItemsRequest>
    <ItemStatusType>1</ItemStatusType>
</ListQueueItemsRequest>

JSON

{
  "ItemStatusType":"1"
}

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Requests List A List of QueueItem entities.
QueueItem Complex An entity containing the details of the request.
RequestID Int The ID of the Request whose details were returned.
CurrentStatus String The current status of the request, valid values are: Not Started, Executing, Succeeded, Failed, and Resumed.
PercentComplete Int The percentage of the work that has been completed on the request.
ProgressDesc String A description of the progress of the request, for example a description of the step currently being executed.
RequestTitle String A description of what the Request was created to do.
StepNumber Int The number of the current step being executed.
StatusDate DateTime The timestamp (GMT) that the most recent status was recorded on the Request.

Examples

XML

<ListQueueItemsResponse Success="true" Message="3 Queue requests were found for your account" StatusCode="0">
    <Requests>
        <QueueItem RequestID="106" RequestTitle="Installing SQL Server on WA1XXLAB01" ProgressDesc="Request completed" StatusDate="2010-06-15T22:31:33.633" PercentComplete="100" CurrentStatus="Succeeded" StepNumber="0" />
        <QueueItem RequestID="105" RequestTitle="Creating Server WA1XXPREM01" ProgressDesc="Request completed" StatusDate="2010-06-15T16:11:03.083" PercentComplete="100" CurrentStatus="Succeeded" StepNumber="0" />
        <QueueItem RequestID="104" RequestTitle="Creating Lab Server WA1XXLAB01" ProgressDesc="Request completed" StatusDate="2010-06-15T15:59:10.76" PercentComplete="100" CurrentStatus="Succeeded" StepNumber="0" />
    </Requests>
</ListQueueItemsResponse>

JSON

{
  "Requests": [
    {
      "RequestID":106,
      "RequestTitle":"Installing SQL Server on WA1XXLAB01",
      "ProgressDesc":"Request completed",
      "StatusDate":"\/Date(1276666293633)\/",
      "PercentComplete":100,
      "CurrentStatus":"Succeeded",
      "StepNumber":0
    },
    {
      "RequestID":105,
      "RequestTitle":"Creating Server WA1XXPREM01",
      "ProgressDesc":"Request completed",
      "StatusDate":"\/Date(1276643463083)\/",
      "PercentComplete":100,
      "CurrentStatus":"Succeeded",
      "StepNumber":0
    },
    {
      "RequestID":104,
      "RequestTitle":"Creating Lab Server WA1XXLAB01",
      "ProgressDesc":"Request completed",
      "StatusDate":"\/Date(1276642750760)\/",
      "PercentComplete":100,
      "CurrentStatus":"Succeeded",
      "StepNumber":0
    }
  ],
  "Success":true,
  "Message":"15 Queue requests were found for your account",
  "StatusCode":0
}

Status Codes

Status Code Description
0 Create Server request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
100 Authentication Failed - You must logon to the API prior to calling this method.
901 The ItemStatus value is invalid.

Archive Server

Archives the server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Server Actions | Archive Server API.

URL

REST: https://api.ctl.io/REST/Server/ArchiveServer/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=ArchiveServer

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to archive servers in your sub accounts. No
Name String The name of the Server to archive. Yes

Examples

JSON

{
  "AccountAlias":"UNK",
  "Name": "SERVER01"
}

XML

<ServerRequest>
    <AccountAlias>UNK</AccountAlias>
    <Name>SERVER01</Name>
</ServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.

Change Password

Updates the Admin/Root password for a Server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Servers | Set Server Credentials API.

URL

REST: https://api.ctl.io/REST/Server/ChangePassword/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=ChangePassword

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the Account the API user is mapped to. Providing this value gives you the ability to manage servers in your sub accounts. No
Name String The name of the server. Yes
CurrentPassword String The existing password, for authentication. Yes
NewPassword String The new password to apply. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "WA1T3NWEB01",
  "CurrentPassword": "password",
  "NewPassword": "newPassword"
}

XML

<ChangePasswordRequest>
    <AccountAlias>UNK</AccountAlias>
    <Name>QA1FMACC554L01</Name>
    <CurrentPassword>password</CurrentPassword>
    <NewPassword>newPassword</NewPassword>
</ChangePasswordRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.

Examples

JSON

{
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<APIResponse Success="true" Message="Success" StatusCode="0" />

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed - You must logon to the API prior to calling this method.
1410 Name Required.
1411 Password Required. Both current and new passwords are required.

Configure Server

Configures the CPU, Memory, Group and additional storage for a Server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Servers | Set Server CPU/Memory, Servers | Set Server Disks, and Servers | Set Server Description/Group APIs.

URL

REST: https://api.ctl.io/REST/Server/ConfigureServer/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=ConfigureServer

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the Account the API user is mapped to. Providing this value gives you the ability to manage servers in your sub accounts. No
Name String The name of the server. Yes
HardwareGroupUUID String The unique identifier of the Hardware Group to add this server to. Yes
Cpu Int The number of processors to configure the server with.Valid values are 1, 2 and 4 Yes
MemoryGB Int The number of GB of memory to configure the server with.Valid values are between 1 and 16. Yes
AdditionalStorageGB Int If greater than 0, the size a new disk to add to the server. No
CustomFields Complex (see below) A list of Custom Fields associated to this server (see below) No

CustomField Attributes

Name Type Description
ID String Unique identifier that is associated with the Account Custom Field. Call Account/GetCustomFields for a list of all custom fields set at the account level.
Value String For Text: Any value; For Option values, call Account/GetCustomFields to see possible values to pass in. Checkbox values should be "true" or "false". tring For Text: Any value; For Option values, call Account/GetCustomFields to see possible values to pass in. Checkbox values should be "true" or "false".

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "WA1T3NWEB01",
  "HardwareGroupUUID": "8a03fbae8ddfe311b05f00505682315a",
  "Cpu": 2,
  "MemoryGB": 4,
  "AdditionalStorageGB": 50,
  "CustomFields": [
    { "ID": "ea97c6e09f604eb689dcdc080114b04d","Value": "A test"},
    { "ID": "b9f454f2ae664998acc3302b24330c5b","Value": "2"},
    { "ID": "d1f12de4ce4b4685b72ba632db0685c6","Value": "true"}
  ]
}

XML

<ConfigureServerRequest>
    <AccountAlias>UNK</AccountAlias>
    <Name>WEB</Name>
    <HardwareGroupUUID>8a03fbae8ddfe311b05f00505682315a</HardwareGroupUUID>
    <Cpu>2</Cpu>
    <MemoryGB>4</MemoryGB>
    <AdditionalStorageGB>50</AdditionalStorageGB>
    <CustomFields ID="ea97c6e09f604eb689dcdc080114b04d" Value="Test text" />
    <CustomFields ID="b9f454f2ae664998acc3302b24330c5b" Value="2" />
    <CustomFields ID="d1f12de4ce4b4685b72ba632db0685c6" Value="true" />
</ConfigureServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID":1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Hardware Group with the specified ID cannot be found. - OR - A Server with the specified Name cannot be found
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed - You must logon to the API prior to calling this method.
500 Invalid Memory Value.
501 Invalid CPU Value.
541 Hardware Group ID Required.
1310 Name Required.
1413 Additional Storage max size exceeded.

Convert Server To Template

Converts the server to a template.

URL

REST: https://api.ctl.io/REST/Server/ConvertServerToTemplate/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=ConvertServerToTemplate

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts. No
Name String The name of the server. Yes
Password String The administrator/root password for the server to convert. Yes
TemplateAlias String The alias for the Template to create. Yes

Examples

JSON

{
  "Name": "WA1T3NWEB01",
  "AccountAlias": "UNK",
  "Password": "password",
  "TemplateAlias": "TEMP"
}

XML

<ConvertServerToTemplateRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>WEB</Name>
    <Password>password</Password>
    <TemplateAlias>TEMP</TemplateAlias>
</ConvertServerToTemplateRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID":1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed - You must logon to the API prior to calling this method.
1410 Name Required.
1411 Password Required.

ConvertTemplateToServer

Converts the Template to a Server.

URL

REST: https://api.ctl.io/REST/Server/ConvertTemplateToServer/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=ConvertTemplateToServer

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts. No
Name String The name of the Template. Yes
Password String The new administrator/root password for the converted server. Yes
HardwareGroupUUID String The unique identifier of the hardware group to add the converted server to. Yes
Network String The name of the network to add the converted server to. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "WA1T3NWEB01",
  "Password": "password",
  "HardwareGroupUUID": "b7e44f0391824d408732f215a91a0578",
  "Network": "VLAN113_172.21.113"

}

XML

<ConvertTemplateToServerRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>WEB</Name>
    <Password>password</Password>
    <HardwareGroupUUID>b7e44f0391824d408732f215a91a0578</HardwareGroupUUID>
    <Network>VLAN113_172.21.113</Network>
</ConvertTemplateToServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request.Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID":1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found - OR - A Hardware Group with the specified ID cannot be found
6 Invalid Operation. Template must be in an active state.
100 Authentication Failed - You must logon to the API prior to calling this method.
1410 Name Required.
1411 Password Required.
1510 Network Required.

Create Server

Creates a new Server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Servers | Create Server API.

URL

REST: https://api.ctl.io/REST/Server/CreateServer/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=CreateServer

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account to own the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to create servers in your sub accounts. No
LocationAlias String The alias of the data center in which to create the server. If not provided, will default to the API user's default data center. No
Template String The name of the template to create the server from Yes
Alias String The alias for the server. Limit 6 charcters Yes
Description String An optional description for the server. If none is supplied the server name will be used. No
HardwareGroupUUID String The unique identifier of the Hardware Group to add this server to. Yes
ServerType Int The type of server to create1 = Standard
2 = Enterprise
Yes
ServiceLevel Int The service level/performance for the underlying data store1 = Premium
2 = Standard
Yes
Cpu Int The number of processors to configure the server with. Yes
MemoryGB Int The number of GB of memory to configure the server with. Yes
ExtraDriveGB Int Required. Represents the size in GB of an additional drive to add to the server. If no additional drive is needed, pass in a 0 value. Yes
PrimaryDns IPAddress The primary DNS to set on the server.If not supplied the default value set on the account will be used. No
SecondaryDns IPAddress The secondary DNS to set on the server.If not supplied the default value set on the account will be used. No
Network String The name of the network to which to deploy the server. If your account has not yet been assigned a network, leave this blank and one will be assigned automatically. If one or more networks are available, the network name is required. No
Password String The desired Admin/Root password. Please note the password must meet the password strength policy. Leave blank to have the system generate a password. No
CustomFields Complex (see below) A list of Custom Fields associated to this server (see below) No

CustomField Attributes

Name Type Description
ID String Unique identifier that is associated with the Account Custom Field. Call Account/GetCustomFields for a list of all custom fields set at the account level.
Value String For Text: Any value; For Option values, call Account/GetCustomFields to see possible values to pass in. Checkbox values should be "true" or "false".

Examples

JSON

{
  "AccountAlias": "UNK",
  "LocationAlias": "UN1",
  "Template": "WIN2K8R2",
  "Alias": "WEB",
  "Description": "Web server",
  "HardwareGroupUUID": "8a03fbae8ddfe311b05f00505682315a",
  "ServerType": 1,
  "ServiceLevel": 2,
  "Cpu": 2,
  "MemoryGB": 4,
  "ExtraDriveGB": 50,
  "PrimaryDns": "4.2.2.2",
  "SecondaryDns": "4.2.2.3",
  "Network": "VLAN113_172.21.113",
  "CustomFields": [
    { "ID": "ea97c6e09f604eb689dcdc080114b04d","Value": "A test"},
    { "ID": "b9f454f2ae664998acc3302b24330c5b","Value": "2"},
    { "ID": "d1f12de4ce4b4685b72ba632db0685c6","Value": "true"}
  ]
}

XML

<CreateServerRequest>
    <AccountAlias>ACCT</AccountAlias>
    <LocationAlias>QA1</LocationAlias>
    <Template>UBUNTU-10-32-TEMPLATE</Template>
    <MemoryGB>1</MemoryGB>
    <Cpu>1</Cpu>
    <HardwareGroupUUID>8a03fbae8ddfe311b05f00505682315a</HardwareGroupUUID>
    <Alias>WHEE</Alias>
    <Description>Web server</Description>
    <ExtraDriveGB>0</ExtraDriveGB>
    <PrimaryDns>172.17.1.26</PrimaryDns>
    <SecondaryDns>172.17.1.27</SecondaryDns>
    <Network>vlan199_172.21.199</Network>
    <Password>[email protected]</Password>
    <ServerType>1</ServerType>
    <ServiceLevel>2</ServiceLevel>
    <CustomFields ID="ea97c6e09f604eb689dcdc080114b04d" Value="Test text" />
    <CustomFields ID="b9f454f2ae664998acc3302b24330c5b" Value="2" />
    <CustomFields ID="d1f12de4ce4b4685b72ba632db0685c6" Value="true" />
</CreateServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID":1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Hardware Group with the specified ID cannot be found.
100 Authentication Failed - You must logon to the API prior to calling this method.
500 Invalid Memory Value.
501 Invalid CPU Value.
502 Alias Required.
503 Alias Length Exceeded.
541 Hardware Group ID Required.
1510 Network Required.
1413 Extra Drive max storage size exceeded.
1414 Password does not meet strength requirements.

Delete Disk

Deletes a disk on a Server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Servers | Set Server Disks API.

URL

REST: https://api.ctl.io/REST/Server/DeleteDisk/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=DeleteDisk

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the Account the API user is mapped to. Providing this value gives you the ability to manage servers in your sub accounts. No
Name String The name of the server. Yes
ScsiBusID String The SCSI bus ID of the disk. Yes
ScsiDeviceID String The SCSI device ID of the disk. Yes
OverrideFailsafes Boolean Set to 'True' to override safety checks that prevent deleting typical primary operating system drives. e.g. SCSI Bus ID 0, SCSI Device ID 0 on Windows (typically C drive) and SCSI Bus ID 0, SCSI Device IDs 0,1,2 on Linux (typically boot, swap and root disks). No

Examples

####

{
  "AccountAlias": "UNK",
  "Name": "WA1UNKWEB01",
  "ScsiBusID": "0",
  "ScsiDeviceID": "1",
  "OverrideFailsafes": false
}

XML

<DeleteDiskRequest>
    <AccountAlias>UNK</AccountAlias>
    <Name>WA1UNKWEB01</Name>
    <ScsiBusID>0</ScsiBusID>
    <ScsiDeviceID>1</ScsiDeviceID>
    <OverrideFailsafes>false</OverrideFailsafes>
</DeleteDiskRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request.Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
    "RequestID":1,
    "Success":true,
    "Message":"Success",
    "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Hardware Group with the specified ID cannot be found. - OR - A Server with the specified Name cannot be found
6 Invalid Operation. Server must not have snapshots.
100 Authentication Failed - You must logon to the API prior to calling this method.
1410 Name Required.
1415 Unknown snapshot state.

Delete Server

Deletes the machine and releases all associated resources.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Servers | Delete Server API.

URL

REST: https://api.ctl.io/REST/Server/DeleteServer/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=DeleteServer

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to delete servers in your sub accounts. No
Name String The name of the Server to delete. Yes

Examples

JSON

{
  "AccountAlias": "ACCT",
  "Name": "DC1ACCTSVR01"
}

XML

<ServerRequest>
    <AccountAlias>UNK</AccountAlias>
    <Name>SERVER01</Name>
</ServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.

Delete Snapshot

Deletes a named snapshot for a specified server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Server Actions | Delete Snapshot API.

URL

REST: https://api.ctl.io/REST/Server/DeleteSnapshot/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=DeleteSnapshot

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts No
Name String The name of the Server. Yes
SnapshotName String The name of the Snapshot to delete Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "1",
  "SnapshotName": "2012-01-01-12:00:00"
}

XML

<SnapshotRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>SERVER01</Name>
    <SnapshotName>2012-01-01-12:00:00</SnapshotName>
</SnapshotRequest>

Response

Attribute

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.

Examples

JSON

{
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<APIResponse Success="true" Message="Success" StatusCode="0"/>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified name cannot be found. -OR- A Snapshot with the specified name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.
1412 SnapshotName required. The name of the snapshot must be specified.

DeleteTemplate

Deletes the Template with the specified name.

URL

REST: https://api.ctl.io/REST/Server/DeleteTemplate/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=DeleteTemplate

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the template. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to delete templates in your sub accounts. No
Name String The name of the Template to delete. Yes

Examples

JSON

{
  "AccountAlias": "ACCT",
  "Name": "TEMPLATENAME01"
}

XML

<ServerRequest>
    <AccountAlias>UNK</AccountAlias>
    <Name>TEMPLATENAME01</Name>
</ServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Template with the specified Name cannot be found.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.

Get All Servers For Account Hierarchy By Modified Date

Gets a deep list of all modified servers for a given account hierarchy within a given data center. Use this operation to get a full list of all servers contained within an account and all its subaccounts. To get all servers that have changed since a certain date, only provide a BeginDate and omit the EndDate.

URL

REST: https://api.ctl.io/REST/Server/GetAllServersForAccountHierarchyByModifiedDates/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=GetAllServersForAccountHierarchyByModifiedDatesMsg

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the servers. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to query a particular sub-account. No
Location String The data center location. Otherwise leave blank and provide HardwareGroupID or let it default to account's primary data center. No
BeginDate DateTime Beginning of date range for querying modified servers. Can be a partial DateTime (e.g. 2013-05-10) or a full DateTime (e.g. 2013:05-10T14:30:12). If date is missing, then the value equals today minus one day. No
EndDate DateTime End of date range for querying modified servers. Can be a partial DateTime (e.g. 2013-05-10) or a full DateTime (e.g. 2013:05-10T14:30:12). If date is missing, then the value is set to the current date time. No

Examples

JSON

{
  "AccountAlias": "ACCT",
  "Location": "WA1",
  "BeginDate": "2013-05-01",
  "EndDate": "2013-06-30"
}

XML

<GetAllServersByModifiedDatesRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Location>WA1</Location>
    <BeginDate>2013-05-01</BeginDate>
    <EndDate>2013-06-30</EndDate>
</GetAllServersByModifiedDatesRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Servers Complex A list of AccountServerGroups, each containing Server Objects

Examples

JSON

{
  "AccountServers":[
    {
      "AccountAlias":"ACT1",
      "Servers":[
        {
          "ID":-1,
          "HardwareGroupID":1197,
          "HardwareGroupUUID":"8a03fbae8ddfe311b05f00505682315a",
          "Location":"WA1",
          "Name":"SERVERDEMO01",
          "Description":"Demo server",
          "DnsName":"",
          "IsTemplate":false,
          "IsHyperscale":false,
          "Cpu":1,
          "MemoryGB":2,
          "DiskCount":1,
          "TotalDiskSpaceGB":24,
          "Status":"UnderConstruction",
          "PowerState":"Stopped",
          "InMaintenanceMode":false,
          "IPAddress":"",
          "ServerType":1,
          "ServiceLevel":2,
          "OperatingSystem":18,
          "DateModified":"\/Date(1347577422943)\/",
          "ModifiedBy":"[email protected]",
          "IPAddresses":[
            {"Address":"142.25.114.13", "AddressType":"RIP"}
          ],
          "CustomFields":null
        }
      ]
    },
    {
      "AccountAlias":"ACT2",
      "Servers":[
        {
          "ID":-1,
          "HardwareGroupID":1595,
          "HardwareGroupUUID":"b9f454f2ae664998acc3302b24330c5b",
          "Location":"WA1",
          "Name":"SERVERDEMO03",
          "Description":"demo server",
          "DnsName":"QA1SSUBSERO9401",
          "IsTemplate":false,
          "IsHyperscale":false,
          "Cpu":1,
          "MemoryGB":1,
          "DiskCount":3,
          "TotalDiskSpaceGB":17,
          "Status":"Active",
          "PowerState":"Started",
          "InMaintenanceMode":false,
          "IPAddress":"173.25.114.15","ServerType":1,"ServiceLevel":2,"OperatingSystem":20,
          "DateModified":"\/Date(1372476852953)\/","ModifiedBy":"[email protected]",
          "IPAddresses":[
            {"Address":"173.25.114.15", "AddressType":"RIP"}
          ],
          "CustomFields":null
        }
      ]
    }
  ],
  "Success":true,
  "Message":"Successfully retrieved deep view of servers",
  "StatusCode":0
}

XML

<GetAccountHierarchyServersResponse Success="true" Message="Successfully retrieved deep view of servers" StatusCode="0">
  <AccountServers>
    <AccountServerGroup AccountAlias="ACT1">
      <Servers>
        <Server
          ID="-1"
          HardwareGroupID="1197"
          HardwareGroupUUID="8a03fbae8ddfe311b05f00505682315a"
          Location="WA1"
          Name="SERVERDEMO01"
          Description="Server1"
          DnsName=""
          IsTemplate="false"
          Cpu="1"
          MemoryGB="2"
          DiskCount="1"
          TotalDiskSpaceGB="24"
          Status="UnderConstruction"
          PowerState="Stopped"
          InMaintenanceMode="false"
          IPAddress=""
          ServerType="1"
          ServiceLevel="2"
          OperatingSystem="18"
          DateModified="2012-09-13T16:03:42.943"
          ModifiedBy="[email protected]">
          <IPAddresses  Address="142.25.114.13"  AddressType="RIP" />
        </Server>
      </Servers>
    </AccountServerGroup>
    <AccountServerGroup AccountAlias="ACT2">
      <Servers>
        <Server
          ID="-1"
          HardwareGroupID="1595"
          HardwareGroupUUID="b9f454f2ae664998acc3302b24330c5b"
          Location="WA1"
          Name="SERVERDEMO03"
          Description="Server 3"
          DnsName="SERVERDEMO03"
          IsTemplate="false"
          Cpu="1"
          MemoryGB="1"
          DiskCount="3"
          TotalDiskSpaceGB="17"
          Status="Active"
          PowerState="Started"
          InMaintenanceMode="false"
          IPAddress="173.25.114.15"
          ServerType="1"
          ServiceLevel="2"
          OperatingSystem="20"
          DateModified="2013-06-28T20:34:12.953"
          ModifiedBy="[email protected]">
        </Server>
      </Servers>
    </AccountServerGroup>
  </AccountServers>
</GetAccountHierarchyServersResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
100 Authentication Failed. You must logon to the API prior to calling this method.

GetAllServers

Gets a deep list of all Servers for a given Hardware Group and its sub groups, or all Servers for a given location.

URL

REST: https://api.ctl.io/REST/Server/GetAllServers/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=GetAllServersResponseMsg

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the servers. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts. No
HardwareGroupUUID String The unique identifier of the Hardware Group, or empty string if providing Location. No
Location String The data center location. Otherwise leave blank and provide HardwareGroupUUID. No

Examples

JSON

{
  "AccountAlias":"ACCT",
  "HardwareGroupUUID": "8a03fbae8ddfe311b05f00505682315a",
  "Location": "WA1"
}

XML

<GetAllServersRequest>
    <AccountAlias>ACCT</AccountAlias>
    <HardwareGroupUUID>8a03fbae8ddfe311b05f00505682315a</HardwareGroupUUID>
    <Location>WA1</Location>
</GetAllServersRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Servers Complex A list of Server Objects

Examples

JSON

{
  "Success":true,
  "Message":"Success",
  "StatusCode":0,
  "Servers": [
    {
      "ID":-1,
      "HardwareGroupID":1,
      "HardwareGroupUUID":"8a03fbae8ddfe311b05f00505682315a",
      "Name":"WA1T3NWEB01",
      "Description":"WA1T3NWEB01",
      "DnsName":"WA1T3NWEB01",
      "IsHyperscale":false,
      "IsTemplate":false,
      "Cpu":2,
      "MemoryGB":4,
      "DiskCount":3,
      "TotalDiskSpaceGB":116,
      "Status":"Active",
      "ServerType":"2",
      "ServiceLevel":"1",
      "OperatingSystem":4,
      "PowerState":"Started",
      "Location":"WA1",
      "IPAddress":"172.0.0.1"
      "IPAddresses:[
        {"Address":"172.0.0.1", "AddressType":1}
      ],
      "CustomFields":[
        { "ID":"9f4150b68d4340cca652a209a4b32c34", "CustomFieldID": -1, "Name": "My Field", "Type": "Text", "Value": "A test"},
        { "ID":"393a0aafd15d47118d57dde0a3d556e3", "CustomFieldID": -1, "Name": "My Field 2", "Type": "Option", "Value": "2"},
        { "ID":"7997a9c0181644c99e490c5c465cf297", "CustomFieldID": -1, "Name": "My Field 3", "Type": "Checkbox", "Value": "true"}
      ]
    },
    {
      "ID":-1,
      "HardwareGroupID":1,
      "HardwareGroupUUID":"8a03fbae8ddfe311b05f00505682315a",
      "Name":"WA1T3NWEB02",
      "Description":"WA1T3NWEB02",
      "DnsName":"WA1T3NWEB02",
      "IsHyperscale":false,
      "IsTemplate":false,
      "Cpu":2,
      "MemoryGB":4,
      "DiskCount":3,
      "TotalDiskSpaceGB":116,
      "Status":"Active",
      "ServerType":"1",
      "ServiceLevel":"2",
      "OperatingSystem":6,
      "PowerState":"Started",
      "Location":"WA1",
      "IPAddress":"172.0.0.2",
      "IPAddresses: [
        {"Address":"172.0.0.2", "AddressType":1}
      ],
      "CustomFields": []
    }
  ]
}

XML

<GetServersResponse Success="true" Message="Successfully retrieved servers" StatusCode="0">
    <Servers>
        <Server ID="-1" HardwareGroupID="1" HardwareGroupUUID="8a03fbae8ddfe311b05f00505682315a"
          Name="WA1T3NWEB01" Description="WA1T3NWEB01" DnsName="WA1T3NWEB01"
          IsHyperscale="false" IsTemplate="false" Cpu="2" MemoryGB="4" DiskCount="3"
          TotalDiskSpaceGB="116" Status="Active" ServerType="1" ServiceLevel="2"
          OperatingSystem="2" PowerState="Started" Location="WA1" IPAddress="172.0.0.1">
            <IPAddresses>
                <IPAddress Address="172.0.0.1" AddressType="RIP" />
            </IPAddresses>
            <CustomFields ID="9f4150b68d4340cca652a209a4b32c34" CustomFieldID="-1" Name="My Field" Type="Text" Value="Test Value" />
            <CustomFields ID="393a0aafd15d47118d57dde0a3d556e3" CustomFieldID="-1" Name="My 2nd Field" Type="Option" Value="Value 3" />
            <CustomFields ID="7997a9c0181644c99e490c5c465cf297" CustomFieldID="-1" Name="My 3rd Field" Type="Checkbox" Value="true" />
        </Server>
        <Server ID="-1" HardwareGroupID="1" HardwareGroupUUID="8a03fbae8ddfe311b05f00505682315a"
          Name="WA1T3NWEB02" Description="WA1T3NWEB02" DnsName="WA1T3NWEB02"
          IsHyperscale="false" IsTemplate="false" Cpu="2" MemoryGB="4" DiskCount="3"
          TotalDiskSpaceGB="116" Status="Active" ServerType="1" ServiceLevel="2"
          OperatingSystem="2" PowerState="Started" Location="WA1" IPAddress="172.0.0.2">
            <IPAddresses>
                <IPAddress Address="172.0.0.2" AddressType="RIP"/>
            </IPAddresses>
            <CustomFields />
       </Server>
    </Servers>
</GetServersResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
100 Authentication Failed. You must logon to the API prior to calling this method.

GetAllServersByModifiedDates

Gets a deep list of all modified Servers for a given Hardware Group and its sub groups, or all Servers for a given location. To get all servers that have changed since a certain date, only provide a BeginDate and omit the EndDate.

URL

REST: https://api.ctl.io/REST/Server/GetAllServersByModifiedDates/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=GetAllServersByModifiedDatesResponseMsg

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the servers. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to query a particular sub-account. No
HardwareGroupUUID String The unique identifier of the Hardware Group, or empty string if providing Location. No
Location String The data center location. Otherwise leave blank and provide HardwareGroupID or let it default to account's primary data center. No
BeginDate DateTime Beginning of date range for querying modified servers. Can be a partial DateTime (e.g. 2013-05-10) or a full DateTime (e.g. 2013:05-10T14:30:12). If date is missing, then the value equals today minus one day. No
EndDate DateTime End of date range for querying modified servers. Can be a partial DateTime (e.g. 2013-05-10) or a full DateTime (e.g. 2013:05-10T14:30:12). If date is missing, then the value is set to the current date time. No

Examples

JSON

{
  "AccountAlias": "ACCT",
  "Location": "WA1",
  "BeginDate": "2013-05-01",
  "EndDate": "2013-06-30"
}

XML

<GetAllServersRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Location>WA1</Location>
    <BeginDate>2013-05-01</BeginDate>
    <EndDate>2013-06-30</EndDate>
</GetAllServersRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Servers Complex A list of Server Objects.

Examples

JSON

{
  "Success":true,
  "Message":"Success",
  "StatusCode":0,
  "Servers": [
    {
      "ID":-1,
      "HardwareGroupID":1,
      "HardwareGroupUUID":"8a03fbae8ddfe311b05f00505682315a",
      "Name":"WA1T3NWEB01",
      "Description":"WA1T3NWEB01",
      "DnsName":"WA1T3NWEB01",
      "IsHyperscale":false,
      "IsTemplate":false,
      "Cpu":2,
      "MemoryGB":4,
      "DiskCount":3,
      "TotalDiskSpaceGB":116,
      "Status":"Active",
      "ServerType":"2",
      "ServiceLevel":"1",
      "OperatingSystem":4,
      "PowerState":"Started",
      "Location":"WA1",
      "IPAddress":"172.0.0.1"
      "IPAddresses:[
        {"Address":"172.0.0.1", "AddressType":1}
      ],
      "CustomFields":[
        { "ID":"9f4150b68d4340cca652a209a4b32c34", "CustomFieldID": -1, "Name": "My Field", "Type": "Text", "Value": "A test"},
        { "ID":"393a0aafd15d47118d57dde0a3d556e3", "CustomFieldID": -1, "Name": "My Field 2", "Type": "Option", "Value": "2"},
        { "ID":"7997a9c0181644c99e490c5c465cf297", "CustomFieldID": -1, "Name": "My Field 3", "Type": "Checkbox", "Value": "true"}
      ]
    }
  ]
}

XML

<GetServersResponse Success="true" Message="Successfully retrieved servers" StatusCode="0">
    <Servers>
        <Server ID="-1" HardwareGroupID="1" HardwareGroupUUID="8a03fbae8ddfe311b05f00505682315a"
          Name="WA1T3NWEB01" Description="WA1T3NWEB01" DnsName="WA1T3NWEB01"
          IsHyperscale="false" IsTemplate="false" Cpu="2" MemoryGB="4" DiskCount="3"
          TotalDiskSpaceGB="116" Status="Active" ServerType="1" ServiceLevel="2"
          OperatingSystem="2" PowerState="Started" Location="WA1" IPAddress="172.0.0.1">
            <IPAddresses>
                <IPAddress Address="172.0.0.1" AddressType="RIP" />
            </IPAddresses>
            <CustomFields ID="9f4150b68d4340cca652a209a4b32c34" CustomFieldID="-1" Name="My Field" Type="Text" Value="Test Value" />
            <CustomFields ID="393a0aafd15d47118d57dde0a3d556e3" CustomFieldID="-1" Name="My 2nd Field" Type="Option" Value="Value 3" />
            <CustomFields ID="7997a9c0181644c99e490c5c465cf297" CustomFieldID="-1" Name="My 3rd Field" Type="Checkbox" Value="true" />
        </Server>
    </Servers>
</GetServersResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
100 Authentication Failed. You must logon to the API prior to calling this method.

GetAllServersForAccountHierarchy

Gets a deep list of all servers for a given account hierarchy within a given data center. Use this operation to get a full list of all servers contained within an account and all its subaccounts.

URL

REST: https://api.ctl.io/REST/Server/GetAllServersForAccountHierarchy/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=GetAllServersForAccountHierarchyMsg

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that contains sub-accounts with servers. If not provided, it will assume the account to which the API user is mapped. No
Location String The data center location. Otherwise leave blank and let it default to account's primary data center. No

Examples

JSON

{
  "AccountAlias": "ACCT",
  "Location": "WA1"
}

XML

<GetAllServersRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Location>WA1</Location>
</GetAllServersRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
AccountServers Complex A list of AccountServerGroups, each containing Server Objects

Examples

JSON

{
  "AccountServers":[
    {
      "AccountAlias":"ACT1",
      "Servers":[
        {
          "ID":-1,
          "HardwareGroupID":1197,
          "HardwareGroupUUID":"8a03fbae8ddfe311b05f00505682315a",
          "Location":"WA1",
          "Name":"SERVERDEMO01",
          "Description":"Demo server",
          "DnsName":"",
          "IsTemplate":false,
          "IsHyperscale":false,
          "Cpu":1,
          "MemoryGB":2,
          "DiskCount":1,
          "TotalDiskSpaceGB":24,
          "Status":"UnderConstruction",
          "PowerState":"Stopped",
          "InMaintenanceMode":false,
          "IPAddress":"",
          "ServerType":1,
          "ServiceLevel":2,
          "OperatingSystem":18,
          "DateModified":"\/Date(1347577422943)\/",
          "ModifiedBy":"[email protected]",
          "IPAddresses":[
            {"Address":"142.25.114.13", "AddressType":"RIP"}
          ],
          "CustomFields":null
        }
      ]
    },
    {
      "AccountAlias":"ACT2",
      "Servers":[
        {
          "ID":-1,
          "HardwareGroupID":1595,
          "HardwareGroupUUID":"b9f454f2ae664998acc3302b24330c5b",
          "Location":"WA1",
          "Name":"SERVERDEMO03",
          "Description":"demo server",
          "DnsName":"QA1SSUBSERO9401",
          "IsTemplate":false,
          "IsHyperscale":false,
          "Cpu":1,
          "MemoryGB":1,
          "DiskCount":3,
          "TotalDiskSpaceGB":17,
          "Status":"Active",
          "PowerState":"Started",
          "InMaintenanceMode":false,
          "IPAddress":"173.25.114.15","ServerType":1,"ServiceLevel":2,"OperatingSystem":20,
          "DateModified":"\/Date(1372476852953)\/","ModifiedBy":"[email protected]",
          "IPAddresses":[
            {"Address":"173.25.114.15", "AddressType":"RIP"}
          ],
          "CustomFields":null
        }
      ]
    }
  ],
  "Success":true,
  "Message":"Successfully retrieved deep view of servers",
  "StatusCode":0
}

XML

<GetAccountHierarchyServersResponse Success="true" Message="Successfully retrieved deep view of servers" StatusCode="0">
  <AccountServers>
    <AccountServerGroup AccountAlias="ACT1">
      <Servers>
        <Server
          ID="-1"
          HardwareGroupID="1197"
          HardwareGroupUUID="8a03fbae8ddfe311b05f00505682315a"
          Location="WA1"
          Name="SERVERDEMO01"
          Description="Server1"
          DnsName=""
          IsTemplate="false"
          Cpu="1"
          MemoryGB="2"
          DiskCount="1"
          TotalDiskSpaceGB="24"
          Status="UnderConstruction"
          PowerState="Stopped"
          InMaintenanceMode="false"
          IPAddress=""
          ServerType="1"
          ServiceLevel="2"
          OperatingSystem="18"
          DateModified="2012-09-13T16:03:42.943"
          ModifiedBy="[email protected]">
          <IPAddresses  Address="142.25.114.13"  AddressType="RIP" />
        </Server>
      </Servers>
    </AccountServerGroup>
    <AccountServerGroup AccountAlias="ACT2">
      <Servers>
        <Server
          ID="-1"
          HardwareGroupID="1595"
          HardwareGroupUUID="b9f454f2ae664998acc3302b24330c5b"
          Location="WA1"
          Name="SERVERDEMO03"
          Description="Server 3"
          DnsName="SERVERDEMO03"
          IsTemplate="false"
          Cpu="1"
          MemoryGB="1"
          DiskCount="3"
          TotalDiskSpaceGB="17"
          Status="Active"
          PowerState="Started"
          InMaintenanceMode="false"
          IPAddress="173.25.114.15"
          ServerType="1"
          ServiceLevel="2"
          OperatingSystem="20"
          DateModified="2013-06-28T20:34:12.953"
          ModifiedBy="[email protected]">
        </Server>
      </Servers>
    </AccountServerGroup>
  </AccountServers>
</GetAccountHierarchyServersResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
100 Authentication Failed. You must logon to the API prior to calling this method.

GetArchiveServers

Gets the list of Archive Servers.

URL

REST: https://api.ctl.io/REST/Server/GetArchiveServers/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=GetArchiveServers

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Servers Complex (see below) A list of Archive Servers (see below)

Archive Server Attributes

Name Type Description
ID Int The ID of the Server.
Deprecated. Value is -1.
Name String The full name of the Server.
Description String The description of the Server as provided on creation.

Examples

JSON

{
  "Success":true,
  "Message":"Success",
  "StatusCode":0,
  "Servers": [
    {"ID":-1, "Name":"WA1T3NWEB01", "Description":"WA1T3NWEB01"},
    {"ID":-1, "Name":"WA1T3NWEB02", "Description":"WA1T3NWEB02"}
   ]
}

XML

<GetServersResponse Success="true" Message="Successfully retrieved servers" StatusCode="0">
    <Servers>
        <Server ID="-1" Name="WA1T3NWEB01" Description="WA1T3NWEB01"/>
        <Server ID="-1" Name="WA1T3NWEB02" Description="WA1T3NWEB02"/>
    </Servers>
</GetServersResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. The archive group could not be found. Please contact support.
100 Authentication Failed. You must logon to the API prior to calling this method.

GetServer

Gets the detail for one server.

URL

REST: https://api.ctl.io/REST/Server/GetServer/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=ServerResponseMsg

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts. No
Name String The name of the server. Yes

Examples

JSON

{ "Name": "WA1T3NWEB01" }

XML

<ServerRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>WA1T3NWEB01</Name>
</ServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Server Complex A Server Object.

Examples

JSON

{
  "Success":true,
  "Message":"Success",
  "StatusCode":0,
  "Servers": [
    {
      "ID":-1,
      "HardwareGroupID":1,
      "HardwareGroupUUID":"8a03fbae8ddfe311b05f00505682315a",
      "Name":"WA1T3NWEB01",
      "Description":"WA1T3NWEB01",
      "DnsName":"WA1T3NWEB01",
      "IsHyperscale":false,
      "IsTemplate":false,
      "Cpu":2,
      "MemoryGB":4,
      "DiskCount":3,
      "TotalDiskSpaceGB":116,
      "Status":"Active",
      "ServerType":"2",
      "ServiceLevel":"1",
      "OperatingSystem":4,
      "PowerState":"Started",
      "Location":"WA1",
      "IPAddress":"172.0.0.1"
      "IPAddresses:[
        {"Address":"172.0.0.1", "AddressType":1}
      ],
      "CustomFields":[
        { "ID":"9f4150b68d4340cca652a209a4b32c34", "CustomFieldID": -1, "Name": "My Field", "Type": "Text", "Value": "A test"},
        { "ID":"393a0aafd15d47118d57dde0a3d556e3", "CustomFieldID": -1, "Name": "My Field 2", "Type": "Option", "Value": "2"},
        { "ID":"7997a9c0181644c99e490c5c465cf297", "CustomFieldID": -1, "Name": "My Field 3", "Type": "Checkbox", "Value": "true"}
      ]
    }
  ]
}

XML

<GetServersResponse Success="true" Message="Successfully retrieved servers" StatusCode="0">
    <Servers>
        <Server ID="-1" HardwareGroupID="1" HardwareGroupUUID="8a03fbae8ddfe311b05f00505682315a"
          Name="WA1T3NWEB01" Description="WA1T3NWEB01" DnsName="WA1T3NWEB01"
          IsHyperscale="false" IsTemplate="false" Cpu="2" MemoryGB="4" DiskCount="3"
          TotalDiskSpaceGB="116" Status="Active" ServerType="1" ServiceLevel="2"
          OperatingSystem="2" PowerState="Started" Location="WA1" IPAddress="172.0.0.1">
            <IPAddresses>
                <IPAddress Address="172.0.0.1" AddressType="RIP" />
            </IPAddresses>
            <CustomFields ID="9f4150b68d4340cca652a209a4b32c34" CustomFieldID="-1" Name="My Field" Type="Text" Value="Test Value" />
            <CustomFields ID="393a0aafd15d47118d57dde0a3d556e3" CustomFieldID="-1" Name="My 2nd Field" Type="Option" Value="Value 3" />
            <CustomFields ID="7997a9c0181644c99e490c5c465cf297" CustomFieldID="-1" Name="My 3rd Field" Type="Checkbox" Value="true" />
        </Server>
    </Servers>
</GetServersResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
100 Authentication Failed. You must logon to the API prior to calling this method.

GetServerCredentials

Gets the credentials for the specified server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Servers | Get Server Credentials API.

URL

REST: https://api.ctl.io/REST/Server/GetServerCredentials/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=GetServerCredentials

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts. No
Name String The Name of the server. Yes

Examples

JSON

{
  "AccountAlias": "ACCT",
  "Name": "DC1ACCTSVR01"
}

XML

<ServerRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>DC1ACCTSVR01</Name>
</ServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Username String The administrator or root user name for the server.
Password String The password associated with the account.

Examples

JSON

{
    "Success":true,
    "Message":"Success",
    "StatusCode":0,
    "Username":"administrator",
    "Password":"password"
}

XML

<GetServerCredentialsResponse Success="true" Message="Successfully retrieved servers" StatusCode="0">
    <Username>administrator</Username>
    <Password>password</Password>
</GetServerCredentialsResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A server with the specified name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Server Name Required.

GetServers

Gets the list of Servers for a given Hardware Group.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Groups | Get Group API.

URL

REST: https://api.ctl.io/REST/Server/GetServers/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=GetServersResponseMsg

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the servers. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts. No
HardwareGroupUUID String The unique identifier of the Hardware Group Yes

Examples

JSON

{
  "AccountAlias": "ACCT",
  "HardwareGroupUUID": "8a03fbae8ddfe311b05f00505682315a"
}

XML

<GetServersRequest>
    <AccountAlias>ACCT</AccountAlias>
    <HardwareGroupUUID>8a03fbae8ddfe311b05f00505682315a</HardwareGroupUUID>
</GetServersRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Servers Complex A list of Server Objects

Examples

JSON

{
  "Success":true,
  "Message":"Success",
  "StatusCode":0,
  "Servers": [
    {
      "ID":-1,
      "HardwareGroupID":1,
      "HardwareGroupUUID":"8a03fbae8ddfe311b05f00505682315a",
      "Name":"WA1T3NWEB01",
      "Description":"WA1T3NWEB01",
      "DnsName":"WA1T3NWEB01",
      "IsHyperscale":false,
      "IsTemplate":false,
      "Cpu":2,
      "MemoryGB":4,
      "DiskCount":3,
      "TotalDiskSpaceGB":116,
      "Status":"Active",
      "ServerType":"2",
      "ServiceLevel":"1",
      "OperatingSystem":4,
      "PowerState":"Started",
      "Location":"WA1",
      "IPAddress":"172.0.0.1"
      "IPAddresses:[
        {"Address":"172.0.0.1", "AddressType":1}
      ],
      "CustomFields":[
        { "ID":"9f4150b68d4340cca652a209a4b32c34", "CustomFieldID": -1, "Name": "My Field", "Type": "Text", "Value": "A test"},
        { "ID":"393a0aafd15d47118d57dde0a3d556e3", "CustomFieldID": -1, "Name": "My Field 2", "Type": "Option", "Value": "2"},
        { "ID":"7997a9c0181644c99e490c5c465cf297", "CustomFieldID": -1, "Name": "My Field 3", "Type": "Checkbox", "Value": "true"}
      ]
    },
    {
      "ID":-1,
      "HardwareGroupID":1,
      "HardwareGroupUUID":"8a03fbae8ddfe311b05f00505682315a",
      "Name":"WA1T3NWEB02",
      "Description":"WA1T3NWEB02",
      "DnsName":"WA1T3NWEB02",
      "IsHyperscale":false,
      "IsTemplate":false,
      "Cpu":2,
      "MemoryGB":4,
      "DiskCount":3,
      "TotalDiskSpaceGB":116,
      "Status":"Active",
      "ServerType":"1",
      "ServiceLevel":"2",
      "OperatingSystem":6,
      "PowerState":"Started",
      "Location":"WA1",
      "IPAddress":"172.0.0.2",
      "IPAddresses: [
        {"Address":"172.0.0.2", "AddressType":1}
      ],
      "CustomFields": []
    }
  ]
}

XML

<GetServersResponse Success="true" Message="Successfully retrieved servers" StatusCode="0">
    <Servers>
        <Server ID="-1" HardwareGroupID="1" HardwareGroupUUID="8a03fbae8ddfe311b05f00505682315a"
          Name="WA1T3NWEB01" Description="WA1T3NWEB01" DnsName="WA1T3NWEB01"
          IsHyperscale="false" IsTemplate="false" Cpu="2" MemoryGB="4" DiskCount="3"
          TotalDiskSpaceGB="116" Status="Active" ServerType="1" ServiceLevel="2"
          OperatingSystem="2" PowerState="Started" Location="WA1" IPAddress="172.0.0.1">
            <IPAddresses>
                <IPAddress Address="172.0.0.1" AddressType="RIP" />
            </IPAddresses>
            <CustomFields ID="9f4150b68d4340cca652a209a4b32c34" CustomFieldID="-1" Name="My Field" Type="Text" Value="Test Value" />
            <CustomFields ID="393a0aafd15d47118d57dde0a3d556e3" CustomFieldID="-1" Name="My 2nd Field" Type="Option" Value="Value 3" />
            <CustomFields ID="7997a9c0181644c99e490c5c465cf297" CustomFieldID="-1" Name="My 3rd Field" Type="Checkbox" Value="true" />
        </Server>
        <Server ID="-1" HardwareGroupID="1" HardwareGroupUUID="8a03fbae8ddfe311b05f00505682315a"
          Name="WA1T3NWEB02" Description="WA1T3NWEB02" DnsName="WA1T3NWEB02"
          IsHyperscale="false" IsTemplate="false" Cpu="2" MemoryGB="4" DiskCount="3"
          TotalDiskSpaceGB="116" Status="Active" ServerType="1" ServiceLevel="2"
          OperatingSystem="2" PowerState="Started" Location="WA1" IPAddress="172.0.0.2">
            <IPAddresses>
                <IPAddress Address="172.0.0.2" AddressType="RIP"/>
            </IPAddresses>
            <CustomFields />
       </Server>
    </Servers>
</GetServersResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
100 Authentication Failed. You must logon to the API prior to calling this method.
541 Hardware Group UUID Required.

GetServersByModifiedDates

Gets the list of Servers for a given Hardware Group and only those that have been updated within a given date range. To get all servers that have changed since a particular date, provide only a BeginDate and omit the EndDate.

URL

REST: https://api.ctl.io/REST/Server/GetServersByModifiedDates/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=GetServersByModifiedDatesResponseMsg

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the servers. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to query a particular sub-account. No
HardwareGroupUUID String The unique identifier of the Hardware Group Yes
BeginDate DateTime Beginning of date range for querying modified servers. Can be a partial DateTime (e.g. 2013-05-10) or a full DateTime (e.g. 2013:05-10T14:30:12). If date is missing, then the value equals today minus one day. No
EndDate DateTime End of date range for querying modified servers. Can be a partial DateTime (e.g. 2013-05-10) or a full DateTime (e.g. 2013:05-10T14:30:12). If date is missing, then the value is set to the current date time. No

Examples

JSON

{
  "AccountAlias": "ACCT",
  "HardwareGroupUUID": "8a03fbae8ddfe311b05f00505682315a",
  "BeginDate": "2013-06-01",
  "EndDate": "2013-06-30"
}

XML

<GetServersRequest>
    <AccountAlias>ACCT</AccountAlias>
    <HardwareGroupUUID>8a03fbae8ddfe311b05f00505682315a</HardwareGroupUUID>
    <BeginDate>2013-06-01</BeginDate>
    <EndDate>2013-06-30</EndDate>
</GetServersRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Servers Complex A list of Server Objects.

Examples

JSON

{
  "Success":true,
  "Message":"Success",
  "StatusCode":0,
  "Servers": [
    {
      "ID":-1,
      "HardwareGroupID":1,
      "HardwareGroupUUID":"8a03fbae8ddfe311b05f00505682315a",
      "Name":"WA1T3NWEB01",
      "Description":"WA1T3NWEB01",
      "DnsName":"WA1T3NWEB01",
      "IsHyperscale":false,
      "IsTemplate":false,
      "Cpu":2,
      "MemoryGB":4,
      "DiskCount":3,
      "TotalDiskSpaceGB":116,
      "Status":"Active",
      "ServerType":"2",
      "ServiceLevel":"1",
      "OperatingSystem":4,
      "PowerState":"Started",
      "Location":"WA1",
      "IPAddress":"172.0.0.1"
      "IPAddresses:[
        {"Address":"172.0.0.1", "AddressType":1}
      ],
      "CustomFields":[
        { "ID":"9f4150b68d4340cca652a209a4b32c34", "CustomFieldID": -1, "Name": "My Field", "Type": "Text", "Value": "A test"},
        { "ID":"393a0aafd15d47118d57dde0a3d556e3", "CustomFieldID": -1, "Name": "My Field 2", "Type": "Option", "Value": "2"},
        { "ID":"7997a9c0181644c99e490c5c465cf297", "CustomFieldID": -1, "Name": "My Field 3", "Type": "Checkbox", "Value": "true"}
      ]
    },
    {
      "ID":-1,
      "HardwareGroupID":1,
      "HardwareGroupUUID":"8a03fbae8ddfe311b05f00505682315a",
      "Name":"WA1T3NWEB02",
      "Description":"WA1T3NWEB02",
      "DnsName":"WA1T3NWEB02",
      "IsHyperscale":false,
      "IsTemplate":false,
      "Cpu":2,
      "MemoryGB":4,
      "DiskCount":3,
      "TotalDiskSpaceGB":116,
      "Status":"Active",
      "ServerType":"1",
      "ServiceLevel":"2",
      "OperatingSystem":6,
      "PowerState":"Started",
      "Location":"WA1",
      "IPAddress":"172.0.0.2",
      "IPAddresses: [
        {"Address":"172.0.0.2", "AddressType":1}
      ],
      "CustomFields": []
    }
  ]
}

XML

<GetServersResponse Success="true" Message="Successfully retrieved servers" StatusCode="0">
    <Servers>
        <Server ID="-1" HardwareGroupID="1" HardwareGroupUUID="8a03fbae8ddfe311b05f00505682315a"
          Name="WA1T3NWEB01" Description="WA1T3NWEB01" DnsName="WA1T3NWEB01"
          IsHyperscale="false" IsTemplate="false" Cpu="2" MemoryGB="4" DiskCount="3"
          TotalDiskSpaceGB="116" Status="Active" ServerType="1" ServiceLevel="2"
          OperatingSystem="2" PowerState="Started" Location="WA1" IPAddress="172.0.0.1">
            <IPAddresses>
                <IPAddress Address="172.0.0.1" AddressType="RIP" />
            </IPAddresses>
            <CustomFields ID="9f4150b68d4340cca652a209a4b32c34" CustomFieldID="-1" Name="My Field" Type="Text" Value="Test Value" />
            <CustomFields ID="393a0aafd15d47118d57dde0a3d556e3" CustomFieldID="-1" Name="My 2nd Field" Type="Option" Value="Value 3" />
            <CustomFields ID="7997a9c0181644c99e490c5c465cf297" CustomFieldID="-1" Name="My 3rd Field" Type="Checkbox" Value="true" />
        </Server>
        <Server ID="-1" HardwareGroupID="1" HardwareGroupUUID="8a03fbae8ddfe311b05f00505682315a"
          Name="WA1T3NWEB02" Description="WA1T3NWEB02" DnsName="WA1T3NWEB02"
          IsHyperscale="false" IsTemplate="false" Cpu="2" MemoryGB="4" DiskCount="3"
          TotalDiskSpaceGB="116" Status="Active" ServerType="1" ServiceLevel="2"
          OperatingSystem="2" PowerState="Started" Location="WA1" IPAddress="172.0.0.2">
            <IPAddresses>
                <IPAddress Address="172.0.0.2" AddressType="RIP"/>
            </IPAddresses>
            <CustomFields />
       </Server>
    </Servers>
</GetServersResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Group with the specified ID cannot be found.
100 Authentication Failed. You must logon to the API prior to calling this method.
541 Hardware Group UUID Required.

GetServerTemplates

Gets the list of Templates available to the account.

URL

REST: https://api.ctl.io/REST/Server/GetServerTemplates/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=GetServerTemplates

Request

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Templates Complex A list of Server Template Objects

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0,
  "Templates":[
    {
      "ID":1001,
      "Name":"CENTOS-6-32",
      "Description":"Cent OS 6 | 32-bit",
      "Cpu":1,
      "MemoryGB":2,
      "DiskCount":1,
      "TotalDiskSpaceGB":8,
      "OperatingSystem":6
    },
    {
      "ID":1002,
      "Name":"WIN2008R2STD-64",
      "Description":"Windows 2008 R2 Standard | 64-bit",
      "Cpu":1,
      "MemoryGB":4,
      "DiskCount":1,
      "TotalDiskSpaceGB":16,
      "OperatingSystem":18
    }
  ]
}

XML

<GetTemplatesResponse Success="true" Message="Successfully retrieved templates" StatusCode="0">
    <Templates>
        <Template ID="1001" Name="CENTOS-6-32" Description="CentOS 6 | 32-bit" Cpu="1"
          MemoryGB="2" DiskCount="1" TotalDiskSpaceGB="8" OperatingSystem="6" />
        <Template ID="1001" Name="WIN2008R2STD-64" Description="Windows 2008 R2 Standard | 64-bit"
          Cpu="1" MemoryGB="4" DiskCount="1" TotalDiskSpaceGB="16" OperatingSystem="18" />
    </Templates>
</GetTemplatesResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.

GetSnapshots

Gets the list of Snapshots associated with the server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Servers | Get Server API.

URL

REST: https://api.ctl.io/REST/Server/GetSnapshots/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=GetSnapshots

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts No
Name String The name of the Server to get Snapshots for. Yes

Examples

JSON

{
  "Name": "DEMOFIRST01",
  "AccountAlias": "UNK"
}

XML

<ServerRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>SERVER01</Name>
</ServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Snapshots Complex (see below) A list of Snapshots (see below).

Snapshot Attributes

Name Type Description
Name String The full name of the Snapshot.
Description String The description of the Snapshot.
DateCreated DateTime The time (in UTC) when the Snapshot was created.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0,
  "Snapshots":[
    {"Name":"2012-01-01-12:00:00","Description":"Snapshot (2012-01-01-12:00:00)","DateCreated":"\/Date(1330047404893)\/"}
  ]
}

XML

<GetSnapshotsResponse Success="true" Message="Successfully retrieved snapshots" StatusCode="0">
    <Snapshots>
        <Snapshot>
            <Name>2012-01-01-12:00:00</Name>
            <Description>Snapshot (2012-01-01-12:00:00)</Description>
            <DateCreated>2012-01-01T12:00:00.000</DateCreated>
        </Snapshot>
    </Snapshots>
</GetSnapshotsResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
5 Resource Not Found. A server with the specified name could not be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name is required.

ListArchiveServers

Lists archived servers.

URL

REST: https://api.ctl.io/REST/Server/ListArchivedServers/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=ListArchivedServers

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts. No
Location String The data center of the servers. No

Examples

JSON

{
  "AccountAlias": "ACCT",
  "Location": "DC1"
}

XML

<ListArchivedServersRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Location>DC1</Location>
</ListArchivedServersRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Servers Complex (see below) A list of Archive Servers (see below)

Archive Server Attributes

Name Type Description
ID Int The ID of the Server.
Deprecated. Value is -1.
Name String The full name of the Server.
Description String The description of the Server as provided on creation.

Examples

JSON

{
  "Success":true,
  "Message":"Success",
  "StatusCode":0,
  "Servers":[
    {"ID":-1,"Name":"WA1T3NWEB01","Description":"WA1T3NWEB01"},
    {"ID":-1,"Name":"WA1T3NWEB02","Description":"WA1T3NWEB02"}
  ]
}

XML

<GetArchiveServersResponse Success="true" Message="Successfully retrieved servers" StatusCode="0">
    <Servers>
        <ArchiveServer ID="-1" Name="WA1T3NWEB01" Description="WA1T3NWEB01"/>
        <ArchiveServer ID="-1" Name="WA1T3NWEB02" Description="WA1T3NWEB02"/>
    </Servers>
</GetArchiveServersResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. The archive group could not be found. Please contact support.
100 Authentication Failed. You must logon to the API prior to calling this method.

ListAvailableServerTemplates

Gets the list of Templates available to the account and location.

URL

REST: https://api.ctl.io/REST/Server/ListAvailableServerTemplates/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=ListAvailableServerTemplates

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts. No
Location String The data center of the server templates. No

Examples

XML

<ListTemplatesRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Location>WA1</Location>
</ListTemplatesRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Templates Complex A list of Server Template Objects

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0,
  "Templates":[
    {
      "ID":1001,"Name":"CENTOS-6-32","Description":"Cent OS 6 | 32-bit",
      "Cpu":1,"MemoryGB":2 "DiskCount":1 "TotalDiskSpaceGB":8 "OperatingSystem":6
    },
    {
      "ID":1002,"Name":"WIN2008R2STD-64","Description":"Windows 2008 R2 Standard | 64-bit",
      "Cpu":1,"MemoryGB":4 "DiskCount":1 "TotalDiskSpaceGB":16 "OperatingSystem":18
    }
   ]
}

XML

<GetTemplatesResponse Success="true" Message="Successfully retrieved templates" StatusCode="0">
    <Templates>
        <Template ID="1001" Name="CENTOS-6-32" Description="CentOS 6 | 32-bit" Cpu="1"
          MemoryGB="2" DiskCount="1" TotalDiskSpaceGB="8" OperatingSystem="6" />
        <Template ID="1001" Name="WIN2008R2STD-64" Description="Windows 2008 R2 Standard | 64-bit"
          Cpu="1" MemoryGB="4" DiskCount="1" TotalDiskSpaceGB="16" OperatingSystem="18" />
    </Templates>
</GetTemplatesResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.

ListDisks

Lists the disks on a Server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Servers | Get Server API.

URL

REST: https://api.ctl.io/REST/Server/ListDisks/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=ListDisks

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the Account the API user is mapped to. Providing this value gives you the ability to manage servers in your sub accounts. No
Name String The name of the server. Yes
QueryGuestDiskNames Boolean Set to 'True' to retrieve disk mount points / drive letters. No

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "WA1T3NWEB01",
  "QueryGuestDiskNames": true
}

XML

<ListDiskRequest>
    <AccountAlias>UNK</AccountAlias>
    <Name>WEB</Name>
    <QueryGuestDiskNames>true</QueryGuestDiskNames>
</ListDiskRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
Disks DiskInfo List of the disks on the server.

Examples

JSON

{
  "Server": "WA1MDAUBU04",
  "HasSnapshot": false,
  "Disks": [
    {
      "Name": "[0:0]",
      "ScsiBusID": "0",
      "ScsiDeviceID": "0",
      "SizeGB": 16
    }
  ],
  "Success": true,
  "Message": "OK",
  "StatusCode": 0
}

XML

<ListDiskResponse Success="true" Message="OK" StatusCode="0" Server="WA1MDAUBU04" HasSnapshot="false">
    <Disks>
        <DiskInfo Name="[0:0]" ScsiBusID="0" ScsiDeviceID="0" SizeGB="16"/>
    </Disks>
</ListDiskResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Hardware Group with the specified ID cannot be found. - OR - A Server with the specified Name cannot be found
6 Invalid Operation. Server must be in an active state, and must not have snapshots.
100 Authentication Failed - You must logon to the API prior to calling this method.
1410 Name Required.
1415 Unknown snapshot state.

PauseServer

Pauses the server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Power Operations | Pause Server API.

URL

REST: https://api.ctl.io/REST/Server/PauseServer/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=PauseServer

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts. No
Name String The name of the Server to pause. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "1"
}

XML

<ServerRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>SERVER01</Name>
</ServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.

PowerOffServer

Powers off the server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Power Operations | Power Off Server API.

URL

REST: https://api.ctl.io/REST/Server/PowerOffServer/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=PowerOffServer

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts No
Name String The name of the Server to power off. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "SERVER01"
}

XML

<ServerRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>SERVER01</Name>
</ServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.

PowerOnServer

Powers on the server (or resumes from a paused state).

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Power Operations | Power On Server API.

URL

REST: https://api.ctl.io/REST/Server/PowerOnServer/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=PowerOnServer

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts No
Name String The name of the Server to power on. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "SERVER01"
}

XML

<ServerRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>SERVER01</Name>
</ServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.

RebootServer

Reboots the server (OS reboot).

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Power Operations | Reboot Server API.

URL

REST: https://api.ctl.io/REST/Server/RebootServer/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=RebootServer

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts No
Name String The name of the Server to reboot. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "SERVER01"
}

XML

<ServerRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>SERVER01</Name>
</ServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.

ResetServer

Resets the server (forced power cycle).

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Power Operations | Reset Server API.

URL

REST: https://api.ctl.io/REST/Server/ResetServer/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=ResetServer

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts No
Name String The name of the Server to reset. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "SERVER01"
}

XML

<ServerRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>SERVER01</Name>
</ServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.

ResizeDisk

Resizes a disk on a Server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Servers | Set Server Disks API.

URL

REST: https://api.ctl.io/REST/Server/ResizeDisk/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=ResizeDisk

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the Account the API user is mapped to. Providing this value gives you the ability to manage servers in your sub accounts. No
Name String The name of the server. Yes
ScsiBusID String The SCSI bus ID of the disk. Yes
ScsiDeviceID String The SCSI device ID of the disk. Yes
ResizeGuestDisk Boolean Set to 'True' to attempt to expand the file system on the disk after the resize. No
NewSizeGB Int The expanded size of the disk. Must be greater than the existing disk size. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "WA1T3NWEB01",
  "ScsiBusID": "0",
  "ScsiDeviceID": "2",
  "ResizeGuestDisk": true,
  "NewSizeGB": 50
}

XML

<ResizeDiskRequest>
    <AccountAlias>UNK</AccountAlias>
    <Name>WEB</Name>
    <ScsiBusID>0</ScsiBusID>
    <ScsiDeviceID>2</ScsiDeviceID>
    <ResizeGuestDisk>true</ResizeGuestDisk>
    <NewSizeGB>50</NewSizeGB>
</ResizeDiskRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request.Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID":1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Hardware Group with the specified ID cannot be found. - OR - A Server with the specified Name cannot be found
6 Invalid Operation. Server must be in an active state, and must not have snapshots.
100 Authentication Failed - You must logon to the API prior to calling this method.
1410 Name Required.
1415 Unknown snapshot state.

RestoreServer

Restores an archived server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Server Actions | Restore Server API.

URL

REST: https://api.ctl.io/REST/Server/RestoreServer/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=RestoreServer

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts. No
Name String The name of the archived Server. Yes
HardwareGroupUUID String The unique identifier of the hardware group to the restore the server to. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "SERVER01",
  "HardwareGroupUUID": "8a03fbae8ddfe311b05f00505682315a"
}

XML

<RestoreServerRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>SERVER01</Name>
    <HardwareGroupUUID>8a03fbae8ddfe311b05f00505682315a</HardwareGroupUUID>
</RestoreServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request.Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found. - OR - A Group with the specified ID cannot be found.
6 Invalid Operation. Server must be in an archived state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.

RevertToSnapshot

Reverts to a named snapshot for a specified server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Server Actions | Revert to Snapshot API.

URL

REST: https://api.ctl.io/REST/Server/RevertToSnapshot/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=RevertToSnapshot

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts No
Name String The name of the Server. Yes
SnapshotName String The name of the Snapshot to revert to. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "1",
  "SnapshotName": "2012-01-01-12:00:00"
}

XML

<SnapshotRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>SERVER01</Name>
    <SnapshotName>2012-01-01-12:00:00</SnapshotName>
</SnapshotRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.

Examples

JSON

{
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<APIResponse Success="true" Message="Success" StatusCode="0"/>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified name cannot be found. - OR - A Snapshot with the specified name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.
1412 SnapshotName required. The name of the snapshot must be specified.

Server Object

Server Attributes

Name Type Description
ID Int The ID of the Server.
Deprecated. Value is -1.
HardwareGroupID Int The legacy ID of the containing Group.
Deprecated. Not available after May 6, 2015. Use UUID instead.
HardwareGroupUUID String The unique identifier of the containing Group.
Name String The full name of the Server.
Description String The description of the Server as provided on creation.
DnsName String The DNS name of the Server.
Cpu Int The number of processors configured on the Server.
MemoryGB Int Total GB of RAM configured on the Server.
DiskCount Int Total number of disks configured on the Server.
TotalDiskSpaceGB Int Total space across all disk configured on the Server.
IsTemplate Bool True if the Server is a template, else False.
IsHyperscale Bool True if the Server is a Hyperscale instance, else False.
Status Json:Int / Xml:String Active, Archived, Deleted, UnderConstruction, QueuedForArchive, QueuedForDelete, or QueuedForRestore
ServerType String The type of server. Standard or Premium
ServiceLevel String The service level/performance for the underlying data store. Standard or Premium
OperatingSystem Int Operating System of the server (see below).
PowerState Json:Int / Xml:String The current power state of the Server.
0 = Stopped
1 = Started
2 = Paused
InMaintenanceMode Boolean Indicates if the Server is in Maintenance Mode.
Location String Home datacenter of the Server.
IPAddress String The primary IP address of the Server.
IPAddresses Complex A list of all IP Addresses assigned to the server (see below)
CustomFields Complex A list of Custom Fields associated to this server (see below)

Operating Systems

Operating System Description
7 CentOS 64-bit
20 Ubuntu 64-bit
21 Debian 64-bit
22 RedHat Enterprise Linux 64-bit
25 RedHat Enterprise Linux 5 64-bit
27 Windows 2012 Datacenter 64-bit
28 Windows 2012 R2 Datacenter 64-Bit
31 Ubuntu 12 64-Bit
33 CentOS 5 64-Bit
35 CentOS 6 64-Bit
36 Debian 6 64-Bit
37 Debian 7 64-Bit
38 RedHat 6 64-Bit
39 CoreOS
40 PXE Boot
41 Ubuntu 14 64-Bit
42 RedHat 7 64-Bit
43 Windows 2008 R2 Standard 64-Bit
44 Windows 2008 R2 Enterprise 64-Bit
45 Windows 2008 R2 Datacenter 64-Bit
46 Windows 2012 R2 Standard 64-bit

IPAddress Attributes

Name Type Description
Address String The IP Address
AddressType Int The type of the IP Address
RIP - Real IP (internal IP configured on the VLAN)
MIP - Mapped IP (external IP configured on the Firewall)
VIP - Virtual IP (external IP configured on the Load Balancer)

CustomField Attributes

Name Type Description
ID String Unique identifier that is associated with the Account Custom Field. Call Account/GetCustomFields for a list of all custom fields set at the account level.
CustomFieldID Int Deprecated. Value is -1. Use CustomFieldType instead.
Name String Name for the Custom Field.
Type String Type of custom field: Text, Option or Checkbox.
Value String For Text: Any value; For Option values, call Account/GetCustomFields to see possible values to pass in. Checkbox values should be "true" or "false".

Examples

JSON

{
  "Servers": [
    {
      "ID": -1,
      "HardwareGroupID": 2158,
      "HardwareGroupUUID": "4c20467154cb4de99a381cc011a20b96"
      "Location": "WA1",
      "Name": "WA1MDAS-STD01",
      "Description": "foo",
      "DnsName": null,
      "IsTemplate": false,
      "Cpu": 0,
      "MemoryGB": 0,
      "DiskCount": 0,
      "TotalDiskSpaceGB": 0,
      "Status": "Archived",
      "PowerState": "Stopped",
      "InMaintenanceMode": false,
      "IPAddress": null,
      "ServerType": 1,
      "ServiceLevel": 2,
      "OperatingSystem": 41,
      "DateModified": "\/Date(1358410186310)\/",
      "ModifiedBy": "CenturyLink Cloud System",
      "IPAddresses": [],
      "CustomFields": []
    },
    {
      "ID": -1,
      "HardwareGroupID": 5199,
      "HardwareGroupUUID": "ea97c6e09f604eb689dcdc080114b04d"
      "Location": "WA1",
      "Name": "WA1MDA2K1202",
      "Description": "2k12",
      "DnsName": "WA1MDA2K1202",
      "IsTemplate": false,
      "Cpu": 1,
      "MemoryGB": 1,
      "DiskCount": 3,
      "TotalDiskSpaceGB": 110,
      "Status": "Active",
      "PowerState": "Stopped",
      "InMaintenanceMode": false,
      "IPAddress": "10.81.14.18",
      "ServerType": 1,
      "ServiceLevel": 2,
      "OperatingSystem": 28,
      "DateModified": "\/Date(1358793254250)\/",
      "ModifiedBy": "[email protected]",
      "IPAddresses": [],
      "CustomFields": []
    }
  ]
}

ServerMaintenance

Enables or disables maintenance mode on a Server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Power Operations | Start Maintenance Mode, and Power Operations | Stop Maintenance ModeAPIs.

URL

REST: https://api.ctl.io/REST/Server/ServerMaintenance/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=ServerMaintenance

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts. No
Name String The name of the Server. Yes
Enable Boolean Turn maintenance mode on or off. Yes

Examples

JSON

{
  "Name": "DEMOFIRST01",
  "AccountAlias": "UNK",
  "Enable": true
}

XML

<ServerMaintenanceRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>DEMOFIRST01</Name>
    <Enable>true</Enable>
</ServerMaintenanceRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.

ServerTemplateObject

Server Template Object

Name Type Description
ID Int The ID of the Template.
Name String The name of the Template.
Description String The description of the Template.
Location String Home datacenter of the Template.
Cpu Int The number of processors configured in the Template.
MemoryGB Int Total GB of RAM configured in the Template.
DiskCount Int Total number of disks configured on the Template.
TotalDiskSpaceGB Int Storage space taken up by the Template.
OperatingSystem Int Operating System of the Template (see below).

Operating Systems

Operating System Description
2 Windows 2003 32-bit
3 Windows 2003 64-bit
4 Windows 2008 32-bit
5 Windows 2008 64-bit
6 CentOS 32-bit
7 CentOS 64-bit
8 Windows XP 32-bit
9 Windows Vista 32-bit
10 Windows Vista 64-bit
11 Windows 7 32-bit
12 Windows 7 64-bit
13 FreeBSD 32-bit
14 FreeBSD 64-bit
15 Windows 2003 Enterprise 32-bit
16 Windows 2003 Enterprise 64-bit
17 Windows 2008 Enterprise 32-bit
18 Windows 2008 Enterprise 64-bit
19 Ubuntu 32-bit
20 Ubuntu 64-bit
21 Debian 64-bit
22 RedHat Enterprise Linux 64-bit
23 Windows 8 64-bit
24 Windows 2012 64-bit
25 RedHat Enterprise Linux 5 64-bit
26 Windows 2008 Datacenter 64-bit
27 Windows 2012 Datacenter 64-bit

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0,
  "Templates":[
    {
      "ID":1001,
      "Name":"CENTOS-6-32",
      "Description":"Cent OS 6 | 32-bit",
      "Cpu":1,
      "MemoryGB":2,
      "DiskCount":1,
      "TotalDiskSpaceGB":8,
      "OperatingSystem":6
    },
    {
      "ID":1002,
      "Name":"WIN2008R2STD-64",
      "Description":"Windows 2008 R2 Standard | 64-bit",
      "Cpu":1,
      "MemoryGB":4,
      "DiskCount":1,
      "TotalDiskSpaceGB":16,
      "OperatingSystem":18
    }
  ]
}

XML

<GetTemplatesResponse Success="true" Message="Successfully retrieved templates" StatusCode="0">
    <Templates>
        <Template ID="1001" Name="CENTOS-6-32" Description="CentOS 6 | 32-bit" Cpu="1"
          MemoryGB="2" DiskCount="1" TotalDiskSpaceGB="8" OperatingSystem="6" />
        <Template ID="1001" Name="WIN2008R2STD-64" Description="Windows 2008 R2 Standard | 64-bit"
          Cpu="1" MemoryGB="4" DiskCount="1" TotalDiskSpaceGB="16" OperatingSystem="18" />
    </Templates>
</GetTemplatesResponse>

ShutdownServer

Shuts down the operating system and then powers off server.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Power Operations | Shut Down Server API.

URL

REST: https://api.ctl.io/REST/Server/ShutdownServer/&lt;format&gt;
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=ShutdownServer

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts No
Name String The name of the Server to shut down. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "SERVER01"
}

XML

<ServerRequest>
  <AccountAlias>ACCT</AccountAlias>
  <Name>SERVER01</Name>
</ServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.

SnapshotServer

Takes a server snapshot.

V2 API Available

There is an equivalent V2 API that should be used instead. Please use the Server Actions | Create Snapshot API.

URL

REST: https://api.ctl.io/REST/Server/SnapshotServer/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/Server.asmx?op=SnapshotServer

Request

Attributes

Name Type Description Req.
AccountAlias String The alias of the account that owns the server. If not provided it will assume the account to which the API user is mapped. Providing this value gives you the ability to access servers in your sub accounts No
Name String The name of the Server to snapshot. Yes

Examples

JSON

{
  "AccountAlias": "UNK",
  "Name": "SERVER01"
}

XML

<ServerRequest>
    <AccountAlias>ACCT</AccountAlias>
    <Name>SERVER01</Name>
</ServerRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RequestID Int The ID of the Queued request. Status of the request can be obtained by calling the Get Deployment Status method.

Examples

JSON

{
  "RequestID:1,
  "Success":true,
  "Message":"Success",
  "StatusCode":0
}

XML

<QueuedItemResponse Success="true" Message="Success" StatusCode="0">
    <RequestID>1</RequestID>
</QueuedItemResponse>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 Resource Not Found. A Server with the specified Name cannot be found.
6 Invalid Operation. Server must be in an active state.
100 Authentication Failed. You must logon to the API prior to calling this method.
1410 Name required. The name parameter must be specified.

SMTP Relay API Overview

The SMTP Relay API provides methods which allow you to manage SMTP Relay settings with CenturyLink Cloud.

The URL to the SOAP version of the SMTP Relay API can be found at https://api.ctl.io/soap/SMTPRelay.asmx and the WSDL can be found here.

CreateAlias

This method will create a new SMTP Relay alias.

URL

REST: https://api.ctl.io/REST/SMTPRelay/CreateAlias/<format> (format = XML | JSON)

Request

Attributes

None.

Examples

JSON

N/A

XML

N/A

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
RelayAlias String The new Relay Alias created for your account.
Password String The password associated with the new Relay Alias.

Examples

XML

<CreateAliasResponse Success="true" Message="Alias has been created." StatusCode="0" RelayAlias="[email protected]" Password="password" />

JSON

{
  "Success":true,
  "Message":"Alias has been disabled.",
  "StatusCode":0,
  "RelayAlias":"[email protected]",
  "Password":"password"
}

Status Codes

Status Code Description
0 CreateAlias request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed - You must logon to the API prior to calling this method.
400 You have reached the SMTP Relay Alias limit set on your account. Contact the support to increase your account limit if you need more.

DisableAlias

This method will disable an existing SMTP Relay alias.

URL

https://api.ctl.io/REST/SMTPRelay/DisableAlias/<format> (format = XML | JSON)

Request

Attributes

Name Type Description Req.
RelayAlias String The the SMTP relay alias to disable. Yes

Examples

JSON

{
  "RelayAlias":"[email protected]"
}

XML

<SMTPUserRequest>
    <RelayAlias>[email protected]</RelayAlias>
</SMTPUserRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.

Examples

JSON

{
  "Success":true,
  "Message":"Alias has been disabled.",
  "StatusCode":0
}

XML

<APIResponse Success="true" Message="Alias has been disabled." StatusCode="0" />

Status Codes

Status Code Description
0 DisableAlias request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 SMTP Relay alias does not exist for your account.
100 Authentication Failed - You must logon to the API prior to calling this method.
401 RelayAlias attribute is required.
402 Relay alias was previously deleted.
403 Relay alias has already been disabled.

Get Invalid Addresses

This method will retrieve the list of invalid address responses that have been saved by the SMTP Relay system related to your domain.

URL

REST: https://api.ctl.io/REST/SMTPRelay/GetInvalidAddresses/<format> (format = XML | JSON)

Request

Attributes

Name Type Description Req.
DomainAlias String The domain to search for as the source of SMTP Relay errors. Yes
StartDate Date This is the starting date to use for the query. This value is inclusive. Yes
EndDate Date This is the ending date to use for the query. This value is inclusive. Yes

Examples

JSON

{
  "DomainAlias":"mydomain",
  "StartDate":"\/Date(1261014726677)\/",
  "EndDate":"\/Date(1261045879270)\/"
}

XML

<InvalidAddressRequest>
  <DomainAlias>mydomain</DomainAlias>
  <StartDate>2010-09-01</StartDate>
  <EndDate>2010-09-02</EndDate>
</InvalidAddressRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
BadAddresses List The List of Bad Address entries containing the details of the rejected aliases.
Address String The destination email address which was rejected.
Reason String The reason reported for the rejection.
Server String The mail server which rejected the email.
LogDate Datetime The date and time the error was logged.

Examples

JSON

{
  "BadAddresses":
  [
    {
      "Address":" [email protected] ",
      "Reason":"mydomain.com sender, but not from mydomain.com-approved relay.",
      "Server":"mail2.xyz.net",
      "LogDate":"\/Date(1261014726677)\/"
    },
    {
      "Address":"[email protected]",
      "Reason":"00.000.000.000 is not allowed to send mail for \[email protected]\u0027 : Reason: mechanism",
      "Server":"mx.mail.com",
      "LogDate":"\/Date(1261045879270)\/"
    }
  ],
  "Success":true,
  "Message":"GetInvalidAddresses completed successfully",
  "StatusCode":0
}

XML

<InvalidAddressResponse Success="true" Message="GetInvalidAddresses completed successfully" StatusCode="0">  
  <BadAddresses>
    <BadAddress>
      <Address>[email protected]</Address>
      <Reason>mydomain.com sender, but not from mydomain.com-approved relay.</Reason>
      <Server>mail2.xyz.net</Server>
      <LogDate>2010-09-01T19:52:06.677</LogDate>
    </BadAddress>
    <BadAddress>
      <Address>[email protected]</Address>
      <Reason>00.000.000.000 is not allowed to send mail for [email protected]' : Reason: mechanism</Reason>
      <Server>mx.mail.com</Server>
      <LogDate>2010-09-02T04:31:19.27</LogDate>
    </BadAddress>
  </BadAddresses>
</InvalidAddressResponse>

Status Codes

Status Code Description
0 GetInvalidAddresses request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
100 Authentication Failed - You must logon to the API prior to calling this method.

ListAliases

This method will list of all SMTP Relay aliases for your account.

URL

https://api.ctl.io/REST/SMTPRelay/ListAliases/<format> (format = XML | JSON)

Request

Attributes

None.

Examples

JSON

N/A

XML

N/A

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
SMTPRelayAliases List A list of RelayAlias objects.
RelayAlias Complex The details of a Relay Alias instance.
Alias String The new Relay Alias created for your account.
Password String The password associated with the new Relay Alias.
Status String The current status of the Relay Alias (expected values are Active, Deleted, and Disabled)

Examples

XML

<ListAliasesResponse Success="true" Message="ListAliases completed successfully" StatusCode="0">
  <SMTPRelayAliases>
    <RelayAlias Alias="[email protected]" Password="password" Status="Active" />
    <RelayAlias Alias="[email protected]" Password="password" Status="Deleted" />
    <RelayAlias Alias="[email protected]" Password="password" Status="Disabled" />
  </SMTPRelayAliases>
</ListAliasesResponse>

JSON

{
  "SMTPRelayAliases":[
    {
      "Alias":"[email protected]",
      "Password":"password",
      "Status":"Active"
    },
    {
      "Alias":"[email protected]",
      "Password":"password",
      "Status":"Deleted"
    },
    {
      "Alias":"[email protected]",
      "Password":"password",
      "Status":"Disabled"
    }
  ],
  "Success":true,
  "Message":"ListAliases completed successfully",
  "StatusCode":0
}

Status Codes

Status Code Description
0 ListAliases request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed - You must logon to the API prior to calling this method.

RemoveAlias

This method will delete an existing SMTP Relay alias.

URL

REST: https://api.ctl.io/REST/SMTPRelay/RemoveAlias/<format> (format = XML | JSON)

Request

Attributes

Name Type Description Req.
RelayAlias String The the SMTP relay alias to delete. Yes

Examples

JSON

{
  "RelayAlias":"[email protected]"
}

XML

<SMTPUserRequest>
    <RelayAlias>[email protected]</RelayAlias>
</SMTPUserRequest>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.

Examples

JSON

{
  "Success":true,
  "Message":"Alias has been deleted.",
  "StatusCode":0
}

XML

<APIResponse Success="true" Message="Alias has been deleted." StatusCode="0" />

Status Codes

Status Code Description
0 RemoveAlias request was successfully processed
2 Unknown Error - An application error occurred processing your request, contact support to resolve the issue.
3 Invalid Request Format. This value indicates that the XML or JSON requests do not match the expected format.
5 SMTP Relay alias does not exist for your account.
100 Authentication Failed - You must logon to the API prior to calling this method.
401 RelayAlias attribute is required.
402 Relay alias has already been deleted.

CreateUser

Create a new user within a given account. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/User/CreateUser/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/User.asmx?op=CreateUser

Request

Attributes

Name Type Description Req.
UserName String Unique username for the new user. Can be an email address or any other string value. Yes
AccountAlias String Short code for a particular account. Yes
EmailAddress String Email address of the new user. Yes
FirstName String First name of the new user. Yes
LastName String Last name of the new user. Yes
AlternateEmailAddress String Additional email address for the user. No
Title String Job title of the user. No
OfficeNumber String Office phone number of the user. No
MobileNumber String Mobile phone number of the user. No
AllowSMSAlerts Boolean Flag determining whether this user can receive SMS messages. No
FaxNumber String Fax number of the user. No
SAMLUserName String String holding the value used during single-sign-on processes. No
Roles Integer[] List of values indicating the roles assigned to this user.
2 = Server Administrator
3 = Billing Manager
8 = DNS Manager
9 = Account Administrator
10 = Account Viewer
12 = Network Manager
13 = Security Manager
14 = Server Operator
15 = Server Scheduler
Yes
TimeZoneID String Time zone of the user. Timezone must be one of the values in the list below, otherwise the value is set to the account"s Timezone. No

Examples

JSON

{
  "UserName":"user3",
  "AccountAlias":"1000",
  "EmailAddress":"[email protected]",
  "FirstName":"Watson",
  "LastName":"User",
  "AlternateEmailAddress":null,
  "Title":null,
  "OfficeNumber":null,
  "MobileNumber":null,
  "AllowSMSAlerts":false,
  "FaxNumber":null,
  "SAMLUserName":null,
  "Roles":[2,8],
  "TimeZoneID":null
}

XML (REST)

<CreateUserRequest>
    <UserName>user3</UserName>
    <AccountAlias>1000</AccountAlias>
    <EmailAddress>[email protected]</EmailAddress>
    <FirstName>Watson</FirstName>
    <LastName>User</LastName>
    <AlternateEmailAddress></AlternateEmailAddress>
    <Title></Title>
    <OfficeNumber></OfficeNumber>
    <MobileNumber></MobileNumber>
    <AllowSMSAlerts>false</AllowSMSAlerts>
    <FaxNumber></FaxNumber>
    <SAMLUserName></SAMLUserName>
    <Roles><int>8</int></Roles>
    <TimeZoneID></TimeZoneID>
</CreateUserRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <CreateUser xmlns="http://www.tier3.com/">
            <request>
                <UserName>user3</UserName>
                <AccountAlias>1000</AccountAlias>
                <EmailAddress>[email protected]</EmailAddress>
                <FirstName>Watson</FirstName>
                <LastName>User</LastName>
                <AlternateEmailAddress></AlternateEmailAddress>
                <Title></Title>
                <OfficeNumber></OfficeNumber>
                <MobileNumber></MobileNumber>
                <AllowSMSAlerts>false</AllowSMSAlerts>
                <FaxNumber></FaxNumber>
                <SAMLUserName></SAMLUserName>
                <Roles><int>8</int></Roles>
                <TimeZoneID></TimeZoneID>
            </request>
        </CreateUser>
    </soap12:Body>
</soap12:Envelope>  

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of "0" indicates success, all non-zero StatusCodes indicate an error state.
UserDetails Complex The details of the newly created user.

UserDetails Attributes

Name Type Description
AccountAlias String Short code for a particular account.
UserName String User name, which is typically the email address.
EmailAddress String Email address for the user.
FirstName String First name of the user.
LastName String Last name of the user.
AlternateEmailAddress String Additional email address for the user.
Title String Job title of the user.
OfficeNumber String Office phone number of the user.
MobileNumber String Mobile phone number of the user.
AllowSMS Boolean Flag indicating whether this user can receive SMS messages.
FaxNumber String Fax number for the user.
SAMLUserName String Name used for single-sign-on process.
TimeZoneID String Time zone that the user resides in.
Roles Integer[] List of values indicating the roles assigned to this user.
2 = Server Administrator
3 = Billing Manager
8 = DNS Manager
9 = Account Administrator
10 = Account Viewer
12 = Network Manager
13 = Security Manager
14 = Server Operator
No

Examples

JSON

{
  "UserDetails":
    {
      "AccountAlias":"1000",
      "UserName":"[email protected]",
      "EmailAddress":"[email protected]",
      "FirstName":"Watson",
      "LastName":"Demo",
      "AlternateEmailAddress":null,
      "Title":null,
      "OfficeNumber":null,
      "MobileNumber":null,
      "AllowSMS":false,
      "FaxNumber":null,
      "SAMLUserName":null,
      "TimeZoneID":"Pacific Standard Time",
      "Roles":[2,8]
    },
  "Success":true,
  "Message":"User successfully created.",
  "StatusCode":0
}

XML (REST)

<UserDetailsResponse Success="true" Message="User successfully created." StatusCode="0">
    <UserDetails AccountAlias="1000"
      UserName="[email protected]"
      EmailAddress="[email protected]"
      FirstName="Watson"
      LastName="Demo"
      AlternateEmailAddress=""
      OfficeNumber=""
      MobileNumber=""
      AllowSMS="false"
      FaxNumber=""
      TimeZoneID="Pacific Standard Time">
        <Roles><int>8</int></Roles>
    </UserDetails>
</UserDetailsResponse>

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <CreateUserResponse xmlns="http://www.tier3.com/">
            <CreateUserResult Success="true" Message="User successfully created." StatusCode="0">
                <UserDetails AccountAlias="1000"
                  UserName="[email protected]"
                  EmailAddress="[email protected]"
                  FirstName="Watson"
                  LastName="Demo"
                  AlternateEmailAddress=""
                  OfficeNumber=""
                  MobileNumber=""
                  AllowSMS="false"
                  FaxNumber=""
                  TimeZoneID="Pacific Standard Time">
                    <Roles><int>8</int></Roles>
                </UserDetails>
            </CreateUserResult>
        </CreateUserResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
5 Resource Not Found. Provided account alias does not exist.
100 Authentication Failed. You must logon to the API prior to calling this method.
1600 Account Alias Required. You must provide an account alias when calling this method.
1700 Email Address Required. You must provide an email address when calling this method.
1701 User Already Exists. You must provide a unique user name when calling this method.
1702 First Name Required. You must provide user"s first name when calling this method.
1703 Last Name Required. You must provide a user"s last name when calling this method.
1706 Invalid User Roles. You must provide a valid user role (2, 8, and 9) when calling this method.
1707 Invalid Email Address. You must provide a valid email address.

Valid Timezone Entries

  • Dateline Standard Time
  • UTC-11
  • Hawaiian Standard Time
  • Alaskan Standard Time
  • Pacific Standard Time (Mexico)
  • Pacific Standard Time
  • US Mountain Standard Time
  • Mountain Standard Time (Mexico)
  • Mountain Standard Time
  • Central America Standard Time
  • Central Standard Time
  • Central Standard Time(Mexico)
  • Canada Central Standard Time
  • SA Pacific Standard Time
  • Eastern Standard Time
  • US Eastern Standard Time
  • Venezuela Standard Time
  • Paraguay Standard Time
  • Atlantic Standard Time
  • Central Brazilian Standard Time
  • SA Western Standard Time
  • Pacific SA Standard Time
  • Newfoundland Standard Time
  • E. South America Standard Time
  • Argentina Standard Time
  • SA Eastern Standard Time
  • Greenland Standard Time
  • Montevideo Standard Time
  • Bahia Standard Time
  • UTC-02
  • Mid-Atlantic Standard Time
  • Azores Standard Time
  • Cape Verde Standard Time
  • Morocco Standard Time
  • UTC
  • GMT Standard Time
  • Greenwich Standard Time
  • W. Europe Standard Time
  • Central Europe Standard Time
  • Romance Standard Time
  • Central European Standard Time
  • W. Central Africa Standard Time
  • Namibia Standard Time
  • Jordan Standard Time
  • GTB Standard Time
  • Middle East Standard Time
  • Egypt Standard Time
  • Syria Standard Time
  • South Africa Standard Time
  • FLE Standard Time
  • Turkey Standard Time
  • Israel Standard Time
  • E. Europe Standard Time
  • Arabic Standard Time
  • Kaliningrad Standard Time
  • Arab Standard Time
  • E. Africa Standard Time
  • Iran Standard Time
  • Arabian Standard Time
  • Azerbaijan Standard Time
  • Russian Standard Time
  • Mauritius Standard Time
  • Georgian Standard Time
  • Caucasus Standard Time
  • Afghanistan Standard Time
  • Pakistan Standard Time
  • West Asia Standard Time
  • India Standard Time
  • Sri Lanka Standard Time
  • Nepal Standard Time
  • Central Asia Standard Time
  • Bangladesh Standard Time
  • Ekaterinburg Standard Time
  • Myanmar Standard Time
  • SE Asia Standard Time
  • N. Central Asia Standard Time
  • China Standard Time
  • North Asia Standard Time
  • Singapore Standard Time
  • W. Australia Standard Time
  • Taipei Standard Time
  • Ulaanbaatar Standard Time
  • North Asia East Standard Time
  • Tokyo Standard Time
  • Korea Standard Time
  • Cen. Australia Standard Time
  • AUS Central Standard Time
  • E. Australia Standard Time
  • AUS Eastern Standard Time
  • West Pacific Standard Time
  • Tasmania Standard Time
  • Yakutsk Standard Time
  • Central Pacific Standard Time
  • Vladivostok Standard Time
  • New Zealand Standard Time
  • UTC+12
  • Fiji Standard Time
  • Magadan Standard Time
  • Kamchatka Standard Time
  • Tonga Standard Time
  • Samoa Standard Time

DeleteUser

Delete a user associated with a given account. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/User/DeleteUser/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/User.asmx?op=DeleteUser

Request

Attributes

Name Type Description Req.
UserName String User name, which is typically the email address. Yes

Examples

JSON

{
  "UserName": "[email protected]"
}

XML (REST)

<UserRequest>
    <UserName>[email protected]</UserName>
</UserRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <DeleteUser xmlns="http://www.tier3.com/">
            <request>
                <UserName>[email protected]</UserName>
            </request>
        </DeleteUser>
    </soap12:Body>
</soap12:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.

Examples

JSON

{
  "Success":true,
  "Message":"User deleted.",
  "StatusCode":0
}

XML (REST)

<APIResponse Success="true" Message="User deleted." StatusCode="0" />

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <DeleteUserResponse xmlns="http://www.tier3.com/">
            <DeleteUserResult Success="true" Message="User deleted." StatusCode="0"/>
        </DeleteUserResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.
1704 Username Required. You must provide a valid user name when calling this method.
1705 User Not Found. Provided user name does not exist.

GetUserDetails

Gets the details of a specific user associated with a given account. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/User/GetUserDetails/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/User.asmx?op=GetUserDetails

Request

Attributes

Name Type Description Req.
AccountAlias String Short code for a particular account. Yes
UserName String User name, which is typically the email address. Yes

Examples

JSON

{
  "AccountAlias": "1000",
  "UserName": "[email protected]"
}

XML (REST)

<GetUserRequest>
    <AccountAlias>RSDA</AccountAlias>
    <UserName>[email protected]</UserName>
</GetUserRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <GetUserDetails xmlns="http://www.tier3.com/">
            <request>
                <AccountAlias>1000</AccountAlias>
                <UserName>[email protected]</UserName>
            </request>
        </GetUserDetails>
    </soap12:Body>
</soap12:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
UserDetails Complex The list of users

UserDetails Attributes

Name Type Description
AccountAlias String Short code for a particular account.
UserName String User name, which is typically the email address.
EmailAddress String Email address for the user.
FirstName String First name of the user.
LastName String Last name of the user.
AlternateEmailAddress String Additional email address for the user.
Title String Job title of the user.
OfficeNumber String Office phone number of the user.
MobileNumber String Mobile phone number of the user.
AllowSMS Boolean Flag indicating whether this user can receive SMS messages.
FaxNumber String Fax number for the user.
SAMLUserName String Name used for single-sign-on process.
TimeZoneID String Time zone that the user resides in.
Status String Status of the user. May be 'Active', 'Disabled' or 'Deleted'.
Roles Integer[] List of values indicating the roles assigned to this user.
2 = Server Administrator
3 = Billing Manager
8 = DNS Manager
9 = Account Administrator
10 = Account Viewer
12 = Network Manager
13 = Security Manager
14 = Server Operator
15 = Server Scheduler

Examples

JSON

{
  "UserDetails": {
    "AccountAlias":"1000",
    "UserName":"[email protected]",
    "EmailAddress":"[email protected]",
    "FirstName":"Ellie",
    "LastName":"User",
    "AlternateEmailAddress":"",
    "Title":"",
    "OfficeNumber":"",
    "MobileNumber":"",
    "AllowSMS":false,
    "FaxNumber":"",
    "SAMLUserName":null,
    "TimeZoneID":"Pacific Standard Time",
    "Roles":[8]
  },
  "Success":true,
  "Message":"User successfully located.",
  "StatusCode":0
}

XML (REST)

<UserDetailsResponse Success="true" Message="User successfully located." StatusCode="0">
    <UserDetails AccountAlias="1000"
      UserName="[email protected]"
      EmailAddress="[email protected]"
      FirstName="Ellie"
      LastName="User"
      AlternateEmailAddress=""
      Title=""
      OfficeNumber=""
      MobileNumber=""
      AllowSMS="false"
      FaxNumber=""
      TimeZoneID="Pacific Standard Time">
        <Roles>
            <int>8</int>
        </Roles>
    </UserDetails>
</UserDetailsResponse>

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <GetUserDetailsResponse xmlns="http://www.tier3.com/">
            <GetUserDetailsResult Success="true" Message="User successfully located." StatusCode="0">
                <UserDetails AccountAlias="1000"
                  UserName="[email protected]"
                  EmailAddress="[email protected]"
                  FirstName="Ellie"
                  LastName="User"
                  AlternateEmailAddress=""
                  Title=""
                  OfficeNumber=""
                  MobileNumber=""
                  AllowSMS="false"
                  FaxNumber=""
                  TimeZoneID="Pacific Standard Time">
                    <Roles>
                        <int>8</int>
                    </Roles>
                </UserDetails>
            </GetUserDetailsResult>
        </GetUserDetailsResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
5 Resource Not Found. Provided account alias does not exist.
100 Authentication Failed. You must logon to the API prior to calling this method.
1600 Account Alias Required. You must provide an account alias when calling this method.
1700 Email Address Required. You must provide an email address when calling this method.
1705 User Not Found. Provided user name does not exist.

GetUsers

Gets all of users assigned to a given account. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/User/GetUsers/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/User.asmx?op=GetUsers

Request

Attributes

Name Type Description Req.
AccountAlias String Short code for a particular account. Yes

Examples

JSON

{
  "AccountAlias": "1000"
}

XML (REST)

<GetUserRequest>
    <AccountAlias>RSDA</AccountAlias>
</GetUserRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <GetUsers xmlns="http://www.tier3.com/">
            <request>
                <AccountAlias>1000</AccountAlias>
            </request>
        </GetUsers>
    </soap12:Body>
</soap12:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
UserDetails Complex The list of users

UserDetails Attributes

Name Type Description
AccountAlias String Short code for a particular account.
UserName String User name, which is typically the email address.
EmailAddress String Email address for the user.
FirstName String First name of the user.
LastName String Last name of the user.
AlternateEmailAddress String Additional email address for the user.
Title String Job title of the user.
OfficeNumber String Office phone number of the user.
MobileNumber String Mobile phone number of the user.
AllowSMS Boolean Flag indicating whether this user can receive SMS messages.
FaxNumber String Fax number for the user.
SAMLUserName String Name used for single-sign-on process.
TimeZoneID String Time zone that the user resides in.
Status String Status of the user. May be 'Active', 'Disabled' or 'Deleted'.
Roles Integer[] List of values indicating the roles assigned to this user.
2 = Server Administrator
3 = Billing Manager
8 = DNS Manager
9 = Account Administrator
10 = Account Viewer
12 = Network Manager
13 = Security Manager
14 = Server Operator
15 = Server Scheduler

Examples

JSON

{
  "Users":[
    {
      "AccountAlias":null,
      "UserName":"[email protected]",
      "EmailAddress":"[email protected]",
      "FirstName":"Ellie",
      "LastName":"User",
      "AlternateEmailAddress":null,
      "Title":"",
      "OfficeNumber":"",
      "MobileNumber":"",
      "AllowSMS":false,
      "FaxNumber":null,
      "TimeZoneID":null,
      "Roles":[8]
    },
    {
      "AccountAlias":null,
      "UserName":"[email protected]",
      "EmailAddress":"[email protected]",
      "FirstName":"Jessie",
      "LastName":"User",
      "AlternateEmailAddress":null,
      "Title":null,
      "OfficeNumber":null,
      "MobileNumber":null,
      "AllowSMS":false,
      "FaxNumber":null,
      "TimeZoneID":null,
      "Roles":[9]
    }
  ],
  "Success":true,
  "Message":"Users successfully located.",
  "StatusCode":0
}

XML (REST)

<UserListResponse Success="true" Message="Users successfully located." StatusCode="0">
    <Users>
        <UserDetails UserName="[email protected]"
          EmailAddress="[email protected]"
          FirstName="Ellie"
          LastName="User"
          Title="" OfficeNumber=""
          MobileNumber=""
          AllowSMS="false">
            <Roles>
                <int>8</int>
            </Roles>
        </UserDetails>
        <UserDetails UserName="[email protected]"
          EmailAddress="[email protected]"
          FirstName="Jessie"
          LastName="User"
          AllowSMS="false">
            <Roles>
                <int>9</int>
            </Roles>
        </UserDetails>
    </Users>
</UserListResponse>

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <GetUsersResponse xmlns="http://www.tier3.com/">
            <GetUsersResult Success="true" Message="Users successfully located." StatusCode="0">
                <Users>
                    <UserDetails UserName="[email protected]"
                      EmailAddress="[email protected]"
                      FirstName="Ellie"
                      LastName="User"
                      Title="" OfficeNumber=""
                      MobileNumber=""
                      AllowSMS="false">
                        <Roles>
                            <int>8</int>
                        </Roles>
                    </UserDetails>
                    <UserDetails UserName="[email protected]"
                      EmailAddress="[email protected]"
                      FirstName="Jessie"
                      LastName="User"
                      AllowSMS="false">
                        <Roles>
                            <int>9</int>
                        </Roles>
                    </UserDetails>
                </Users>
            </GetUsersResult>
        </GetUsersResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
5 Resource Not Found. Provided account alias does not exist.
100 Authentication Failed. You must logon to the API prior to calling this method.
1600 Account Alias Required. You must provide an account alias when calling this method.

SuspendUser

Deactivate a user associated with a given account. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/User/SuspendUser/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/User.asmx?op=SuspendUser

Request

Attributes

Name Type Description Req.
UserName String User name, which is typically the email address. Yes

Examples

JSON

{
  "UserName": "[email protected]"
}

XML (REST)

<UserRequest>
    <UserName>[email protected]</UserName>
</UserRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <SuspendUser xmlns="http://www.tier3.com/">
            <request>
                <UserName>[email protected]</UserName>
            </request>
        </SuspendUser>
    </soap12:Body>
</soap12:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.

Examples

JSON

{"Success":true, "Message":"User suspended.", "StatusCode":0}

XML (REST)

<APIResponse Success="true" Message="User suspended." StatusCode="0" />

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <SuspendUserResponse xmlns="http://www.tier3.com/">
            <SuspendUserResult Success="true" Message="User suspended." StatusCode="0"/>
        </SuspendUserResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.
1704 Username Required. You must provide a valid user name when calling this method.
1705 User Not Found. Provided user name does not exist.

UnsuspendUser

Reactivate a user associated with a given account. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/User/UnsuspendUser/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/User.asmx?op=UnsuspendUser

Request

Attributes

Name Type Description Req.
UserName String User name, which is could be their email address. Yes

Examples

JSON

{
  UserName": "[email protected]"
}

XML (REST)

<UserRequest><UserName>[email protected]</UserName></UserRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <UnsuspendUser xmlns="http://www.tier3.com/">
            <request>
                <UserName>[email protected]</UserName>
            </request>
        </UnsuspendUser>
    </soap12:Body>
</soap12:Envelope>

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.

Examples

JSON

{"Success":true, "Message":"User unsuspended.", "StatusCode":0}

XML (REST)

<APIResponse Success="true" Message="User unsuspended." StatusCode="0" />

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <UnsuspendUserResponse xmlns="http://www.tier3.com/">
            <UnsuspendUserResult Success="true" Message="User unsuspended." StatusCode="0"/>
        </UnsuspendUserResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.
1704 Username Required. You must provide a valid user name when calling this method.
1705 User Not Found. Provided user name does not exist.

UpdateUser

Update a specific user within a given account. Calls to this operation must include an authorization cookie acquired from the Logon operation.

URL

REST: https://api.ctl.io/REST/User/UpdateUser/<format> (format = XML | JSON)
SOAP: https://api.ctl.io/SOAP/User.asmx?op=UpdateUser

Request

Attributes

Name Type Description Req.
UserName String User name, which is typically the email address. Yes
EmailAddress String Email address of the new user. Yes
FirstName String First name of the new user. Yes
Last Name String Last name of the new user. Yes
AlternateEmailAddress String Additional email address for the user. No
Title String Job title of the user. No
OfficeNumber String Office phone number of the user. No
MobileNumber String Mobile phone number of the user. No
AllowSMSAlerts Boolean Flag determining whether this user can receive SMS messages. No
FaxNumber String Fax number of the user. No
SAMLUserName String String holding the value used during single-sign-on processes. No
TimeZoneID String Time zone of the user. Timezone must be one of the values in the list below, otherwise the value is set to the account's Timezone. No
Roles Integer[] List of values indicating the roles assigned to this user.
2 = Server Administrator
3 = Billing Manager
8 = DNS Manager
9 = Account Administrator
10 = Account Viewer
12 = Network Manager
13 = Security Manager
14 = Server Operator
15 = Server Scheduler
No

Examples

JSON

{
  "UserName":"[email protected]",
  "EmailAddress":"[email protected]",
  "FirstName":"Watson",
  "LastName":"User",
  "AlternateEmailAddress":null,
  "Title":"President",
  "OfficeNumber":null,
  "MobileNumber":null,
  "AllowSMSAlerts":false,
  "FaxNumber":null,
  "SAMLUserName":null,
  "Roles":[8],
  "TimeZoneID":null
}

XML (REST)

<UpdateUserRequest>
    <UserName>[email protected]</UserName>
    <EmailAddress>[email protected]</EmailAddress>
    <FirstName>Watson</FirstName>
    <LastName>User</LastName>
    <AlternateEmailAddress></AlternateEmailAddress>
    <Title>President</Title>
    <OfficeNumber></OfficeNumber>
    <MobileNumber></MobileNumber>
    <AllowSMSAlerts>false</AllowSMSAlerts>
    <FaxNumber></FaxNumber>
    <SAMLUserName></SAMLUserName>
    <Roles><int>8</int></Roles>
    <TimeZoneID></TimeZoneID>
</UpdateUserRequest>

XML (SOAP)

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">
    <soap12:Body>
        <UpdateUser xmlns="http://www.tier3.com/">
            <request>
                <UserName>[email protected]</UserName>
                <EmailAddress>[email protected]</EmailAddress>
                <FirstName>Watson</FirstName>
                <LastName>User</LastName>
                <AlternateEmailAddress></AlternateEmailAddress>
                <Title>President</Title>
                <OfficeNumber></OfficeNumber>
                <MobileNumber></MobileNumber>
                <AllowSMSAlerts>false</AllowSMSAlerts>
                <FaxNumber></FaxNumber>
                <SAMLUserName></SAMLUserName>
                <Roles><int>8</int></Roles>
                <TimeZoneID></TimeZoneID>
            </request>
        </UpdateUser>
    </soap12:Body>
</soap12:Envelope>  

Response

Attributes

Name Type Description
Success Boolean True if the request was successful, otherwise False.
Message String A description of the result. The contents of this field does not contain any actionable information, it is purely intended to provide a human readable description of the result.
StatusCode Int This value will help to identify any errors which were encountered while processing the request. The value of '0' indicates success, all non-zero StatusCodes indicate an error state.
UserDetails Complex The details of the updated user.

UserDetails Attributes

Name Type Description
AccountAlias String Short code for a particular account.
UserName String User name, which is typically the email address.
EmailAddress String Email address for the user.
FirstName String First name of the user.
LastName String Last name of the user.
AlternateEmailAddress String Additional email address for the user.
Title String Job title of the user.
OfficeNumber String Office phone number of the user.
MobileNumber String Mobile phone number of the user.
AllowSMS Boolean Flag indicating whether this user can receive SMS messages.
FaxNumber String Fax number for the user.
SAMLUserName String Name used for single-sign-on process.
TimeZoneID String Time zone that the user resides in.
Roles Integer[] List of values indicating the roles assigned to this user.
2 = Server Admin
8 = Domain Admin
9 = Account Admin

Examples

JSON

{
  "UserDetails":
    {
      "AccountAlias":"1000",
      "UserName":"[email protected]",
      "EmailAddress":"[email protected]",
      "FirstName":"Watson",
      "LastName":"Demo",
      "AlternateEmailAddress":null,
      "Title":'President',
      "OfficeNumber":null,
      "MobileNumber":null,
      "AllowSMS":false,
      "FaxNumber":null,
      "SAMLUserName":null,
      "TimeZoneID":"Pacific Standard Time",
      "Roles":[8]
     },
  "Success":true,
  "Message":"User successfully updated.",
  "StatusCode":0
}

XML (REST)

<UserDetailsResponse Success="true" Message="User successfully updated." StatusCode="0">
    <UserDetails AccountAlias="1000"
      UserName="[email protected]"
      EmailAddress="[email protected]"
      FirstName="Watson"
      LastName="Demo"
      AlternateEmailAddress=""
      Title="President"
      OfficeNumber=""
      MobileNumber=""
      AllowSMS="false"
      FaxNumber=""
      TimeZoneID="Pacific Standard Time">
        <Roles><int>8</int></Roles>
    </UserDetails>
</UserDetailsResponse>

XML (SOAP)

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
        <UpdateUserResponse xmlns="http://www.tier3.com/">
            <UpdateUserResult Success="true" Message="User successfully updated." StatusCode="0">
                <UserDetails AccountAlias="1000"
                  UserName="[email protected]"
                  EmailAddress="[email protected]"
                  FirstName="Watson"
                  LastName="Demo"
                  AlternateEmailAddress=""
                  Title="President"
                  OfficeNumber=""
                  MobileNumber=""
                  AllowSMS="false"
                  FaxNumber=""
                  TimeZoneID="Pacific Standard Time">
                    <Roles><int>8</int></Roles>
                </UserDetails>
            </UpdateUserResult>
        </UpdateUserResponse>
    </soap:Body>
</soap:Envelope>

Status Codes

Status Code Description
0 Request was successfully processed
2 Unknown Error. An application error occurred processing your request, contact support to resolve the issue.
100 Authentication Failed. You must logon to the API prior to calling this method.
1700 Email Address Required. You must provide an email address when calling this method.
1702 First Name Required. You must provide user's first name when calling this method.
1703 Last Name Required. You must provide a user's last name when calling this method.
1704 Username Required. You must provide a valid username when calling this method.
1705 User Not Found. This user was not found in the system.
1706 Invalid User Roles. You must provide a valid user role (2, 8, and 9) when calling this method.

Valid Timezone Entries

  • Dateline Standard Time
  • UTC-11
  • Hawaiian Standard Time
  • Alaskan Standard Time
  • Pacific Standard Time (Mexico)
  • Pacific Standard Time
  • US Mountain Standard Time
  • Mountain Standard Time (Mexico)
  • Mountain Standard Time
  • Central America Standard Time
  • Central Standard Time
  • Central Standard Time(Mexico)
  • Canada Central Standard Time
  • SA Pacific Standard Time
  • Eastern Standard Time
  • US Eastern Standard Time
  • Venezuela Standard Time
  • Paraguay Standard Time
  • Atlantic Standard Time
  • Central Brazilian Standard Time
  • SA Western Standard Time
  • Pacific SA Standard Time
  • Newfoundland Standard Time
  • E. South America Standard Time
  • Argentina Standard Time
  • SA Eastern Standard Time
  • Greenland Standard Time
  • Montevideo Standard Time
  • Bahia Standard Time
  • UTC-02
  • Mid-Atlantic Standard Time
  • Azores Standard Time
  • Cape Verde Standard Time
  • Morocco Standard Time
  • UTC
  • GMT Standard Time
  • Greenwich Standard Time
  • W. Europe Standard Time
  • Central Europe Standard Time
  • Romance Standard Time
  • Central European Standard Time
  • W. Central Africa Standard Time
  • Namibia Standard Time
  • Jordan Standard Time
  • GTB Standard Time
  • Middle East Standard Time
  • Egypt Standard Time
  • Syria Standard Time
  • South Africa Standard Time
  • FLE Standard Time
  • Turkey Standard Time
  • Israel Standard Time
  • E. Europe Standard Time
  • Arabic Standard Time
  • Kaliningrad Standard Time
  • Arab Standard Time
  • E. Africa Standard Time
  • Iran Standard Time
  • Arabian Standard Time
  • Azerbaijan Standard Time
  • Russian Standard Time
  • Mauritius Standard Time
  • Georgian Standard Time
  • Caucasus Standard Time
  • Afghanistan Standard Time
  • Pakistan Standard Time
  • West Asia Standard Time
  • India Standard Time
  • Sri Lanka Standard Time
  • Nepal Standard Time
  • Central Asia Standard Time
  • Bangladesh Standard Time
  • Ekaterinburg Standard Time
  • Myanmar Standard Time
  • SE Asia Standard Time
  • N. Central Asia Standard Time
  • China Standard Time
  • North Asia Standard Time
  • Singapore Standard Time
  • W. Australia Standard Time
  • Taipei Standard Time
  • Ulaanbaatar Standard Time
  • North Asia East Standard Time
  • Tokyo Standard Time
  • Korea Standard Time
  • Cen. Australia Standard Time
  • AUS Central Standard Time
  • E. Australia Standard Time
  • AUS Eastern Standard Time
  • West Pacific Standard Time
  • Tasmania Standard Time
  • Yakutsk Standard Time
  • Central Pacific Standard Time
  • Vladivostok Standard Time
  • New Zealand Standard Time
  • UTC+12
  • Fiji Standard Time
  • Magadan Standard Time
  • Kamchatka Standard Time
  • Tonga Standard Time
  • Samoa Standard Time