Table of Contents

  1. Introduction
  2. Autorization
  3. Account Management
  4. User management
    • Check user exists
    • Create user
    • Update user details
    • Change user password
    • Disable user
    • Enable user
  5. Order management
    • Place order for a subscription creation
    • Check hosted domain availability
    • Place order for subsection creation with domain name
    • Place upgrade order to switch a product
    • Place order to change resource quantity
    • Check order status
    • Get details of an order
  6. Subscription Management
    • Get subscription
    • Disable subscription
    • Enable subscription
    • Delete subscription
  7. Service Management
    • Check service user existence
    • Add service user
    • Update service user details
    • Change service user password
    • Disable service user
    • Enable service user
    • List service users

1 Introduction

The goal of this document is to present a set of minimal function to implement a syndication integration with TopCloudXL Services. As a Reseller, you will be able to create your customers and users, place orders, get the subscription information and create service users attached to the subscription.

2 Autorization

For all requests that you will send to the API, you must add to the HTTP header the following information:

Header key Header value description
X-AUTH-USERNAME Username string value provided by TopCloudXL
X-AUTH-PASSWORD Password string value provided by TopCloudXL
X-AUTH-TOKEN Token string value provided by TopCloudXL

3 Account management

3.1 Create account

Role Reseller
HTTP Method POST
URI https://api.topcloudxl.com/1.0/customers
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload
<?xml version="1.0" encoding="utf-8"?>
 <account>
 <name>ACCOUNT_NAME</name>
 <type>RELATION_TYPE</type>
 <address>
 <addressLine1>ADDRESS_LINE_1</addressLine1>
 <addressLine2>ADDRESS_LINE_2</addressLine2>
 <city>CITY</city>
 <state />
 <postalCode>POSTAL_CODE</postalCode>
 <countryCode>ADDRESS_COUNTRY_CODE</countryCode>
 </address>
 <contacts>
 <contact>
 <firstName>FIRST_NAME</firstName>
 <lastName>LAST_NAME</lastName>
 <email>EMAIL_ADDRESS</email>
 <type>CONTACT_TYPE</type>
 <phone>
 <countryCode>PHONE_COUNTRY_CODE</countryCode>
 <areaCode />
 <number>PHONE_NUMBER</number>
 <extension />
 </phone>
 </contact>
 </contacts>
</account>
Item Value
ACCOUNT_NAME The account name for whom the services are created
RELATION_TYPE COMPANY or other type: PERSON
ADDRESS_LINE_1 Address line 1 provided by the client
ADDRESS_LINE_2 Address line 2 provided by the client
CITY City provided by the client
POSTAL_CODE Address postal code provided by the client
ADDRESS_COUNTRY_CODE Address country code (ISO 3166-1 alpha-2 code)
FIRST_NAME First name provided by the client
LAST_NAME Last name provided by the client
EMAIL_ADDRESS Email address provided by the client
CONTACT_TYPE ADMIN or additional contacts with type: {BILLING, TECHNICAL} when RELATION_TYPE is COMPANY. PERSONAL when RELATION_TYPE is PERSON
PHONE_COUNTRY_CODE Country dialing code provided by the client
PHONE_NUMBER Phone number provided by the client
Result payload
<?xml version="1.0" encoding="utf-8"?>
<account>
 <id>ACCOUNT_ID </id>
 <status>ACCOUNT_STATUS</status>
 </account>

3.2 Update account details

Role Reseller or Cusrtomer
HTTP Method PUT
URI https://api.topcloudxl.com/1.0/my/account
URI https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload
<?xml version="1.0" encoding="utf-8"?>
 <account>
 <name>ACCOUNT_NAME</name>
 <address>
 <addressLine1>ADDRESS_LINE_1</addressLine1>
 <addressLine2>ADDRESS_LINE_2</addressLine2>
 <city>CITY</city>
 <state />
 <postalCode>POSTAL_CODE</postalCode>
 <countryCode>ADDRESS_COUNTRY_CODE</countryCode>
 </address>
 <contacts>
 <contact>
 <firstName>FIRST_NAME</firstName>
 <lastName>LAST_NAME</lastName>
 <email>EMAIL_ADDRESS</email>
 <type>CONTACT_TYPE</type>
 <phone>
 <countryCode>PHONE_COUNTRY_CODE</countryCode>
 <areaCode />
 <number>PHONE_NUMBER</number>
 <extension />
 </phone>
 </contact>
 </contacts>
