CrossConnects (V2)

CrossConnects (V2) API allows an authenticated user with the required permissions to do the following: create a cross connects order request, and update the cross connects order.

 

To create a cross connects order, see Order cross connects (V2) under the Getting Started section. All other methods can be found below.

PATCH CrossConnects {orderId}

	PATCH /crossConnects/{orderId}
Method	PATCH
URL or End Point	/colocations/v2/orders/crossConnects/{orderId}
Headers	Authorization, Content-Type
Query Parameters	Not applicable
Body	{contacts [type, {registeredUsers [...]}]}

This method partially updates a specific cross connects order that is not cancelled or completed. To update this cross connects order, the authenticated user must have permissions to view all users' requests, or they must be the ordering or technical contact for this cross connects order. Currently, the user can only update the notification contacts of the order. 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 would like to update any additional information on the order besides the notification contacts, you may add notes to the order with POST Orders {orderId} Notes.

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 screenshot shows a sample curl request to update the notification contacts of the cross connects order.

curl -X
PATCH "https://api.equinix.com/colocations/v2/orders/crossConnects/1-188243137021"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "contacts": [
    {
      "registeredUser": [
        "siripala@acme.com",
        "somchai9"
      ],
      "type": "NOTIFICATION"
    }
  ]
}'

The description of the URL parameters is as follows:

URL Parameter Name	Mandatory	Type	Example	Description
orderId	Yes	string	1-188243137021	Order identifier (order ID). Order ID was returned in the response header 'Location' after the cross connects order was created. For example, 'orders/1-188243137021' would have been returned as the URL of the newly created cross connects order. This order ID is also the cross connect order number in the Equinix Customer Portal.   If you are not sure of your order ID, see How to retrieve order history? under the Getting Started.

The description of the body parameters is as follows:

Body Parameter Name	Mandatory	Type	Example	Applicable Values	Description
type	Yes	string	NOTIFICATION	NOTIFICATION	Defines the registered contact type. Type - Description NOTIFICATION - Notification contact
contacts	Yes	array [object]			Contacts array consists of the notification contact object. The contacts object contains the following parameters: registeredUsers, and type. Limit: 1 object   This notification contacts object will serve as the latest list of registered users to receive notifications for this order. All registered users included in this object will completely replace the existing list of users. If you would like to add more users to the existing list, ensure that the existing list of registered usernames are not left out in this object.
registeredUsers	Yes	array [string]	siripala@acme.com, somchai9		List of Equinix Customer Portal usernames of the registered contacts. Each string in the array represents one contact's username.   Equinix Customer Portal user's status must be approved, active, or locked. If the user's status is not any of these, the request will fail. Limit for notification contacts: 1 to 10 strings.

Cross connects order update is successful when an HTTP code of 200 is returned, and the following response header is returned. There is no response body.

HTTP Response Header Name	Description
Location	URL of the cross connects order. Example: /orders/{orderId}   'orderId' is the order identifier (ID). This is important to retrieve, update, cancel, or add notes to the order. The cross connects order ID is also known as the cross connect order number in the Equinix Customer Portal.

 

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

POST CrossConnects Deinstall

	POST /crossConnects/deinstall
Method	POST
URL or End Point	/colocations/v2/orders/crossConnects/deinstall
Headers	Authorization, Content-Type
Query Parameters	Not applicable
Body Parameters	customerReferenceId, description, details [{assetId, proceedWithLiveTraffic, patchEquipment {cabinetId, details, port}}], removalDate, purchaseOrder {type, number, amount, startDate, endDate, attachmentId}, attachments [{id, name }], contacts [{type, registeredUsers […]}, {type, firstName, lastName, availability, timezone, details [{type, value }]}]

This method initiates a cross connects deinstallation order request for the Equinix customer (A-side) in the same or different IBX locations. The A-side customer initiates this request. Only an authenticated user with Cross Connect & Intra-Facility Cables ordering permissions may create a cross connects request.

You can deinstall cross connects based on the associated A-side asset IDs. Refer to the GET Assets {assetId} endpoint to know how to get asset number ID that belongs to a cross connect.

Single or multiple assets of a cross connect can be deinstalled in a single request.

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.

DEINSTALL CROSS CONNECT ASSETS

---

The following screenshots show sample curl requests based on the following scenarios:

(A) A deinstallation order for cross connect with a single asset ID and optional parameters (minimum required information)

(B) A deinstallation order for cross connect with a multiple asset IDs (minimum required information)

The minimum required information is illustrated for each of these scenarios, and the final scenario, (C), includes all the available properties that can be passed with any of these scenarios.

