Search

Page tree
Skip to end of metadata
Go to start of metadata

Table of Contents


Overview



The interworks.cloud BSS API is designed to enable 3rd party application to apply several actions available through interworks.cloud BSS by simple RESTFul calls.

API Responses

Currently interworks.cloud BSS API supports JSON format as output and uses standard HTTP status codes to indicate success or failure of API calls.

The following table contains some common HTTP status codes.

 

HTTP CodeMessageDescription
200OKThe request was processed and returned successfully. Nothing was changed.
201CreatedThe new resource was created successfully
400Bad RequestProblem with the request, such as a missing, invalid or type mismatched parameter
401UnauthorizedThe request did not have valid authorization credentials
403ForbiddenPrivate data you are not allowed to access, or you've hit a rate limit.
404Not FoundYour URL is wrong, or the requested resource doesn't exist
500Server ErrorWe call this the "crap code" error. Basically we've got a problem on our side. If this persists please contact support. We log and review all errors but your help often helps us fix it quicker.
503Service UnavailableOur API is down. Please try again. We work hard to make this rare.

 

Authorization / Authentication

Check Authorization & Authentication for Billing and BSS API for details

Pagination / Pagination metadata

Check interworks.cloud BSS API for details

API Methods

Accounts

Get Synchronization Options

This API call returns the synchronization options for a specific system for an account.

API Call:

GET: https://<host_name>/api/Accounts/{accountid}/syncoptions/{systemcode}

Parameters:

ParameterDescriptionTypeConstraints
accountidThe id of the accountintrequired
systemcodeThe code of the systemstringoptional

Call Examples:

Call example to load sync options of an account for all systems.

GET: https://<host_name>/api/Accounts/151/syncoptions

Basic type

Synchronization Options for account with id = 151
[
    {
        "systemId": 1,
        "options": [
            {
                "name": "Role",
                "value": "",
                "alias": "Role"
            },
            {
                "name": "User Name",
                "value": "",
                "alias": "UserName"
            }
        ]
    },
    {
        "systemId": 2,
        "options": [
            {
                "name": "Role",
                "value": "",
                "alias": "Role"
            },
            {
                "name": "User Name",
                "value": "",
                "alias": "UserName"
            }
        ]
    },
    {
        "systemId": 3,
        "options": [
            {
                "name": "Username",
                "value": "",
                "alias": "username"
            }
        ]
    }
]

 

Call example to load sync options of an account for a specific system.

GET: https://<host_name>/api/Accounts/151/syncoptions/oss    

Basic type

Synchronization options for account with id = 151 and system code "oss"
[
    {
        "systemId": 1,
        "options": [
            {
                "name": "Role",
                "value": "",
                "alias": "Role"
            },
            {
                "name": "User Name",
                "value": "",
                "alias": "UserName"
            }
        ]
    }
]

 

Get Billing Address

This API call returns the billing address info for an account

API Call:

GET: https://<host_name>/api/Accounts/{accountid}/Billingaddress

Parameters:

ParameterDescriptionTypeConstraints
accountIdThe id of the accountintrequired

Call Example:

Call example to load billing address of a specific account with id = 151

 GET: https://<host_name>/api/Accounts/151/Billingaddress

Basic Type

Billing Address for account with id=151
{
    "id": "15d1e6b6-fc2c-45e5-8389-5ff2d3f78c66",
    "name": "Billing Address",
    "address1": "Address 1",
    "address2": "Address 1",
    "city": "City",
    "region": "Alabama",
    "postCode": "54444",
    "country": "United States",
    "countryCode": "US",
    "isBilling": true
}

 

Get Account Subscriptions

This API call returns the subscriptions of a specific account for a specific product

API Call:

GET: https://<host_name>/api/Accounts/{accountId}/subscriptions/{productId}

Parameters:

ParameterDescriptionTypeConstraints
accountIdThe id of the accountintrequired
productIdThe id of the productstringrequired

Call Example:

Call example to load subscriptions of account with id = 151 and for product id = E3F1D15D-2531-499E-80E6-C6C768613CA3 

GET: https://<host_name>/api/Accounts/151/subscriptions/E3F1D15D-2531-499E-80E6-C6C768613CA3

Basic type