</account>
Item Value
ACCOUNT_NAME The account name for whom the services are created
ADDRESS_LINE_1 Address line 1 provided by the client
ADDRESS_LINE_2 Address line 2 provided by the client
CITY City provided by the client
POSTAL_CODE Address postal code provided by the client
ADDRESS_COUNTRY_CODE Address country code (ISO 3166-1 alpha-2 code)
FIRST_NAME First name provided by the client
LAST_NAME Last name provided by the client
EMAIL_ADDRESS Email address provided by the client
CONTACT_TYPE ADMIN or additional contacts with type: {BILLING, TECHNICAL} when RELATION_TYPE is COMPANY. PERSONAL when RELATION_TYPE is PERSON
PHONE_COUNTRY_CODE Country dialing code provided by the client
PHONE_NUMBER Phone number provided by the client
Result payload
<?xml version="1.0" encoding="utf-8"?>
<account>
 <id>ACCOUNT_ID </id>
 <status>ACCOUNT_STATUS</status>
 </account>

3.3 Disable account

Role Reseller
HTTP Method PUT
URI https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/disable
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No payload is needed
Item Value
ACCOUNT_ID Account identifier provided by CSL
Result payload
<?xml version="1.0" encoding="utf-8"?>
<account>
 <id>ACCOUNT_ID </id>
 <status>ACCOUNT_STATUS</status>
 </account>

3.4 Enable account

Role Reseller
HTTP Method PUT
URI https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/enable
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No payload is needed
Item Value
ACCOUNT_ID Account identifier provided by CSL
Result payload
<?xml version="1.0" encoding="utf-8"?>
<account>
 <id>ACCOUNT_ID </id>
 <status>ACCOUNT_STATUS</status>
 </account>

4 User management

4.1 Check user exists

Role Reseller or Customer
HTTP Method GET
URI https://api.topcloudxl.com/1.0/user/USER_NAME/exists
HTTP Header r See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <user>
 <status>USERNAME_STAUS</status>
 </user>

URI Encoding:

Status Description
USER_NAME The username must be URI encoded in order to be correctly included within the URL query string. The API will by default decode the username value and proceed with the check.

When checking the username availability, you can have one of statuses defined in the table below.

Status Description
AVAILABLE The username is available and can be used.
TAKEN The username is not available and must not be used.

4.2 Create user

Role Reseller or Customer
HTTP Method POST
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/users
URI Customer https://api.topcloudxl.com/1.0/my/users
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload
<?xml version="1.0" encoding="utf-8"?>
 <user>
 <username>$USER_NAME</username>
 <password>$USER_PASSWORD</password>
 <address>
 <addressLine1>ADDRESS_LINE_1</addressLine1>
 <addressLine2>ADDRESS_LINE_2</addressLine2>
 <city>CITY</city>
 <state />
 <postalCode>POSTAL_CODE</postalCode>
 <countryCode>ADDRESS_COUNTRY_CODE</countryCode>
 </address>
 <contact>
 <firstName>FIRST_NAME</firstName>
 <lastName>LAST_NAME</lastName>
 <email>EMAIL_ADDRESS</email>
 <phone>
 <countryCode>PHONE_COUNTRY_CODE</countryCode>
 <areaCode />
 <number>PHONE_NUMBER</number>
 <extension />
 </phone>
 </contact>
</user>
Item Value
USER_NAME Username provided by the client API
USER_PASSWORD Password provided by the client API
ADDRESS_LINE_1 Address line 1 provided by the client API
ADDRESS_LINE_2 Address line 2 provided by the client API
CITY City provided by the client API
POSTAL_CODE Address postal code provided by the client API
ADDRESS_COUNTRY_CODE E Address country code (ISO 3166-1 alpha-2 code)
FIRST_NAME First name provided by the client API
LAST_NAME Last name provided by the client API
EMAIL_ADDRESS Email address provided by the client API
PHONE_COUNTRY_CODE Country dialing code provided by the client API
PHONE_NUMBER Phone number provided by the client API
Result payload
<?xml version="1.0"encoding="utf-8"?>
 <user>
 <id>USER_ID</id>
 <status>USER_STATUS</status>
 </user>

4.3 Update user details