(A) A deinstallation order for cross connects with a single asset ID and optional parameters (minimum required information)
A cross connects deinstallation order (an account in a single account cage), minimally requires the asset ID and removal date.
One object in the details array represents one asset of a cross connect. When placing deinstallation order request for multiple assets, pass multiple objects in the details array.

curl -X
POST "https://api.equinix.com/colocations/v2/orders/crossConnects/deinstall"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "customerReferenceId": "048837d6-4cd8-401f-ba41-a4ac015c",
   "details": [
    {
      "assetId": "4-197962310255"
    }   
   ],
  "removalDate": "2022-11-23"
}'

(B) A deinstallation order for cross connects with multiple assets IDs (minimum required information)
One object in the details array represents one asset of cross connect. When placing deinstallation order request for multiple assets, pass multiple objects in the details array.
Multiple assets of a cross connect can only be submitted in one deinstallation order request if they fulfill the following criteria:

• All assets belonging to this cross connect must come from the same A-side IBX, cage and cabinet
• Total number of assets in one request does not exceed 10

If the assets you want to deinstall do not fulfill these criteria, you need to submit separate order requests.

curl -X
POST "https://api.equinix.com/colocations/v2/orders/crossConnects/deinstall"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "customerReferenceId": "048837d6-4cd8-401f-ba41-a4ac015c",
   "description": "Deinstallation of multiple assets",
   "details": [
    {
      "assetId": "4-197962310255"
    },
    {
      "assetId": "4-197962310300"
    }   
   ],
  "removalDate": "2022-11-23"
}'

All the scenarios up to this point have illustrated the minimum required information to include in different request payloads.

In the following scenario, the cross connect deinstallation order will include all the additional attachments, information, and requests that may be included in any other scenario.

(C) A deinstallation order for cross connects with a single asset ID along with attachments, information, and requests
This deinstallation order request includes: customer reference information; live traffic information; additional Smart Hands request to patch equipment for the A-side, additional descriptions and attachments to support this deinstallation order; purchase order information to be applied to this order; and technical and notifications contacts that are different from the ordering contact.
One object in the details array represents one asset of a cross connect. When placing deinstallation order request for multiple assets, pass multiple objects in the details array.

curl -X
POST "https://api.equinix.com/colocations/v2/orders/crossConnects/deinstall"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
   "customerReferenceId": "048837d6-4cd8-401f-ba41-a4ac015c",
   "description": "Please proceed with deinstallation.",
   "details": [
    {
      "assetId": "4-180070410542",
      "proceedWithLiveTraffic": false,
      "patchEquipment": {
        "cabinetId": "AM2:01:410304:0000",
        "details": "Refer to attachment for patching details.",
        "port": 12
      }
    }
  ],  
  "removalDate": "2022-11-23",
  "purchaseOrder": {
    "type": "NEW",
    "number": "1111111111",
    "amount": 10000,
    "startDate": "2021-05-04",
    "endDate": "2022-09-30",
    "attachmentId": "4cfecaec-73c0-4a8b-805d-5b579c77f8f5"
  },
  "attachments": [
    {
      "id": "4cfecaec-73c0-4a8b-805d-5b579c77f8f5",
      "name": "DeinstallInstructions.docx"
    }
  ],
  "contacts": [
    {
      "type": "TECHNICAL",
      "firstName": "John",
      "lastName": "Doe",
      "availability": "ANYTIME",
      "timezone": "Atlantic/Canary",
      "details": [
        {
          "type": "EMAIL",
          "value": "johndoe@acme.com"
        },
        {
          "value": "+1234567890",
          "type": "PHONE"
        },
        {
          "value": "+1234567890",
          "type": "MOBILE"
        }
      ]
    },
    {
      "registeredUsers": [
        "john_doe",
        "john_doe1"
      ],
      "type": "NOTIFICATION",
      "availability": "ANYTIME",
      "timezone": "Atlantic/Canary"
    }
  ]
}' 

The description of the body parameters is as follows:

 

When 'Conditional' is indicated for a Body Parameter, refer to Description for further details.

