Skip to main content
Index

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
 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 Started section.

 

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

 

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

 

 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.'

 

{
  "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).

 

{
  "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.'

 

{
  "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.

 

{
  "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.