Role Reseller or Customer
HTTP Method PUT
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/users/USER_ID
URI Customer https://api.topcloudxl.com/1.0/my/users/USER_ID
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload
<?xml version="1.0" encoding="utf-8"?>
 <user>
 <username>USER_NAME</username>
 <password>USER_PASSWORD</password>
 <address>
 <addressLine1>ADDRESS_LINE_1</addressLine1>
 <addressLine2>ADDRESS_LINE_2</addressLine2>
 <city>CITY</city>
 <state />
 <postalCode>POSTAL_CODE</postalCode>
 <countryCode>ADDRESS_COUNTRY_CODE</countryCode>
 </address>
 <contact>
 <firstName>FIRST_NAME</firstName>
 <lastName>LAST_NAME</lastName>
 <email>EMAIL_ADDRESS</email>
 <phone>
 <countryCode>PHONE_COUNTRY_CODE</countryCode>
 <areaCode />
 <number>PHONE_NUMBER</number>
 <extension />
 </phone>
 </contact>
</user>
Item Value
USER_NAME Username provided by the client API
ADDRESS_LINE_1 Address line 1 provided by the client API
ADDRESS_LINE_2 Address line 2 provided by the client API
CITY City provided by the client API
POSTAL_CODE Address postal code provided by the client API
ADDRESS_COUNTRY_CODE Address country code (ISO 3166-1 alpha-2 code)
FIRST_NAME First name provided by the client API
LAST_NAME Last name provided by the client API
EMAIL_ADDRESS Email address provided by the client API
PHONE_COUNTRY_CODE Country dialing code provided by the client API
PHONE_NUMBER Phone number provided by the client API
Result payload
<?xml version="1.0"encoding="utf-8"?>
 <user>
 <id>USER_ID</id>
 <passwordStatus>USER_PASSWORD_STATUS</passwordStatus>
 </user>

4.4 Change user password

Role Reseller or Customer
HTTP Method PUT
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/users/USER_ID
URI Customer https://api.topcloudxl.com/1.0/my/users/USER_ID/password
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Result payload
<?xml version="1.0"encoding="utf-8"?>
 <user>
 <id>USER_ID</id>
 <oldPassword>USER_OLD_PASSWORD</oldPassword>
 <newPassword>USER_NEW_PASSWORD</newPassword>
 </user>
Item Value
ACCOUNT_ID The account identifier containing the user to enable
USER_ID The user identifier that needs to be enabled
Result payload
<?xml version="1.0"encoding="utf-8"?>
 <user>
 <id>USER_ID</id>
 <passwordStatus>USER_PASSWORD_STATUS</passwordStatus>
 </user>

When changing the password, you can have one of statuses defined in the table below.

Status Description
CHANGED The password is changed successfully and can be used.
NOT_CHANGED
<?xml version="1.0"encoding="utf-8"?>
 <user>
 <id>USER_ID</id>
 <passwordStatus>USER_PASSWORD_STATUS</passwordStatus>
 <reason>REASON_NOT_CHANGED_PASSWORD_MESSAGE</reason>
</user>

4.5 Disable user

Role Reseller or Customer
HTTP Method PUT
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/users/USER_ID
URI Customer https://api.topcloudxl.com/1.0/my/users/USER_ID/disable
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No payload is needed
Item Value
ACCOUNT_ID The account identifier containing the user to disable
USER_ID The user identifier that needs to be disabled
Result payload
<?xml version="1.0"encoding="utf-8"?>
 <user>
 <id>USER_ID</id>
 <status>USER_STATUS</status>
 </user>

4.6 Enable user

Role Reseller or Customer
HTTP Method PUT
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/users/USER_ID
URI Customer https://api.toplcloudxl.com/1.0/my/users/USER_ID/enable
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No payload is needed
Item Value
ACCOUNT_ID The account identifier containing the user to enable
USER_ID The user identifier that needs to be enabled
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <domain>
 <status>DOMAIN_STATUS</status>
 </domain>

5 Order Management

5.1 Place order for a subscription creation

Role Reseller or Customer
HTTP Method POST
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/orders
URI Customer https://api.topcloudxl.com/1.0/my/orders
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload
<?xml version="1.0" encoding="utf-8"?>
 <order>
 <items>
 <item>
 <type>ORDER_ITEM_TYPE</type>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 </subscription>
 <product>
 <id>PRODUCT_ID</id></product>
 <period>
 <id>PERIOD_ID</id></period>
 </item>
 </items>
 </order>