Body Parameter Name	Mandatory	Type	Example	Applicable Values	Description
customerReferenceId	No	string	048837d6-4cd8-401f-ba41-a4ac015c		Customer's own reference ID. This information can be searched for in Order History and will appear within Reports. This is free text input. Limit: 1 to 40 characters
description	No	string	Please proceed with deinstallation.		Additional details the Equinix Technician may need to complete your request. This is free text input. Limit: 0 to 4000 characters.
details	Yes	array [objects]			List of cross connects deinstallation order details. Each element in the array represents one asset of a cross connect, and comprises the following parameters where applicable: assetId, proceedWithLiveTraffic, patchEquipment Limit: Up to 10 cross connect objects.   If your desired cross connects do not fulfil the following criteria, you need to submit separate order requests for this cross connects. All cross connects start from the same A-side IBX, cage, and cabinet.
assetId	Yes	string	4-180070410542		A-side asset ID of the cross connect you want to deinstall.
proceedWithLiveTraffic	No	boolean	false	true, false	Requirement for a cross connect removal even if live traffic is detected. If 'true', proceed with removal even if live traffic is detected. If 'false', the removal request is not required and deinstallation order will not proceed. Default value: false
patchEquipment	No	object			Device information that Equinix requires to deinstall the cross connect from demarcation panel to customer equipment, if you need to have your equipment patched. This object comprises the following parameters where applicable: cabinetId, details, port.   Smart Hands fees will apply for providing this extension.
cabinetId	Conditional	string	AM2:01:410304:0000		ID of cabinet where customer equipment for patching is located. This must belong to the specific A-side cage used in this cross connect. This is mandatory when equipment patching is required.
details	Conditional	string	Refer to attachment for patching details.		Additional device details to facilitate cross connect. This is mandatory when equipment patching is required. This is free text input. Limit: 1 to 4000 characters.
port	Conditional	number	12		Device port number. This is mandatory when equipment patching is required.
removalDate	Yes	string	2022-11-23		Requested removal date for the deinstall order. Equinix will aim to terminate this Cross Connect at this date. However it is subject to operation availability. Format: yyyy-MM-dd
purchaseOrder	No	object			Purchase order information you want to associate with this order. This object comprises the following parameters where applicable: type, number, amount, startDate, endDate, attachmentId.
type	Conditional	string	NEW	EXEMPTED, EXISTING, NEW	Purchase order type can be categorized as exempted, existing, or new. This is mandatory when including purchase order information. Type - Description EXEMPTED - You are exempted from: a) including a purchase order in your request, or b) you are applying for exemption to include a purchase order in your request. If b), see body parameter 'attachmentId'. EXISTING - You would like to use an existing blanket purchase order for this order. Body parameter 'number' is mandatory with this. NEW - You would like to use a new blanket purchase order which has not yet been applied for any order. Body parameter 'number' is mandatory with this. You can also include the following parameters: amount, startDate, endDate, attachmentId. Default: EXEMPTED
number	Conditional	string	1111111111		Purchase order number to associate with this order. This is mandatory when purchase order type is existing or new. For existing purchase orders, it the blanket purchase order number submitted throws an error, select 'EXEMPTED' for purchase order type instead.   See GET PurchaseOrders under the API Reference section to retrieve your applicable blanket purchase order number.
amount	No	number	10000		Total value amount of the new purchase order. This is only applicable when purchase order type is new.
startDate	No	string	2021-05-04		Starting date of the new purchase order. This is only applicable when purchase order type is new. Format: yyyy-MM-dd
endDate	No	string	2022-09-30		End date of the new purchase order. This is only applicable when purchase order type is new. Format: yyyy-MM-dd
attachmentId	No	string	4cfecaec-73c0-4a8b-805d-5b579c77f8f5		Attachment ID. You can attach a new purchase order document, or the Purchase Order Exemption Form. Use the document below as a template for your Purchase Order Exemption Form. Download Purchase Order Exemption Form Template. The attachment, not exceeding 5MB, can be provided in the following formats: bmp, jpg, jpeg, gif, png, tif, tiff, txt, doc, docx, xls, xlsx, ppt, pps, ppsx, pdf, and vsd. Limit: 36 characters.   This should be included when your purchase order type is new and you would like to attach the new blanket purchase order, or your purchase order type is exempted and you are submitting a Purchase Order Exemption form.   See POST Attachments File under the API Reference section for more information.
attachments	No	array [objects]			Attachments array comprising object(s) with attachment details. Each attachment object must contain the following parameters: id, name. Up to 5 attachments, each not exceeding 5MB, can be provided in the following formats: bmp, jpg, jpeg, gif, png, tif, tiff, txt, doc, docx, xls, xlsx, ppt, pps, ppsx, pdf, and vsd.   See POST Attachments File under the API Reference section for more information.
id	Conditional	string	4cfecaec-73c0-4a8b-805d-5b579c77f8f5		Attachment id. This is mandatory when an attachment is included. You will obtain this value after attaching your file using the POST Attachments File API. Limit: 36 characters.
name	Conditional	string	DeinstallInstructions.docx		Name of the attachment. This is mandatory when an attachment is included. You will obtain this value after using the POST Attachments File API, but you can change the name for your own reference when including this attachment in any order request. This is free text input. Limit: 5 to 100 characters.
contacts	No	array [objects]			Contacts array consists of the technical contact and notification contact(s) information. Equinix will be able to communicate with these contacts based on their information provided. When any of the contacts are not provided, they default to the authenticated user who submitted this order (i.e. ordering contact). Technical contact is the person who Equinix can reach out to for technical clarifications. Only one technical contact can be passed. If they are a registered Equinix Customer Portal user, only their username needs to be passed. All their contact details will be referred from their user profile in the Equinix Customer Portal. Their work hours time zone will also be referred from the user profile, unless otherwise included in this request. If they are a non-registered contact, their full name (first and last names) and contact details must be provided. To include more information such as the technical contact's availability or time zone, see parameter 'details'. Notification contact is the person who will be notified of status updates. At least one notification contact must be provided. They must be a registered Equinix Customer Portal user. Only their username needs to be passed. N/A for a non-registered contact. When providing the contact information for: Registered contact object, the following body parameters are mandatory: registeredUsers, type. All other attributes passed in a registered contact object will be ignored. Non-registered contact object, the following body parameters are mandatory: firstName, lastName, type, details. For more information on technical contact's work hours time zone, see description of body parameter, 'timezone'.
type	Conditional	string	TECHNICAL	NOTIFICATION, TECHNICAL	Defines the contact type. This is mandatory for the registered and non-registered contacts. Type - Description TECHNICAL - Technical contact (applies to both registered and non-registered contacts). NOTIFICATION - Notification contact (applies to registered contact only).
registeredUsers	Conditional	array [strings]	john_doe, john_doe1		Equinix Customer Portal username of the registered user. This is mandatory for a registered contact.   Equinix Customer Portal user's status must be approved, active, or locked. If the user's status is not any of these, the request will fail. Refer to GET Users for more information. Limit for technical contact: 1 string. Limit for notification contact(s): 1 to 10 strings.
firstName	Conditional	string	John		First name of the non-registered Technical contact. This is mandatory for a non-registered Technical contact. This is free text input.
lastName	Conditional	string	Doe		Last name of the non-registered Technical contact. This is mandatory for a non-registered Technical contact. This is free text input.
availability	Conditional	string	ANYTIME	WORK_HOURS, ANYTIME	Defines the technical contact's availability to be contacted. Availability - Description ANYTIME - Technical contact is available 24/7. WORK_HOURS - Technical contact is only available during work hours in their time zone. For a registered technical contact, their work hours is defaulted to the time zone in their user profile. If they would like to provide a different time zone, they should provide it in the body parameter 'timezone'. For a non-registered technical contact, if they select their work hours, the parameter 'timezone' is mandatory. Default value: ANYTIME
timezone	Conditional	string	Atlantic/Canary	Click here for applicable values.	Defines the time zone of the technical contact's work hours. This is mandatory when the non-registered technical contact selects their work hours as their availability. For a registered technical contact, the time zone provided here will override the time zone in the user profile only for this order request, and does not replace the time zone in their user profile. For example, selecting 'America/Detroit' specifies the technical contact's work hours.
details	Conditional	array [objects]			Array of contact details for the non-registered technical contact consisting of the type of contact detail and its value. It is mandatory to provide two types of contacts: always email address and at least one type of number, either phone or mobile. Limit: 2 to 3 objects.
type	Conditional	string	EMAIL	EMAIL, MOBILE, PHONE	Defines the contact detail type. Type - Description EMAIL - Email address. MOBILE - Mobile phone number. This is the secondary contact number. PHONE - Phone number. This is the primary contact number.
value	Conditional	string	janedoe@acme.com		Value of the contact detail type. Phone and mobile numbers must be prefixed by '+' country code. For example, +1-987-654-3210 or +1 987 654 3210. Email addresses must follow a valid email format.

Deinstallation order is successfully created when an HTTP code of 201 is returned and the following response header is returned. There is no response body.

HTTP Response Header Name	Description
Location	Location of the newly created deinstallation order. Example: /orders/{orderId}   'orderId' is the order identifier. This is important if you want to update, add notes to, retrieve and reply negotiations for, or cancel the order. It is also known as the order number in the Equinix Customer Portal.

 

If you would like to update this order, see CrossConnects (V2) in the API Reference Section for more information.

If you would like to add notes to this order, retrieve and reply negotiations for this order, or cancel this order, see Orders (V2 Beta) in the API Reference Section for more information.

 

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