SupportPlans (V2 Beta)

Equinix Smart Hands™ Support Plans allow you to prepay for Smart Hands hours at a discount. SupportPlans (V2 Beta) API allows an authenticated user with the required permission to retrieve their available support plans.

See Smart Hands Support Plans for more information.

GET SupportPlans

	GET /supportPlans
Method	GET
URL or End Point	/colocations/v2/supportPlans
Headers	Authorization, Content-Type
Query Parameters	accountNumbers, ibxs, offset, limit, sorts, planIds
Body	Not applicable

This method retrieves a summary of Smart Hands support plans for the active months and year based on your search criteria. Only an authenticated user with Smart Hands support plan notifications permission may view these support plans. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.

The following screenshots show a sample curl request and successful JSON responses for different types of support plans.

Copy

curl -X
GET "https://api.equinix.com/colocations/v2/supportPlans?accountNumbers=111111,123456&ibxs=AM1,AM2&offset=0&limit=3&sorts=ASSET_NUMBER"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

The description of the query parameters is as follows:

Query Parameter name	Mandatory	Type	Example	Applicable Values	Description
accountNumbers	No	array [strings]	111111, 123456		Account numbers associated with the support plans. Multiple account numbers should be comma-separated. Default value: all user's permitted account numbers
ibxs	No	array [strings]	AM1, AM2		IBX location codes of the associated IBX data centers. Multiple IBXs should be comma-separated. Default value: all user's permitted IBXs
offset	No	integer	0		Defines the index of the first item returned in the response. By specifying the offset, the response returns a subset of records starting with the offset value. For example, if the offset is 10, the starting item returned in the response would be the 11th item. Default value: 0
limit	No	integer	3		Defines the maximum number of items returned per page. Default value: 10 Limit: 1 to 100
sorts	No	array [strings]	ID	ACCOUNT_NUMBER, ID, PLAN_NAME, START_DATE, END_DATE, -ACCOUNT_NUMBER -ID, -START_DATE, -END_DATE, -PLAN_NAME	Sorting preference for the returned list of support plans. Sorts - Description ACCOUNT_NUMBER - Support plans will be returned in ascending alphanumeric order of their associated account number. ID - Support plans will be returned in ascending alphanumeric order of their associated Equinix asset number or ID. PLAN_NAME - Support plans will be returned in ascending alphanumeric order of their plan name. START_DATE - Support plans will be returned in ascending chronological order of their start date. END_DATE - Support plans will be returned in ascending chronological order of their end date. When these sorts values are prefixed by '-' support plans will be returned in descending order instead. Default value: ACCOUNT_NUMBER
planIds	No	array [strings]	12_0101529685		Allows filtering existing support plans based on plan ID. Multiple plan IDs should be comma-separated. You can provide up to 10 plan IDs.

These are the different types of support plans that can be returned in your response payload:

Monthly plan
Monthly rollover plan
Prepaid plan
Plan of any type for a reseller account

Monthly plan
All the fields returned in this sample response payload are applicable for monthly support plans. This support plan type can be identified by the plan frequency 'MONTHLY.'

Copy