Item Value
ORDER_ITEM_TYPE CREATE
PRODUCT_ID Product identifier provided by CSL (use REST API call: GET /customers/products)
PERIOD_ID Period identifier provided by CSL (use REST API call: GET /customers/products/PRODUCT_ID)
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <order>
 <id>ORDER_ID</id>
 <number>ORDER_NUMBER</number>
 <status>ORDERSTATUS_VALUE</status>
 <subscriptions>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 <status>SUBSCRIPTION_STATUS</status>
 </subscription>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 <status>SUBSCRIPTION_STATUS</status>
 </subscription></subscriptions>
 </order>

5.2 Check hosted domain availability

Role Reseller or Customer
HTTP Method GET
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/domain/
URI Customer https://api.topcloudxl.com/1.0/my/domain/hosted/DOMAIN_NAME/
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No payload is needed
Item Value
DOMAIN_NAME The domain name to be checked for existence, for example: domain.com
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <domain>
 <status>DOMAIN_STATUS</status>
 </domain>

URI Encoding:

Status Value
DOMAIN_NAME The domain name must be URI encoded in order to be correctly included within the URL query string. The API will by default decode the domain name value and proceed with the check.

The domain statuses are defined in the table below.

Status Value
AVAILABLE The Domain is available and can be used during order placement
TAKEN The Domain is not available and must not be used for orders.

5.3 Place order for a subsection creation with domain name

Role Reseller or Customer
HTTP Method POST
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/orders
URI Customer https://api.topcloudxl.com/1.0/my/orders
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload
<?xml version="1.0" encoding="utf-8"?>
 <order>
 <items>
 <item>
 <type>ORDER_ITEM_TYPE</type>
 <product><id>PRODUCT_ID</id></product>
 <period><id>PERIOD_ID</id></period>
 <parameters>
 <parameter>
 <name>PARAM_NAME</name>
 <value>PARAM_VALUE</value>
 </parameter>
 </parameters>
 </item>
 </items>
 </order>
Item Value
ORDER_ITEM_TYPE CREATE
PRODUCT_ID Product identifier provided by CSL (use REST API call: GET /customers/products)
PERIOD_ID Period identifier provided by CSL (use REST API call: GET /customers/products/PRODUCT_ID)
PARAM_NAME name parameter identifier (In this case, a constant string value equals to DOMAIN_ID)
PARAM_VALUE Fully qualified domain name or subsdomain.
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <order>
 <id>ORDER_ID</id>
 <number>ORDER_NUMBER</number>
 <status>ORDERSTATUS_VALUE</status>
 <subscriptions>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 <status>SUBSCRIPTION_STATUS</status>
 </subscription>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 <status>SUBSCRIPTION_STATUS</status>
 </subscription></subscriptions>
 </order>

5.4 Place upgrade order to switch a product

Role Reseller or Customer
HTTP Method POST
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/orders
URI Customer https://api.topcloudxl.com/1.0/my/orders
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload
<?xml version="1.0" encoding="utf-8"?>
 <order>
 <items>
 <item>
 <type>ORDER_ITEM_TYPE</type>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 </subscription>
 <product>
 <id>PRODUCT_ID</id></product>
 <period>
 <id>PERIOD_ID</id></period>
 </item>
 </items>
 </order>
Item Value
ORDER_ITEM_TYPE SWITCH
SUBSCRIPTION_ID Existing subscription identifier provided by CSL (use REST API call: GET /customers/ACCOUNT_ID/subscriptions)
PRODUCT_ID Product identifier provided by CSL (use REST API call: GET /customers/products)
PERIOD_ID Period identifier provided by CSL (use REST API call: GET /customers/products/PRODUCT_ID)
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <order>
 <id>ORDER_ID</id>
 <number>ORDER_NUMBER</number>
 <status>ORDERSTATUS_VALUE</status>
 <subscriptions>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 <status>SUBSCRIPTION_STATUS</status>
 </subscription>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 <status>SUBSCRIPTION_STATUS</status>
 </subscription></subscriptions>
 </order>

5.5 Place order to change resource quantity