Subscription for account with id = 151 and for product with id = E3F1D15D-2531-499E-80E6-C6C768613CA3
[
    {
        "id": "32264C6B-B6BB-4058-908F-0F8DD438F990",
        "externalId": "2103213618",
        "productId": "E3F1D15D-2531-499E-80E6-C6C768613CA3",
        "quantity": "1",
        "stageType": "Active",
        "account": {
            "id": "151",
            "externalId": "2103213618"
        },
        "billingAccount": {
            "id": "151",
            "externalId": "2103213618"
        }
    },
    {
        "id": "D0FDB9C4-102F-4FF9-AB01-37690BDFF2EE",
        "externalId": "2103213618",
        "productId": "E3F1D15D-2531-499E-80E6-C6C768613CA3",
        "quantity": "1",
        "stageType": "Suspended",
        "account": {
            "id": "151",
            "externalId": "2103213618"
        },
        "billingAccount": {
            "id": "151",
            "externalId": "2103213618"
        }
    }
]

 

Get Account Service Totals

Given an external system service type (external's system product type id), this API call returns the service quotas of an account calculated by the subscriptions acquired and their characteristics.

API Call:

GET: https://<host_name>/api/accounts/<account_id>/subscriptions/totals?serviceType=<servicetype>&systemName=<systemname>
or
GET: https://<host_name>/api/accounts/<account_id>/subscriptions/totals?serviceType=<servicetype>&systemCode=<systemcode>

Parameters:

ParameterDescriptionTypeConstraints
accountIdThe id of the accountintrequired
servicetypeThe identifier of the product type used during get service definitionstringrequired
systemnameThe name of the target external system as appeared in Settings page in BSS Setupstringoptional
systemcodeThe code of the target external system. In case of multiple instances, the first one will be used.stringoptional

Call Example:

Call example to get service quotas of account with id = 151 and for service 'Cloud Storage' (servicetype='cloudstorage') from external system with name 'Cloud Backup' (systemcode=cloudbackup)

GET: https://<host_name>/api/accounts/151/subscriptions/totals?serviceType=backupstorage&systemName=Cloud%20Backup
or
GET: https://<host_name>/api/accounts/151/subscriptions/totals?serviceType=backupstorage&systemCode=cloudbackup
Totals for account id =151 and service type = cloudstorage
{
	"totalSubscriptions": 2,
	"totalQuantity": 3,
	"totals": {
		"id": "storage",
		"name": "Storage (GB)",
		"value": "18"
	}
}


Get Account Service Totals by Subscription

Given a subscription, this API call returns the service quotas of an account calculated by the subscriptions acquired and their characteristics.

API Call:

GET: https://<host_name>/api/accounts/<account_id>/subscriptions/<subscription_id>/totals

Parameters:

ParameterDescriptionTypeConstraints
accountIdThe id of the accountintrequired
subscriptionIdThe id of the target subscriptionstringrequired

Call Example:

Call example to get service quotas of account with id = 151 and for subscription id = 'E3F1D15D-2531-499E-80E6-C6C768613CA3'

GET: https://<host_name>/api/accounts/151/subscriptions/E3F1D15D-2531-499E-80E6-C6C768613CA3/totals
Totals for account id =151 and subscription id = E3F1D15D-2531-499E-80E6-C6C768613CA3
{
	"totalSubscriptions": 2,
	"totalQuantity": 3,
	"totals": {
		"id": "storage",
		"name": "Storage (GB)",
		"value": "18"
	}
}


Subscriptions

Get Subscription's Attributes

This API call returns the attributes of a specific subscription

API Call:

GET: https://<host_name>/api/Subscriptions/{subscriptionId}/attributes

Parameters:

ParameterDescriptionTypeConstraints
subscriptionIdthe id of the subscriptionstringrequired

Call Example:

Call example to load the attributes of the subscription with id = D0FDB9C4-102F-4FF9-AB01-37690BDFF2EE

GET: https://<host_name>/api/Subscriptions/D0FDB9C4-102F-4FF9-AB01-37690BDFF2EE/attributes

Basic type

Attributes of the subscription with id = D0FDB9C4-102F-4FF9-AB01-37690BDFF2EE
{
    "attributes": [
        {
            "id": "07BD83B8-9AB4-49EA-9B44-30103C857128",
            "externalId": "valueCheckbox",
            "name": "Bool value",
            "value": "1",
            "valueExternal": "",
            "code": ""
        },
        {
            "id": "C2B50D1D-D232-4EBF-8780-0DB202014FAB",
            "externalId": "valueList",
            "name": "List value",
            "value": "Value 2",
            "valueExternal": "valueList_2",
            "code": "2"
        },
        {
            "id": "BC71C8DB-5160-4A7A-A331-4A1D2519E16D",
            "externalId": "valueCheckboxes",
            "name": "Multiple checkboxes value",
            "value": "Value 1; Value 2",
            "valueExternal": "valueCheckboxes_2;valueCheckboxes_1",
            "code": ""
        },
        {
            "id": "6BAFFCAF-D832-42FC-8F33-CB23D9753412",
            "externalId": "valueNumeric",
            "name": "Numeric value",
            "value": "1.000000",
            "valueExternal": "",
            "code": ""
        }
    ]
}

Get Subscriptions By Activation Date And Product Code

This API call returns the subscriptions which were activated in a given date for a given product code.

API Call:

GET: https://<host_name>/api/subscriptions/?activationDate=<activation_date>&productCode=<product_code>&page=<page_number>&size=<page_size>

Parameters:

ParameterDescriptionTypeConstraints
activationDate
Activation date of the subscriptionsdaterequired
productCode
The code of the productstringrequired
page
The number of the page to be displayed (default: 1)intoptional
size
The number of items per page (default: 25)intoptional

Call Examples:

Call example to get all the subscriptions for the product AZPRD001 which were activated in 26/09/2016.

GET: https://<host_name>/api/subscriptions/?activationDate=2016-09-26&productCode=AZPRD001


Response:

This API call will return a list of subscriptions:

[
   {
      "id":"6d0ab8fe-a194-4aef-85d2-5953835705d0",
      "name":"Azure Subs",
      "startDate":"2016-09-26T00:00:00+02:00",
      "endDate":"2016-09-30T23:59:00+02:00",
      "signupDate":"2016-09-26T00:00:00+02:00",
      "createdDate":"2016-09-26T00:00:00+02:00",
      "stage":"Active",
      "quantity":1,
      "unit":"Monthly",
      "isTrial":false,
      "billingOption":"OnSubscriptionStart",
	  "description": "",
      "isRenewAutomatically": false, 
	  "account":{
         "id":1051,
         "name":"Customer"
      },
      "billingAccount":{
         "id":1051,
         "name":"Customer"
      },
      "contact":{
         "id":1040,
         "name":"Primary Customer Contact"
      },
      "product":{
         "id":"f27691eb-1a9b-4030-9c9c-8549eb6e9fac",
         "code":"AZPRD001",
         "name":"Azure Product 1"
      }
   }
]
 
(*) billingOption could be: OnSubscriptionStart, OnSubscriptionEnd


Addons

Get Addon's Attributes

This API call returns the attributes of a specific addon

API Call:

GET: https://<host_name>/api/Addons/{addonId}/attributes

Parameters:

ParameterDescriptionTypeConstraints
addonId
the id of the addonstringrequired

Call Example:

Call example to load the attributes of the addon with id = 62A821D2-E3F8-4C50-803D-55ED2CCEC589

GET: https://<host_name>/api/Addons/62A821D2-E3F8-4C50-803D-55ED2CCEC589/attributes

Basic type

Attributes of the addon with id = 62A821D2-E3F8-4C50-803D-55ED2CCEC589
{
    "attributes": [
        {
            "id": "07BD83B8-9AB4-49EA-9B44-30103C857128",
            "externalId": "valueCheckbox",
            "name": "Bool value",
            "value": "1",
            "valueExternal": "",
            "code": ""
        },
        {
            "id": "C2B50D1D-D232-4EBF-8780-0DB202014FAB",
            "externalId": "valueList",
            "name": "List value",
            "value": "Value 2",
            "valueExternal": "valueList_2",
            "code": "2"
        },
        {
            "id": "BC71C8DB-5160-4A7A-A331-4A1D2519E16D",
            "externalId": "valueCheckboxes",
            "name": "Multiple checkboxes value",
            "value": "Value 1; Value 2",
            "valueExternal": "valueCheckboxes_2;valueCheckboxes_1",
            "code": ""
        },
        {
            "id": "6BAFFCAF-D832-42FC-8F33-CB23D9753412",
            "externalId": "valueNumeric",
            "name": "Numeric value",
            "value": "1.000000",
            "valueExternal": "",
            "code": ""
        }
    ]
}

Leads

Create Lead

This API call creates a new Lead.

API Call:

POST: https://<host_name>/api/Leads

Parameters:

ParameterTypeConstraints
FirstNamestringoptional
LastNamestringrequired
Statusstringrequired
MiddleNamestringoptional
Titlestringoptional
JobTitlestringoptional
Compellationstringoptional
Companystringoptional
Industrystringoptional
AnnualRevenuenumericoptional
Sourcestringoptional
Ratingstringoptional
Phonestringoptional
Mobilestringoptional
Faxstringoptional
Emailstringoptional
WebSitestringoptional
EmployeeNumbernumericoptional
Address1stringoptional
Address2stringoptional
Citystringoptional
Countrystringoptional
Statestringoptional
PostCodestringoptional
Commentsstringoptional



API Objects

Api methods return one or more json object as provided in details in the following paragraphs.

Object: SyncOptions

Represents a set of options that used in order to synchronize an account with an external system.

{
        "systemId": 1,
        "options": [
            {
                "name": "Role",
                "value": "",
                "alias": "Role"
            },
            {
                "name": "User Name",
                "value": "",
                "alias": "UserName"
            }
        ]
    }
systemIdExternal system identifier as configured in interworks.cloud BSS
option:nameDisplay name of sync option
option:valueValue of sync option or empty string if not available
option:aliasAlias of sync option as defined during get service definition proccess

Object: AccountAddress

Represents the billing address info of an account.

{
    "id": "15d1e6b6-fc2c-45e5-8389-5ff2d3f78c66",
    "name": "Billing Address",
    "address1": "Address 1",
    "address2": "Address 1",
    "city": "City",
    "region": "Alabama",
    "postCode": "54444",
    "country": "United States",
    "countryCode": "US",
    "isBilling": true
}
IdAccount address identifier for interworks.cloud BSS
nameDisplay name of account's address
address1First line of address
address2Second line of address
cityThe city defined for the address
regionThe region defined for the address
postcodeThe postcode defined for the address
countryThe full country name defined for the address
countryCodeThe ISO 2-letter country code defined for the address
isBilling

true in case the address is used as billing address for the account,

false otherwise

Object: Subscription

Represents the billing address info of an account.

{
        "id": "32264C6B-B6BB-4058-908F-0F8DD438F990",
        "externalId": "2103213618",
        "productId": "E3F1D15D-2531-499E-80E6-C6C768613CA3",
        "quantity": "1",
        "stageType": "Active",
        "account": {
            "id": "151",
            "externalId": "2103213618"
        },
        "billingAccount": {
            "id": "151",
            "externalId": "2103213618"
        }
    }
IdSubscription identifier for interworks.cloud BSS
externalId

Subscription identified for the related External System, or empty if no related external system.

productIdThe subscription's product identifier for interworks.cloud BSS
quantityThe quantity of the subscription
stageType

Active: for active status

Suspended: for suspended status

Inactive: for inactive status

Cancelled: for cancelled status

Pending Cancellation: for pending cancellation status

account:idAccount identifier for interworks.cloud BSS
account:externalIdAccount identifier for External System
billingAccount:idBilling account identifier for interworks.cloud BSS
billingAccount:externalIdBilling account identifier for External System

Object: ServiceAttribute

Represents a value selected for a specific characteristic of a subscription or an addon.

{
            "id": "C2B50D1D-D232-4EBF-8780-0DB202014FAB",
            "externalId": "valueList",
            "name": "List value",
            "value": "Value 2",
            "valueExternal": "valueList_2",
            "code": "2"
        }
idAttribute identifier for interworks.cloud BSS
externalIdAttribute identifier for External System
nameDisplay name of the attribute
value

For text characteristic, the text typed by the user.

For numeric characteristic, the number completed by the user.

For date characteristic, the date selected by the user.

For slider characteristic, the number selected by the user.

For checkbox characteristic, value '1' if checked by the user, value '0' otherwise.

For dropdown characteristic, selected value's text.

For multiple selection (checkboxes) characteristics, the selected values's text.

valueExternal

For dropdown characteristic, the external system value related with the value selected by the user.

For multiple selection (checkboxes) characteristics, the external system values related with the values selected by the user.

Empty string otherwise.

code

For dropdown characteristic, the code related with the value selected by the user.

For multiple selection (checkboxes) characteristics, the codes related with the values selected by the user.

Empty string otherwise.

 

 

2 Comments

  1. Προστέθηκε το 'Sample Application for .NET Client' και ενημερώθηκε η λίστα των API Methods με βάση την τελική υλοποίηση.

  2. Προστέθηκε αναφορά στα HTTP status codes στην παράγραφο API Responses, προστέθηκαν τα API Objects και η πληροφορία 'Basic type' σε κάθε κλήση.