{
    "data": [
        {
        "id": "4-111111111111",
        "accountNumber": "111111",
        "planName": "Monthly Smart Hands Support Plan",
        "productCode": "PS00022.ELEM",
        "ibxs": [
            "AM1",
            "AM2"
        ],
        "ibxSpecific": false,
        "planFrequency": "MONTHLY",
        "purchasedMinutes": 10800,
        "assignedMinutes": 10800,
        "consumedMinutes": 1980,
        "remainingMinutes": 8820,
        "currentConsumedMinutes": 1980,
        "startDate": "2021-03-01",
        "endDate": "2021-03-31",
        "status": "ACTIVE",
        "createdDateTime": "2021-03-01T00:00:00Z",
        "updatedDateTime": "2021-03-15T16:22:56Z"
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 2,
        "total": 1,
        "next": "/supportPlans?accountNumbers=111111,222222&ibxs=AM1,AM2&sorts=ASSET_NUMBER&limit=2&offset=0",
        "previous": "/supportPlans?accountNumbers=111111,222222&ibxs=AM1,AM2&sorts=ASSET_NUMBER&limit=2&offset=2"
    }
}

Monthly rollover plan
All the fields returned in this sample response payload are applicable for monthly rollover support plans. This support plan type can be identified by the plan frequency 'MONTHLY_ROLLOVER.' Once the rollover plan has passed its first month, two plan names associated with the same support plan ID will be returned; Monthly Smart Hands Support Plan (this represents the current month), and Monthly Smart Hands Support Plan [Rollover] (this represents the previous month which has remaining minutes that can be rolled over).

Copy

{
    "data": [
        {
            "id": "4-111111111111",
            "accountNumber": "111111",
            "planName": "Monthly Smart Hands Support Plan",
            "productCode": "PS00022.ELEM",
            "ibxs": [
                "AM1",
                "AM2"
            ],
            "ibxSpecific": false,
            "planFrequency": "MONTHLY_ROLLOVER",
            "purchasedMinutes": 10800,
            "assignedMinutes": 10800,
            "consumedMinutes": 1980,
            "remainingMinutes": 8820,
            "previousConsumedMinutes": 0,
            "currentConsumedMinutes": 1980,
            "startDate": "2021-03-01",
            "endDate": "2021-04-30",
            "status": "ACTIVE",
            "createdDateTime": "2021-03-01T00:00:00Z",
            "updatedDateTime": "2021-03-15T16:22:56Z",
            "assignment": {
                "status": "UNASSIGNED",
                "eligible": false
            }
        },

        {
            "id": "4-111111111111",
            "accountNumber": "111111",
            "planName": "Monthly Smart Hands Support Plan (Rollover)",
            "productCode": "PS00022.ELEM",
            "ibxs": [
                "AM1",
                "AM2"
            ],
            "ibxSpecific": false,
            "planFrequency": "MONTHLY_ROLLOVER",
            "purchasedMinutes": 10800,
            "consumedMinutes": 0,
            "remainingMinutes": 10800,
            "previousConsumedMinutes": 0,
            "currentConsumedMinutes": 0,
            "startDate": "2021-02-01",
            "endDate": "2021-03-31",
            "status": "ACTIVE",
            "createdDateTime": "2021-03-01T00:00:00Z",
            "updatedDateTime": "2021-03-15T16:22:56Z"
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 3,
        "total": 2,
        "next": "/supportPlans?accountNumbers=111111,222222&ibxs=AM1,AM2&sorts=ASSET_NUMBER&limit=3&offset=0",
        "previous": "/supportPlans?accountNumbers=111111,222222&ibxs=AM1,AM2&sorts=ASSET_NUMBER&limit=3&offset=0"
    }
}

Prepaid plan
All the fields returned in this sample response payload are applicable for prepaid support plans. This support plan type can be identified by the plan frequency 'ANNUAL.'

Copy

{
    "data": [
        {
            "id": "4-111111111111",
            "accountNumber": "111111",
            "planName": "Prepaid Smart Hands Hours",
            "productCode": "PS00021.ELEM",
            "ibxs": [
                "AM1",
                "AM2"
            ],
            "ibxSpecific": false,
            "planFrequency": "ANNUAL",
            "purchasedMinutes": 10800,
            "assignedMinutes": 10800,
            "consumedMinutes": 1980,
            "remainingMinutes": 8820,
            "prepaidConsumedMinutes": 1980,
            "startDate": "2021-03-01",
            "endDate": "2022-02-28",
            "status": "ACTIVE",
            "createdDateTime": "2021-03-01T00:00:00Z",
            "updatedDateTime": "2021-03-15T16:22:56Z"
       }
    ],
    "pagination": {
        "offset": 0,
        "limit": 2,
        "total": 1,
        "next": "/supportPlans?accountNumbers=111111,222222&ibxs=AM1,AM2&sorts=ASSET_NUMBER&limit=2&offset=0",
        "previous": "/supportPlans?accountNumbers=111111,222222&ibxs=AM1,AM2&sorts=ASSET_NUMBER&limit=2&offset=2"
    }
}

Reseller assigned plans
This scenario is specific only to resellers who can assign their support plans to their own customers. In this sample response payload, the data returned shows that the reseller's monthly support plan with "id": "4-111111111111" had been reassigned from Customer_A to the reseller, and then to Customer_Z.

Copy

{
    "data": [
        {
            "id": "4-111111111111",
            "accountNumber": "111111",
            "planName": "Monthly Smart Hands Support Plan",
            "ibxs": [
                "AM1",
                "AM2"
            ],
            "ibxSpecific": false,
            "planFrequency": "MONTHLY",
            "purchasedMinutes": 10800,
            "assignedMinutes": 10800,
            "consumedMinutes": 1980,
            "remainingMinutes": 8820,
            "currentConsumedMinutes": 1980,
            "transitionMinutes": 8820,
            "startDate": "2021-03-15",
            "endDate": "2021-03-31",
            "status": "ACTIVE",
            "createdDateTime": "2021-03-01T00:00:00Z",
            "updatedDateTime": "2021-03-15T16:22:56Z",
            "assignment": {
                "status": "ASSIGNED",
                "eligible": true,
                "accountNumber": "999999",
                "name": "Customer_Z"
            }
        },
        {
            "id": "4-111111111111",
            "accountNumber": "111111",
            "planName": "Monthly Smart Hands Support Plan",
            "ibxs": [
                "AM1",
                "AM2"
            ],
            "ibxSpecific": false,
            "planFrequency": "MONTHLY",
            "purchasedMinutes": 10800,
            "assignedMinutes": 10800,
            "consumedMinutes": 1980,
            "remainingMinutes": 8820,
            "currentConsumedMinutes": 1980,
            "transitionMinutes": -8820,
            "startDate": "2021-03-15",
            "endDate": "2021-03-15",
            "status": "CANCELLED",
            "createdDateTime": "2021-03-01T00:00:00Z",
            "updatedDateTime": "2021-03-15T16:22:56Z",
            "assignment": {
                "status": "CANCELLED",
                "eligible": true
            }
        },
        {
            "id": "4-111111111111",
            "accountNumber": "111111",
            "planName": "Monthly Smart Hands Support Plan",
            "ibxs": [
                "AM1",
                "AM2"
            ],
            "ibxSpecific": false,
            "planFrequency": "MONTHLY",
            "purchasedMinutes": 10800,
            "assignedMinutes": 10800,
            "consumedMinutes": 1980,
            "remainingMinutes": 8820,
            "currentConsumedMinutes": 1980,
            "transitionMinutes": -8820,
            "startDate": "2021-03-01",
            "endDate": "2021-03-15",
            "status": "ACTIVE",
            "createdDateTime": "2021-03-01T00:00:00Z",
            "updatedDateTime": "2021-03-15T12:20:56Z",
            "assignment": {
                "status": "CANCELLED",
                "eligible": true,
                "accountNumber": "222222",
                "name": "Customer_A"
            }
        }
    ],
    "pagination": {
        "offset": 0,
        "limit": 3,
        "total": 3,
        "next": "/supportPlans?accountNumbers=111111,222222&ibxs=AM1,AM2&sorts=ASSET_NUMBER&limit=3&offset=0",
        "previous": "/supportPlans?accountNumbers=111111,222222&ibxs=AM1,AM2&sorts=ASSET_NUMBER&limit=3&offset=0"
    }
}

The description of the response payload is as follows:

Field name	Type	Example	Description
data	array [objects]		Data returned from your query. Each billing document object comprises the following fields where applicable: id, accountNumber, planName, ibxs, ibxSpecific, planFrequency, purchasedMinutes, assignedMinutes, consumedMinutes, remainingMinutes, prepaidConsumedMinutes, previousConsumedMinutes, currentConsumedMinutes, startDate, endDate, status, createdDateTime, updatedDateTime, assignment.
id	string	4-111111111111	Equinix ID of the support plan, also known as Equinix asset number.
accountNumber	string	111111	Account number.
planName	string	Monthly Smart Hands Support Plan	Name of your Smart Hands support plan. Currently, the following plan names are returned. Prepaid Smart Hands Hours Monthly Smart Hands Support Plan Monthly Smart Hands Support Plan (Rollover) Dependency on this plan name should be avoided and the field 'planFrequency' should be viewed to verify your plan type instead.
productCode	string	PS00022.ELEM	Equinix product catalog code of your support plan.
ibxs	array [strings]	AM1, AM2	Associated IBX location codes.
ibxSpecific	boolean	false	Indicates if the support plan is only applicable to a specific IBX. When true, the plan is applicable only to the IBX location code listed in field 'ibxs.' When false, the plan is not limited to a single IBX.
planFrequency	string	MONTHLY	Frequency of the support plan. Plan frequency - Description MONTHLY - This is a subscription plan with pre-bundled hours renewed on a monthly basis. Any unused pre-paid hours remaining at the end of the applicable period will expire, and will not be refunded or rolled over to the following period. MONTHLY_ROLLOVER - This plan is similar to the MONTHLY support plan type, except that any unused pre-paid hours remaining at the end of the applicable period will roll over for one additional thirty day period. Smart Hands hours from the current period will be consumed first, followed by any roll over hours. Any roll over hours that remain unused at the end of the applicable month will expire and will not be refunded or rolled over to the following period. ANNUAL - This is a one-time purchase plan with a twelve month term that does not auto-renew.
purchasedMinutes	integer	10800	Contracted pre-purchased minutes for your specific plan.
assignedMinutes	integer	10800	Pre-purchased minutes applicable for the specified time period (defined by the fields 'startDate' and 'endDate'). When MONTHLY or MONTHLY_ROLLOVER plans have a start date after the first day the month, the assigned minutes are prorated to reflect this. Otherwise, the assigned minutes of any plan is the same as its purchased minutes.
consumedMinutes	integer	1980	Number of minutes consumed for the specified time period.
remainingMinutes	integer	8820	Number of minutes left for the specified time period.
previousConsumedMinutes	integer	0	Number of minutes consumed in the previous month. This is only applicable for plans with plan frequency 'MONTHLY_ROLLOVER.'
currentConsumedMinutes	integer	1980	Number of minutes consumed in the current month. This is only applicable for plans with plan frequency 'MONTHLY' and 'MONTHLY_ROLLOVER.'
prepaidConsumedMinutes	integer	1980	Number of prepaid minutes consumed in the current month. This is only applicable for plans with plan frequency 'ANNUAL.'
transitionMinutes	integer	8820	Number of minutes that has been transitioned. This is only applicable for reseller accounts. When the value is positive, the minutes have not been transferred, and are applicable to this account. When the value is negative, the minutes have been transferred, and are no longer applicable to this account.
startDate	string	2021-03-01	Start date of the applicable month or year. Format: YYYY-MM-DD.
endDate	string	2021-03-31	End date of the applicable month or year. Format: YYYY-MM-DD.
status	string	ACTIVE	Status of the support plan, which can be ACTIVE or CANCELLED.
createdDateTime	string	2021-03-01T00:00:00Z	Date and time the support plan was created. ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssZ.
updatedDateTime	string	2021-03-15T16:22:56Z	Date and time the support plan was last updated. ISO 8601 format: yyyy-MM-dd'T'HH:mm:ssZ.
assignment	object		Assignment details of your support plan. This object comprises the following fields where applicable: status, eligible, accountNumber, name. This is only applicable to resellers.
status	string	ASSIGNED	Assignment status of your support plan. Status - Description ASSIGNED - This support plan is currently assigned to your customer. UNASSIGNED - This support plan is not been assigned to any customer. PENDING_ASSIGNED - This support plan was just assigned to a customer, pending finalization. PENDING_UNASSIGNED - This support plan was just unassigned from a customer, pending finalization. CANCELLED - This support plan was cancelled for your account, and assigned to a customer.
eligible	boolean	true	Indicates if this plan is eligible for assignment. When true, plan can be assigned. This is only applicable for plans purchased after August 2020. When false, plan cannot be assigned. Plans purchased before August 2020 are not assignable.
accountNumber	string	999999	Customer account number.
name	string	Customer_Z	Customer account name
pagination	object		Page information. This object comprises the following fields: offset, limit, total, next, previous.
offset	integer	0	Offset of the first item in the response.
limit	integer	2	Maximum number of items in the response.
total	integer	1	Total number of available items in the record.
next	string	/supportPlans?accountNumbers=111111,222222 &ibxs=AM1,AM2&sorts=ASSET_NUMBER &limit=2&offset=0	URL for the next page of results.
previous	string	/supportPlans?accountNumbers=111111,222222 &ibxs=AM1,AM2&sorts=ASSET_NUMBER &limit=2&offset=2	URL for the previous page of results.

If you get “Insufficient permissions” error, contact your Master Administrator.

GET SupportPlans

Was this documentation helpful?