Role Reseller or Customer
HTTP Method POST
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/orders
URI Customer https://api.topcloudxl.com/1.0/my/orders
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload
<?xml version="1.0" encoding="utf-8"?>
 <order>
 <items>
 <item>
 <type>ORDER_ITEM_TYPE</type>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 </subscription>
 <resources>
 <resource>
 <id>RESOURCE_ID</id>
 <quantity>QUANTITY</quantity>
 </resource>
 <resource>
 <id>RESOURCE_ID</id>
 <quantity>QUANTITY</quantity>
 </resource></resources>
 </item>
 </items>
</order>
Item Value
ORDER_ITEM_TYPE UPGRADE
SUBSCRIPTION_ID Subscription identifier provided by CSL (use REST API call: GET /customers/ACCOUNT_ID/subscriptions)
QUANTITY Positive or Negative number representing ordered quantity i.e. 2.0
RESOURCE_ID Resource identifier provided by CSL
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <order>
 <id>ORDER_ID</id>
 <number>ORDER_NUMBER</number>
 <status>ORDERSTATUS_VALUE</status>
 <subscriptions>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 <status>SUBSCRIPTION_STATUS</status>
 </subscription>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 <status>SUBSCRIPTION_STATUS</status>
 </subscription></subscriptions>
 </order>

5.6 Check order status

Role Reseller or Customer
HTTP Method GET
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/orders/ORDER_
URI Customer https://api.topcloudxl.com/1.0/my/orders/ORDER_ID/status
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No Payload required
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <order>
 <id>ORDER_ID</id>
 <status>ORDERSTATUS_VALUE</status>
 </order>

5.7 Get details of an order

Role Reseller or Customer
HTTP Method GET
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/orders/ORDER_
URI Customer https://api.topcloudxl.com/1.0/my/orders/ORDER_ID
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No Payload required
Result payload
<?xml version=\"1.0\" encoding=\"UTF-8\"?>
 <order>
 <id>ORDER_ID</id>
 <number>ORDER_NUMBER</number>
 <status>STATUS_VALUE</status>
 <items>
 <item>
 <type>ITEM_TYPE</type>
 <product><id>PRODUCT_ID</id></product>
 <period><id>PERIOD_ID</id></period>
 <subscription><id>SUBSCRIPTION_ID</id></subscription>
 <resources>
 <resource>
 <id>RESOURCE_ID</id>
 <quantity>QUANTITY</quantity>
 <usedQuantity>USED_QUANTITY</usedQuantity>
 <unitOfMeasure>UNIT</unitOfMeasure>
 </resource>
 </resources>
 <parameters>
 <parameter>
 <name>PARAMETER_NAME</name>
 <value>PARAMETER_VALUE</value>
</parameter>
 </parameters>
 </item>
 </items>
 </order>

6 Subscription Management

6.1 Get subscription

Role Reseller or Customer
HTTP Method GET
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/subscriptions
URI Customer https://api.topcloudxl.com/1.0/my/subscriptions/SUBSCRIPTION_ID
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No payload is needed
Item Value
SUBSCRIPTION_ID Subscription identifier provided by CSL (use REST API call: GET /customers/ACCOUNT_ID/subscriptions)
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 <name>SUBSCRIPTION_NAME</name>
 <status>SUBSCRIPTIONSTATUS_VALUE</status>
 <product>
 <id>PRODUCT_ID</id>
 <name>PRODUCT_NAME</name>
 </product>
 <period>
 <id>PERIOD_ID</id>
 <name>PERIOD_NAME</name>
 </period><resources>
 <resource>
 <id>RESOURCE_ID</id>
 <name>RESOURCE_NAME</name>
 <quantity>QUANTITY</quantity>
 <usedQuantity>USED_QUANTITY</usedQuantity>
 <unitOfMeasure>UNIT</unitOfMeasure>
 </resource>
 <resource>
 <id>RESOURCE_ID</id>
 <name>RESOURCE_NAME</name>
 <quantity>QUANTITY</quantity>
 <usedQuantity>USED_QUANTITY</usedQuantity>
 <unitOfMeasure>UNIT</unitOfMeasure>
 </resource></resources>
 <parameters>
 <parameter>
 <name>PARAMETER_NAME</name>
 <value>PARAMETER_VALUE</value>
 </parameter>
 ...
 </parameters>
</subscription>

6.2 Disable subscription

Role Reseller or Customer
HTTP Method PUT
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/subscriptions
URI Customer https://api.topcloudxl.com/1.0/my/subscriptions/SUBSCRIPTION_ID/d
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload d No payload is needed
Item Value
SUBSCRIPTION_ID Subscription identifier provided by CSL (use REST API call: GET /customers/ACCOUNT_ID/subscriptions)
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 <status>SUBSCRIPTIONSTATUS_VALUE</status>
 </subscription>

6.3 Enable subscription

Role Reseller or Customer
HTTP Method PUT
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/subscriptions
URI Customer https://api.topcloudxl.com/1.0/my/subscriptions/SUBSCRIPTION_ID/e
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No payload is needed
Item Value
ACCOUNT_ID Account identifier provided by CSL
SUBSCRIPTION_ID Subscription identifier provided by CSL (use REST API call: GET /customers/ACCOUNT_ID/subscriptions)
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 <status>SUBSCRIPTIONSTATUS_VALUE</status>
 </subscription>

6.4 Delete subscription

Role Reseller or Customer
HTTP Method DELETE
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/subscriptions
URI Customer https://api.topcloudxl.com/1.0/my/subscriptions/SUBSCRIPTION_ID
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No payload is needed
Item Value
ACCOUNT_ID Account identifier provided by CSL
SUBSCRIPTION_ID Subscription identifier provided by CSL (use REST API call: GET /customers/ACCOUNT_ID/subscriptions)
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <subscription>
 <id>SUBSCRIPTION_ID</id>
 <status>SUBSCRIPTIONSTATUS_VALUE</status>
 </subscription>

7 Service management

7.1 Check service user existence

Role Reseller or Customer
HTTP Method GET
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/subscriptions
URI Customer https://api.topcloudxl.com/1.0/my/subscriptions/SUBSCRIPTION_ID/s
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No payload is needed
Item Value
SUBSCRIPTION_ID Subscription identifier provided by CSL (use REST API call: GET /customers/ACCOUNT_ID/subscriptions)
USER_NAME The username of a given service user. The username has the following format: user@domain
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <serviceUser>
 <status>SERVICEUSER_STATUS</status>
 </serviceUser>

URI Encoding:

Status Description
USER_NAME The username must be URI encoded in order to be correctly included within the URL query string. The API will by default decode the username value and proceed with the check.

When checking the username availability, you can have one of statuses defined in the table below.

Status Description
AVAILABLE The username is available and can be used
TAKEN The username is not available and must not be used.

7.2 Add service user

Role Reseller or Customer
HTTP Method POST
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/subscriptions
URI Customer https://api.topcloudxl.com/1.0/my/subscriptions/SUBSCRIPTION_ID/s
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload
<?xml version="1.0" encoding="utf-8"?>
 <serviceUser>
 <username>USER_NAME</username>
 <password>USER_PASSWORD</password>
 <address>
 <addressLine1>ADDRESS_LINE_1</addressLine1>
 <addressLine2>ADDRESS_LINE_2</addressLine2>
 <city>CITY</city>
 <state />
 <postalCode>POSTAL_CODE</postalCode>
 <countryCode>ADDRESS_COUNTRY_CODE</countryCode>
 </address>
 <contact>
 <firstName>FIRST_NAME</firstName>
 <lastName>LAST_NAME</lastName>
 <email>EMAIL_ADDRESS</email>
 <phone>
 <countryCode>PHONE_COUNTRY_CODE</countryCode>
 <areaCode />
 <number>PHONE_NUMBER</number>
 <extension />
 </phone>
 </contact>
</serviceUser>
Item Value
SUBSCRIPTION_ID Subscription identifier provided by CSL (use REST API call: GET /customers/ACCOUNT_ID/subscriptions)
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <serviceUser>
 <id>SERVICE_USER_ID </id>
 <status>SERVICEUSER_STATUS</status>
 </serviceUser>

7.3 Update service user details

Role Reseller or Customer
HTTP Method PUT
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/subscriptions
URI Customer https://api.topcloudxl.com/1.0/my/subscriptions/SUBSCRIPTION_ID/
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload
<?xml version="1.0" encoding="utf-8"?>
 <serviceUser>
 <username>USER_NAME</username>
 <address>
 <addressLine1>ADDRESS_LINE_1</addressLine1>
 <addressLine2>ADDRESS_LINE_2</addressLine2>
 <city>CITY</city>
 <state />
 <postalCode>POSTAL_CODE</postalCode>
 <countryCode>ADDRESS_COUNTRY_CODE</countryCode>
 </address>
 <contact>
 <firstName>FIRST_NAME</firstName>
 <lastName>LAST_NAME</lastName>
 <email>EMAIL_ADDRESS</email>
 <phone>
 <countryCode>PHONE_COUNTRY_CODE</countryCode>
 <areaCode />
 <number>PHONE_NUMBER</number>
 <extension />
 </phone>
 </contact>
 </serviceUser>
Item Value
SUBSCRIPTION_ID Subscription identifier provided by CSL (use REST API call: GET /customers/ACCOUNT_ID/subscriptions)
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <serviceUser>
 <id>SERVICE_USER_ID </id>
 <status>SERVICEUSER_STATUS</status>
 </serviceUser>

7.4 Change service user password

Role Reseller or Customer
HTTP Method PUT
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/subscriptions
URI Customer https://api.topcloudxl.com/1.0/my/subscriptions/SUBSCRIPTION_ID/
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload
<?xml version="1.0"encoding="utf-8"?>
 <serviceUser>
 <id>SERVICEUSER_ID</id>
 <oldPassword>SERVICEUSER_OLD_PASSWORD</oldPassword>
 <newPassword>SERVICEUSER_NEW_PASSWORD</newPassword>
 </serviceUser>
Item Value
SUBSCRIPTION_ID Subscription identifier provided by CSL (use REST API call: GET /customers/ACCOUNT_ID/subscriptions)
SERVICEUSER_ID The identifier of a given service user.
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <serviceUser>
 <id>SERVICEUSER_ID</id>
 <passwordStatus>
 SERVICE_USER_PASSWORD_STATUS</passwordStatus>
 </serviceUser>

When changing the password, you can have one of statuses defined in the table below.

Status Description
CHANGED The password is changed successfully and can be used.
NOT_CHANGED
<?xml version="1.0"encoding="utf-8"?>
 <serviceUser>
 <id>SERVICEUSER_ID</id>
 <passwordStatus>
 SERVICEUSER_PASSWORD_STATUS</passwordStatus>
 <reason>REASON_NOT_CHANGED_PASSWORD_MESSAGE</reason>
</serviceUser>

The password is not changed and must not be used. In this specific case, the
reason for not changing the password will be provided in the result payload as
follows:

7.5 Disable service user

Role Reseller or Customer
HTTP Method PUT
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/subscriptions
URI Customer https://api.topcloudxl.com/1.0/my/subscriptions/SUBSCRIPTION_ID/
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No payload is needed
Item Value
SUBSCRIPTION_ID Subscription identifier provided by CSL (use REST API call: GET /customers/ACCOUNT_ID/subscriptions)
SERVICEUSER_ID The identifier of a given service user.
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <serviceUser>
 <id>SERVICEUSER_ID</id>
 <status>SERVICEUSER_STATUS</status>
 </serviceUser>

7.6 Enable service user

Role Reseller or Customer
HTTP Method PUT
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/subscriptions
URI Customer https://api.topcloudxl.com/1.0/my/subscriptions/SUBSCRIPTION_ID/s
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No payload is needed
Item Value
SUBSCRIPTION_ID D Subscription identifier provided by CSL (use REST API call: GET /customers/ACCOUNT_ID/subscriptions)
SERVICEUSER_ID The identifier of a given service user.
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <serviceUser>
 <id>SERVICEUSER_ID</id>
 <status>SERVICEUSER_STATUS</status>
 </serviceUser>

7.7 List service users

Role Reseller or Customer
HTTP Method GET
URI Reseller https://api.topcloudxl.com/1.0/customers/ACCOUNT_ID/subscriptions
URI Customer https://api.topcloudxl.com/1.0/my/subscriptions/SUBSCRIPTION_ID/
HTTP Header See HTTP header table in section 2 (Authorization) with header keys and value descriptions.
Payload No payload is needed
Item Value
SUBSCRIPTION_ID Subscription identifier provided by CSL (use REST API call: GET /customers/ACCOUNT_ID/subscriptions)
Result payload
<?xml version="1.0" encoding="utf-8"?>
 <serviceUsers>
 <serviceUser>
 <id>SERVICEUSER_ID</id>
 <status>SERVICEUSER_STATUS</status>
 </serviceUser>
 <serviceUser>
 <id>SERVICEUSER_ID</id>
 <status>SERVICEUSER_STATUS</status>
 </serviceUser><serviceUsers>